Authentication

Plane Compose saves credentials as connections. A connection is a server URL plus an API token. Each connection has one or more workspaces (slugs) linked to it, and one workspace can be the default. Connections live in ~/.config/plane-compose/config.json with owner-only permissions (0600); if the file's permissions are looser, Plane Compose tightens them and prints a warning.

One connection can serve several workspaces, for example several workspaces on the same server with one personal access token.

auth login

Confirm. Checks a token against a workspace and saves the connection.

Flag	What it controls
--server-url	Plane API server, for example https://api.plane.so. Blank input falls back to that. A URL without a scheme gets https://. A plain http:// URL to a non-local host prints an insecure-connection warning.
--auth-type	pat (or 1) for a personal access token; workspace (or 2) for a workspace token.
--token	The API token. Must be at least 10 characters.
-w, --workspace	Workspace slug to link.
-c, --connection	Connection name. If you leave it out, you're asked for it (suggested default connection-N) even when every other flag is set. Always pass it in scripts.

With none of --server-url, --auth-type, --token or --workspace, login is fully interactive and asks for every value. With --workspace, it asks only for what's missing, including the connection name unless you pass -c.

Before saving, login calls GET <server>/api/v1/workspaces/<slug>/projects/ with the token. If that fails, nothing is saved. Both token types are sent in the X-Api-Key header.

plane auth login
plane auth login --server-url https://plane.example.com --auth-type workspace \
  --token "$PLANE_TOKEN" --workspace myteam -c prod

When you pass any of the four flags above, a successful login prints only the connection name, which suits scripts.

Log in from environment variables

PLANE_SERVER_URL, PLANE_AUTH_TYPE, PLANE_AUTH_TOKEN, PLANE_WORKSPACE and PLANE_CONNECTION are fallbacks for the matching flags. A flag wins over its variable. Set all five and login runs with no prompts:

export PLANE_SERVER_URL=https://api.plane.so
export PLANE_AUTH_TYPE=pat
export PLANE_AUTH_TOKEN="$PLANE_TOKEN"
export PLANE_WORKSPACE=myteam
export PLANE_CONNECTION=ci
plane auth login

If you use only environment variables and no flags, the output is the interactive style rather than the bare connection name.

Other auth commands

Command	Label	What it does
plane auth list-connections	Safe	Table of connections, token type, server and linked workspaces. The default workspace is starred.
plane auth connect-workspace <slug> -c <connection>	Confirm	Link another workspace to an existing connection. The token is checked first. --connection is required.
plane auth disconnect-workspace <slug> [-c <connection>]	Confirm	Unlink a workspace. With --connection, it first checks the workspace is linked to that connection.
plane auth logout <connection> [-f]	Confirm	Remove a connection and every workspace linked to it. Asks first unless you pass --force.

list, connections and whoami also work as names for list-connections, and connect works for login.

Which connection a command uses

Project commands (push, pull, diff, schema, status, validate and the rest) pick credentials from the project's plane.yaml, in this order:

1. The connection: ID, if it exists in config.json. If it doesn't, Plane Compose warns and moves on.
2. The connection linked to the workspace: slug.
3. The default workspace's connection.
4. The first saved connection.

-c on push and pull doesn't pick credentials

push and pull accept -c / --connection, but credentials are already chosen from plane.yaml by then. The flag only changes the label used for rate-limit counters. To use a specific connection for a project, set connection: in its plane.yaml.

init, clone and ws clone do use -c, because they choose the workspace and connection themselves.

Self-hosted Plane

Log in with your instance URL as the server URL. The saved connection carries the server, and every project command that uses that connection talks to it.

plane auth login --server-url https://plane.mycompany.com --auth-type pat \
  --token "$PLANE_TOKEN" --workspace myteam -c selfhosted

You can also set api_url: in a project's plane.yaml. A value other than the default https://api.plane.so wins over the connection's server.

PLANE_API_URL has no effect in v0.5.2. Use --server-url at login or api_url: in plane.yaml.