CLI Reference

planeai-cli is a companion CLI that lets you script and automate planeai from the terminal. Most commands output JSON by default and accept a --pretty flag for human-readable output. The axi subcommand outputs TOON (a token-efficient text format) for agent consumption.

Install

On macOS, brew install --cask nicolegros/tap/planeai installs the app and links planeai-cli into $(brew --prefix)/bin.

Otherwise, install the CLI from within the app via Preferences → Advanced → Command line or with the system installer bundled with each release.

Once installed, it’s available as planeai-cli on your PATH.

Global Behavior

Behavior	Details
Output format	JSON (single line) by default
Pretty output	Add --pretty to any command for indented JSON or tables
Errors	Printed to stderr as {"error": "..."}, exits with code 1
Database	Uses the same SQLite database as the desktop app
Config	Reads ~/.config/planeai/config.json (same as the app)

---

session

Manage agent sessions.

session create

Create and launch a new agent session.

planeai-cli session create --project <name> --branch <branch> [options]

Flag	Description
--project	Project name (required)
--branch	Git branch to use (required)
--name	Display name for the session
--new-branch	Create the branch if it doesn’t exist
--worktree	Use a git worktree instead of checking out in-place
--base-branch	Base branch for new branch / worktree (default: main)
--yolo	Enable autonomous mode (skip confirmations)
--provider	Provider to use (overrides default_provider)
--task-key	Associate a task key with this session
--task-project	Project (name or id) owning --task-key, when the session runs in another project’s repo
--prompt	Initial prompt to send to the agent
--parent	Parent session ID (for orchestration tracking). Falls back to $PLANEAI_SESSION_ID env var

session ls

List active sessions.

planeai-cli session ls [--archived] [--pretty]

Flag	Description
--archived	Show archived sessions only

session delete

Permanently destroy a session and stop its tmux/daemon process. Its worktree is removed later by stale worktree cleanup.

planeai-cli session delete <id>

The id can be a prefix — it will match if unambiguous.

session archive

Archive a session (stops the agent but preserves the record).

planeai-cli session archive <id>

session children

List direct child sessions of a parent session.

planeai-cli session children <id> [--pretty]

Returns a JSON array of child sessions. Empty array if no children exist.

session tree

Show the full session tree. Walks up to the root (follows parent_session_id links), then returns all descendants in BFS order.

planeai-cli session tree <id> [--pretty]

Returns a JSON array of session records ordered root-first, then breadth-first. If the parent referenced by parent_session_id no longer exists, the orphaned session becomes the effective root.

session prompt

Send a prompt to a running session.

planeai-cli session prompt <id> [text]

If text is omitted, the prompt is read from stdin. This is useful for piping multi-line prompts:

echo "Refactor the auth module" | planeai-cli session prompt abc123

Prompts are serialized per session — only one prompt can be in flight at a time. If a concurrent prompt is already being sent to the same session, the command fails immediately with an error. Concurrent prompts to different sessions proceed independently.

---

project

Manage registered projects.

project list

List all registered projects.

planeai-cli project list [--pretty]

---

task

Built-in task tracker. Tasks are scoped to a project (resolved from --project or the current working directory).

task add

Create a new task.

planeai-cli task add <title> [options]

Flag	Description
--desc	Task description (default: empty)
--priority	Priority number (default: 0)
--tags	Comma-separated tags
--blocked-by	Comma-separated task keys that block this task
--parent	Parent task key (for subtasks)
--base-branch	Base branch for this task (default: main)
--project	Project name (otherwise resolved from CWD)

task show

Show a task by key.

planeai-cli task show <key> [--project <name>]

task ls

List tasks with optional filters.

planeai-cli task ls [--status <status>] [--tags <tags>] [--project <name>]

Flag	Description
--status	Filter by status: todo, in_progress, in_review, done
--tags	Comma-separated tags to filter by

task move

Move a task to a new status.

planeai-cli task move <key> <status>

Valid statuses: todo, in_progress, in_review, done.

task edit

Edit an existing task.

planeai-cli task edit <key> [options]

Flag	Description
--title	New title
--desc	New description
--priority	New priority
--tags	Replace tags (comma-sep)
--blocked-by	Replace blockers (comma-sep)
--base-branch	New base branch

task delete

Delete a task.

planeai-cli task delete <key> [--project <name>]

---

symphony

Control the auto-dispatch orchestrator.

symphony status

Show orchestrator status (running sessions, concurrency).

planeai-cli symphony status

symphony stop

Stop the orchestrator.

planeai-cli symphony stop

---

axi

Agent eXperience Interface — token-efficient TOON output designed for autonomous agents. Use planeai-cli axi instead of the JSON commands when building agent integrations.

Running planeai-cli axi with no subcommand prints a context-aware home view (current project, open tasks, active sessions).

axi task ls

List tasks (TOON tabular output).

planeai-cli axi task ls [--status <status>] [--tags <tags>] [--project <name>]

axi task show

Show task details.

planeai-cli axi task show <key> [--project <name>]

axi task add

Create a new task.

planeai-cli axi task add <title> [--desc "..."] [--priority <int>] [--tags <a,b>] [--blocked-by <K1,K2>] [--parent <KEY>] [--project <name>]

axi task move

Move a task to a new status.

planeai-cli axi task move <key> <status> [--project <name>]

Valid statuses: todo, in_progress, in_review, done.

axi session ls

List sessions.

planeai-cli axi session ls [--archived]

axi session create

Create a new session. Automatically sets the parent session from the $PLANEAI_SESSION_ID environment variable if present (for orchestration tracking).

planeai-cli axi session create --project <name> --branch <branch> [options]

Flag	Description
--project	Project name (required)
--branch	Git branch to use (required)
--name	Display name for the session
--new-branch	Create the branch if it doesn’t exist
--worktree	Use a git worktree instead of checking out in-place
--base-branch	Base branch for new branch / worktree (default: main)
--yolo	Enable autonomous mode (skip confirmations)
--provider	Provider to use (overrides default_provider)
--task-key	Associate a task key with this session
--task-project	Project (name or id) owning --task-key
--prompt	Initial prompt to send to the agent

axi session children

List direct child sessions of a parent session (TOON output).

planeai-cli axi session children <id>

Example output:

parent_session_id: abc12345
children[2]{id,parent_session_id,name,status,provider,task_key,backend}:
  def45678,abc12345,Worker 1,active,codex,PLA-201,daemon
  ghi78901,abc12345,Reviewer,exited,kiro,PLA-201,daemon

axi session tree

Show the full session tree rooted at the given session’s root ancestor (TOON output). Walks up parent_session_id links to find the root, then returns all descendants in BFS order.

planeai-cli axi session tree <id>

Example output:

session_tree:
  root: abc12345
sessions[3]{id,parent_session_id,name,status,provider,task_key,backend}:
  abc12345,,Planner,active,claude,PLA-201,daemon
  def45678,abc12345,Worker 1,active,codex,PLA-201,daemon
  ghi78901,abc12345,Reviewer,exited,kiro,PLA-201,daemon

Child sessions are linked for observability only. Killing a parent does not automatically kill children — cleanup remains explicit.

axi session read

Read the last N lines of a session’s terminal output (ANSI-stripped).

planeai-cli axi session read <id> [--lines <n>]
planeai-cli axi session read <id> --after <cursor> [--max-bytes <n>]

Flag	Description
--lines	Number of lines to read (default: 100). Used in tail mode.
--after	Opaque cursor from a previous read. Returns only new output since that cursor.
--max-bytes	Maximum bytes to return (default: 0 = unlimited). Only used with --after.

Tail mode (default): returns the last N lines.

Cursor mode (--after): returns only output produced since the cursor. See CONTEXT.md § Session reads for cursor format, truncation semantics, and polling workflow.

Works with both daemon and tmux backends. The local backend does not support cursor mode. The id can be a prefix.

axi session prompt

Send a prompt to a running session.

planeai-cli axi session prompt <id> [text]

If text is omitted, reads from stdin.

Prompts are serialized per session. If another prompt is already in flight, the command returns a TOON error with a retry hint:

error: session prompt already in progress
help[1]:
  - retry after the current prompt is sent

axi project ls

List registered projects.

planeai-cli axi project ls

---

Examples

Create a session with a worktree in autonomous mode:

planeai-cli session create \
  --project myapp \
  --branch feat/auth \
  --new-branch \
  --worktree \
  --yolo \
  --prompt "Implement JWT authentication"

Dispatch a task to an agent:

planeai-cli task add "Add pagination to /users" \
  --desc "Support limit/offset query params" \
  --tags backend,api \
  --priority 1
planeai-cli task move PLA-1 in_progress

List sessions as a formatted table:

planeai-cli session ls --pretty