plane-cli

name

plane-cli

description

Use the unofficial Plane CLI (`plane` / `python -m plane_cli`) to inspect and manage Plane issues from the terminal. Trigger when the user asks to list Plane workspaces/projects/issues, read/create/update issues or work-items, move issue states, or add/read comments — against self-hosted Plane (old `/issues`) or Plane Cloud (`/work-items`). NOT for editing the plane_cli source (that is normal code work) or for non-Plane trackers.

Plane CLI

Overview

unofficial-plane-cli is a dependency-free Python CLI for the Plane issue tracker. It auto-bridges the old /issues and newer /work-items endpoints and redacts API tokens from all output. Invoke it as plane ... (installed via pipx/pip) or python -m plane_cli ... from a clone.

Token safety (mandatory)

• Never print, echo, log, or commit a Plane API token. Do not run echo $PLANE_API_TOKEN, env | grep -i token, or paste a token anywhere.
• Provide the token only via environment variables: PLANE_API_TOKEN, or per-workspace PLANE_TOKEN_<SLUG> (slug uppercased, - → _).
• If a token already exists in the user's shell/config, rely on it being in the environment; do not read and display its value.
• The CLI already masks tokens in config show, in --debug traces, and in error messages — prefer these safe surfaces over any manual token handling.

Configure

export PLANE_BASE_URL=http://localhost:8080/api/v1     # self-hosted
# export PLANE_BASE_URL=https://api.plane.so/api/v1    # Plane Cloud
# token comes from the environment; never print it

Endpoint mode when the server is known: --endpoint-mode issues (old self-hosted, e.g. v1.3.1), --endpoint-mode work-items (Cloud/newer), or omit for auto.

Read first (prefer before any write)

plane workspaces                             # discover workspaces (no -w needed)
plane -w <workspace> projects
plane -w <workspace> states <project>
plane -w <workspace> labels <project>
plane -w <workspace> list <project> --state-name Todo
plane -w <workspace> search "<query>" --project <project>
plane -w <workspace> get <project> <issue-number>
plane -w <workspace> comments <project> <issue-number>

plane workspaces is not workspace-scoped; some Plane builds do not expose it to API tokens, in which case use a known slug with -w. <project> is the identifier (MF), name, or UUID. <issue-number> is the bare sequence number (41), not MF-41. Add --json for machine parsing. Global flags come before the subcommand.

Writes (only when the user asked)

plane -w <workspace> create <project> "Title" \
  --description "..." --state-name Backlog --priority high --label-names "Bug,API"
plane -w <workspace> update <project> <issue-number> --state-name "In Progress"
plane -w <workspace> comment <project> <issue-number> "Note ..."

Only create/update/comment when the user explicitly requested that change; run a read first to confirm the target.

The api escape hatch

plane api <METHOD> <path> issues a raw workspace-scoped request. It sends whatever method you pass, including destructive ones (DELETE/PUT) and performs no confirmation. Prefer the first-class subcommands; use api only for reads or when explicitly authorized for a specific write. Output is still redacted.

Exit codes

0 success, 1 API/transport error, 2 usage/config/not-found. Error messages are already token-safe; surface them verbatim.