Plane CLI
CLI for Plane.so project management. Output is JSON by default — pipe to jq or consume directly.
Setup
uv tool install plane-cli # or: pip install plane-cli
plane config init # interactive setup wizard
Config: ~/.config/plane-cli/config.toml. All values can be set via env vars (PLANE_API_KEY, PLANE_WORKSPACE_SLUG, PLANE_BASE_URL, PLANE_PROJECT) or CLI flags.
Command Discovery
Do not guess command names or options. Use --help:
plane --help
plane issues --help
plane issues create --help
Quick Reference
| Resource |
Key commands |
plane projects |
list, get, create --name, update, delete |
plane issues |
list, get, create --title, update, delete |
plane issues comment |
list <issue-id>, add <issue-id> --body |
plane states |
list, get, create --name --color, update, delete |
plane labels |
list, get, create --name, update, delete |
plane pages |
list, get, create --name, update, delete |
Common Workflows
Create an issue:
plane issues create --title "Fix login bug" --priority high --state <state-id>
List issues with filters:
plane issues list --state <state-id> --assignee <user-id> --all
Update issue state (move to "In Progress"):
# First, find the state ID
plane states list --project <pid>
# Then update
plane issues update <issue-id> --state <state-id>
Add a comment (supports stdin with -):
plane issues comment add <issue-id> --body "Deployed to staging"
git diff HEAD~1 | plane issues comment add <issue-id> --body -
Important Conventions
--project is optional when defaults.project is configured- Destructive commands (
delete) require --yes in non-TTY (agent) contexts
--description and --body accept - to read from stdin--all fetches all pages (capped at 1000); default is first 20 results--pretty renders Rich tables — avoid in scripts, parse JSON instead- Errors go to stderr as JSON:
{"error": {"type": "...", "message": "...", "status_code": N}}
- Exit codes:
0 success, 1 error, 2 rate-limited (retry safe)
[!CAUTION]
delete commands are destructive — always confirm with the user before executing.
1---2name: plane-cli-23description: Plane.so: Create, update, and manage issues, projects, states, labels, and pages. Use when the user wants to interact with Plane.so — creating issues, listing tasks, updating status, managing labels, or any project-management workflow.4---5
6# Plane CLI
7
8CLI for [Plane.so](https://plane.so) project management. Output is JSON by default — pipe to `jq` or consume directly.
9
10## Setup
11
12```bash
13uv tool install plane-cli # or: pip install plane-cli
14plane config init # interactive setup wizard
15```
16
17Config: `~/.config/plane-cli/config.toml`. All values can be set via env vars (`PLANE_API_KEY`, `PLANE_WORKSPACE_SLUG`, `PLANE_BASE_URL`, `PLANE_PROJECT`) or CLI flags.
18
19## Command Discovery
20
21Do not guess command names or options. Use `--help`:
22
23```bash
24plane --help
25plane issues --help
26plane issues create --help
27```
28
29## Quick Reference
30
31| Resource | Key commands |
32|----------|-------------|
33| `plane projects` | `list`, `get`, `create --name`, `update`, `delete` |
34| `plane issues` | `list`, `get`, `create --title`, `update`, `delete` |
35| `plane issues comment` | `list <issue-id>`, `add <issue-id> --body` |
36| `plane states` | `list`, `get`, `create --name --color`, `update`, `delete` |
37| `plane labels` | `list`, `get`, `create --name`, `update`, `delete` |
38| `plane pages` | `list`, `get`, `create --name`, `update`, `delete` |
39
40## Common Workflows
41
42**Create an issue:**
43```bash
44plane issues create --title "Fix login bug" --priority high --state <state-id>
45```
46
47**List issues with filters:**
48```bash
49plane issues list --state <state-id> --assignee <user-id> --all
50```
51
52**Update issue state (move to "In Progress"):**
53```bash
54# First, find the state ID
55plane states list --project <pid>
56# Then update
57plane issues update <issue-id> --state <state-id>
58```
59
60**Add a comment (supports stdin with `-`):**
61```bash
62plane issues comment add <issue-id> --body "Deployed to staging"
63git diff HEAD~1 | plane issues comment add <issue-id> --body -
64```
65
66## Important Conventions
67
68- `--project` is optional when `defaults.project` is configured
69- Destructive commands (`delete`) require `--yes` in non-TTY (agent) contexts
70- `--description` and `--body` accept `-` to read from stdin
71- `--all` fetches all pages (capped at 1000); default is first 20 results
72- `--pretty` renders Rich tables — avoid in scripts, parse JSON instead
73- Errors go to stderr as JSON: `{"error": {"type": "...", "message": "...", "status_code": N}}`
74- Exit codes: `0` success, `1` error, `2` rate-limited (retry safe)
75
76> [!CAUTION]
77> `delete` commands are destructive — always confirm with the user before executing.
dvcrn