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 Plane. It auto-bridges the old /issues and newer /work-items endpoints and redacts API tokens from all output. Invoke it as plane ... (if 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, do not paste it into a message, do not write it to a tracked file.
• Provide the token to the CLI only via environment variables in the subprocess environment: 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 paths 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; do not print it

Pick the endpoint mode when you know the server: --endpoint-mode issues (old self-hosted, e.g. v1.3.1), --endpoint-mode work-items (Cloud/new), 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 needs no -w (it is not workspace-scoped), but some Plane builds do not expose workspace listing to API-token auth; if it fails, ask for or use a known workspace 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.

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. Confirm the target project/issue with a read first.

Exit codes & errors

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

Troubleshooting

• no API token ... → the environment has no token for that workspace; ask the user to export PLANE_API_TOKEN (do not request the value in chat if it can be set in their shell).
• 404 on issue operations with a forced mode → try the other --endpoint-mode or use auto.
• Instance down → curl -s <base-host>/api/instances/ should return data.