| 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
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
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.
