CLI

cocurdex CLI reference — open the desktop app, manage notes, issues, and slide decks, sessions, teams, script runs, devices, providers, and skills.

The cocurdex CLI is the supported command-line boundary for app-owned product data and daemon operations. External tools and agents should use the CLI rather than reading private database files.

Most data and session commands require the desktop daemon (normally started when you open the desktop app).

Install

When the CLI is packaged with the desktop app, install the launcher from Settings → General → Shell command so cocurdex is on your PATH.

cocurdex --version
cocurdex --help

In monorepo development, use the workspace CLI package (apps/cli).

Finding the desktop binary

Open flows need the Cocurdex / Electron binary. Resolution order includes:

COCURDEX_ELECTRON environment variable
Running under Electron / packaged app
Development node_modules/electron under the monorepo
Common macOS install paths (/Applications/Cocurdex.app/...)

If resolution fails, open the desktop app once and install the CLI launcher, or set COCURDEX_ELECTRON.

Platform notes:

Linux AppImage — the launcher runs a stable copy of the CLI bundle, so it keeps working after the AppImage mount goes away.
Windows — the launcher is a shim on your user PATH; uninstalling Cocurdex removes the shim and its PATH entry.

Global flags

Flag	Meaning
`--help` / `help`	Print usage
`--version` / `-v` / `-V` / `version`	Print CLI version
`--json`	Machine-readable output where supported

Open the desktop app

VS Code-style folder open:

cocurdex                 # open app
cocurdex .               # open current directory as workspace
cocurdex open            # open app
cocurdex open /path/to/project

Notes

cocurdex note list [--json]
cocurdex note show <id> [--json]
cocurdex note create --title <title> [--body <markdown>] [--parent <id>] [--workspace <id>] [--folder] [--json]
cocurdex note update <id> [--title <title>] [--body <markdown>] [--json]
cocurdex note move <id> --parent <note-id> | --root [--json]
cocurdex note delete <id> [--json]
cocurdex note backlinks <id> [--json]
cocurdex note tags [note-id] [--json]

Flag	Meaning
`--title`	Required on create
`--body`	Markdown body (`-` reads stdin). `--body-file <path>` reads a file
`--root`	On `move`, lift the note to the sidebar root
`--folder`	Create a folder node instead of a note
`--parent`	Parent note/folder id
`--workspace`	Optional workspace association

Updates use optimistic concurrency (revision) under the hood — always prefer CLI/desktop over editing SQLite.

Issues

Default view id is project unless you pass --view.

cocurdex issue list [--status <column>] [--label <name>] [--parent <id>] [--open] [--view <id>] [--json]
cocurdex issue show <id> [--detail] [--view <id>] [--json]
cocurdex issue create --title <title> [--status <column>] [--priority <id>] [--body <text>] [--workspace <id>] [--parent <id>] [--labels <ids>] [--view <id>] [--json]
cocurdex issue update <id> [--title <title>] [--body <text>] [--status <column>] [--priority <id>] [--workspace <id>|none] [--parent <id>|none] [--labels <ids>] [--view <id>] [--json]
cocurdex issue move <id> <column> [--view <id>] [--json]
cocurdex issue comment <id> --body <markdown> [--json]
cocurdex issue relate <id> blocks|related|duplicate <id> [--json]
cocurdex issue unrelate <id> blocks|related|duplicate <id> [--json]
cocurdex issue labels [--json]
cocurdex issue label create --name <name> [--color <color>] [--json]
cocurdex issue label delete <id|name> [--json]
cocurdex issue delete <id> [--view <id>] [--json]
cocurdex issue views [--json]

Default status columns: backlog, doing, review, done.
Default priority columns: urgent, high, medium, low, none.

Examples:

cocurdex issue create --title "Fix download page" --status backlog --priority high
cocurdex issue move <id> doing
cocurdex issue list --status doing

Decks

Slide decks are app-owned records: Markdown in, a 16:9 deck out, with a checker for overflow, empty slides, and unknown slots. Layouts, themes, presenting, and the /cocurdex-deck skill: Slide decks.

cocurdex deck list [--json]
cocurdex deck show <id> [--json]
cocurdex deck create [--title <title>] [--markdown-file <path|-> | --content-file <path|->] [--workspace <id>] [--json]
cocurdex deck update <id> [--title <title>] [--markdown-file <path|-> | --content-file <path|->] [--expected-revision <n>] [--json]
cocurdex deck edit <id> --ops-file <path|-> [--expected-revision <n>] [--json]
cocurdex deck image <id> --slide <slideId> --file <path.png|path.jpg> [--alt <text>] [--replace <elementId>] [--expected-revision <n>] [--json]
cocurdex deck check <id> [--json]
cocurdex deck export <id> --output <path.pptx|path.pdf> [--format pptx|pdf] [--json]
cocurdex deck import <file.pptx> [--title <title>] [--workspace <id>] [--json]
cocurdex deck read <file.pptx> [--json]
cocurdex deck delete <id> [--json]

Flag	Meaning
`--markdown-file` / `--content-file`	Markdown source, or structured deck JSON. `-` reads stdin. Mutually exclusive and optional. Omit both to create a deck with no slides, or to leave slides unchanged on update
`--ops-file`	JSON array of edit ops, or `{ "ops": [ ... ] }`. Applied in order; a failure saves nothing
`--expected-revision`	Revision from `deck show`. A stale write fails with `Deck was modified`
`--output` / `--format`	Export path. Format is `pptx` or `pdf`, or the output extension
`--workspace`	Optional workspace id on create or import
`--slide` / `--file` / `--alt` / `--replace`	Add a PNG or JPEG (up to 20 MB), or swap one and keep its frame

deck list prints id, title, slide count, revision, and updated time. deck show includes checker issues. deck read prints the PowerPoint file as Markdown and does not create a deck. deck import creates a deck and leaves the file untouched. A line that is only --- splits slides; a paragraph starting with Notes: or 备注： starts speaker notes.

Search

cocurdex search <query> [--kind note|issue] [--workspace <id>] [--json]

Skills

Product skills are namespaced cocurdex-*. Install is manual (not automatic).

cocurdex skills list [--json]
cocurdex skills status --scope project|global [--root <path>] [--json]
cocurdex skills install --scope project|global [--root <path>] [--json]
cocurdex skills remove --scope project|global [--root <path>] [--json]

--root defaults to the current working directory for project scope. cocurdex skill is accepted as an alias. See Skills.

Daemon and workspaces

cocurdex daemon status
cocurdex workspace list

Devices and local web

Print the local web client URL (desktop app must be running):

cocurdex web [--json]

Pair another device with the host daemon. Full model: Devices and local web.

cocurdex host status [--json]
cocurdex host remote enable [--port <port>] | disable [--json]
cocurdex host pair --label <name> [--scopes read,interact,approvals] [--ttl <minutes>] [--json]
cocurdex host pairings [--json]
cocurdex host pairing cancel <pairing-id>
cocurdex host devices [--json]
cocurdex host revoke <device-id>
cocurdex host audit [--limit <n>] [--json]

--scopes is a comma-separated list of read, interact, execute, files.read, files.write, git.destructive, approvals, and credentials. Default pairing scopes are read,interact,approvals.

Worktrees

Managed git worktrees give sessions an isolated checkout of a workspace repository.

cocurdex worktree list [--json]
cocurdex worktree settings [--root <path>] [--fetch|--no-fetch] [--json]
cocurdex worktree create --workspace <id|path> --branch <name> [--start-point <rev>] [--json]
cocurdex worktree remove --workspace <id|path> --path <worktree-path> [--json]

worktree settings with no flags prints the current settings; pass --root and/or --fetch/--no-fetch to update them. --root sets the directory where Cocurdex creates managed worktrees (empty clears it back to the default location); --fetch controls whether the repository is fetched before creating a worktree.

Sessions

cocurdex session list
cocurdex session create --workspace <id|path> --agent <agent> --provider <provider> --model <model>
cocurdex session tui [session-id]
cocurdex session tui --workspace <id|path> --agent <agent> --provider <provider> --model <model>
cocurdex session send <session-id> <prompt>
cocurdex session tree <session-id> [--depth <n>] [--json]
cocurdex session fork <session-id> [--through <message-id>] [--title <title>] [--json]
cocurdex session switch-agent <session-id> <agent> [--json]
cocurdex session handoffs <session-id> [--json]
cocurdex session peers <session-id>
cocurdex session send-peer <from-session-id> <to-session-id> <message>
cocurdex session peer-inbound <session-id> deliver|refuse
cocurdex session stop <session-id>

Flag	Required for	Meaning
`--workspace`	create / tui create	Workspace id or filesystem path
`--agent`	create / tui create	Agent id: `claude-agent`, `codex`, `opencode`, `pi`, or an installed ACP Registry agent such as `acp:cursor`, `acp:devin`, `acp:grok-build`
`--provider`	create / tui create	Provider config id from `provider list`
`--model`	create / tui create	Model id from `provider models`

session tui without flags attaches to the latest non-archived session. It does not support --json.

session tree prints the execution tree. fork starts a new session from this one (--through cuts off after that message). switch-agent changes the runtime on an idle session. handoffs lists context transfers after a fork or agent switch. See Fork and switch agent.

peers lists the sessions a session can message; send-peer delivers a message as a new turn (or queues it after the current one); peer-inbound refuse stops a session from accepting peer messages. See Peer messaging.

Agent ids and permissions: Agents.

Teams

A lead session and its teammates. Full model: Agent teams.

cocurdex team get --lead <session-id> [--json]
cocurdex team create --lead <session-id> --template <template-id>
cocurdex team spawn --lead <session-id> --name <name> [--title <title>] --prompt <prompt> [--role <role-id>] [--agent <agent>] [--worktree]
cocurdex team stop --team <team-id>
cocurdex team stop-member --team <team-id> --session <session-id>
cocurdex team roles [--json]
cocurdex team templates [--json]
cocurdex team spawn-template --lead <session-id> --template <template-id> [--prompt <prompt>]

Flag	Meaning
`--lead`	The lead (main) session that owns the team
`--name`	Teammate name; lowercase slug
`--title`	Display title shown in the app; falls back to the name
`--role`	Saved agent role for the teammate
`--agent`	Agent id when not using a role; defaults to the lead's agent
`--worktree`	Run the teammate in its own managed git worktree

Script runs

Approved JavaScript fan-outs to subagents. Full model: Script runs.

cocurdex script-run list [--session <requester-session-id>] [--workspace <workspace-id>] [--json]
cocurdex script-run get --run <run-id> [--json]
cocurdex script-run create --session <requester-session-id> --name <name> --file <script.js>
cocurdex script-run start --run <run-id> [--max-agents <n>]
cocurdex script-run cancel --run <run-id>

create makes a draft run owned by the requester session; start approves and runs it with an agent limit (a positive integer). The result is delivered back to the requester session.

Providers

Provider configs feed the built-in Pi agent and the shared model catalog. See Providers and settings.

cocurdex provider list [--json]
cocurdex provider templates [--json]
cocurdex provider add <id> [--template <template-id>] [--name <name>] [--base-url <url>]
cocurdex provider update <id> [--name <name>] [--base-url <url>] [--enable|--disable]
cocurdex provider remove <id>
cocurdex provider status <id> [--json]
cocurdex provider login <id> [--method oauth|api_key] [--no-tui]
cocurdex provider logout <id>
cocurdex provider key set <id>        # reads the key from stdin (or a hidden prompt)
cocurdex provider key clear <id>
cocurdex provider models <id> [--refresh] [--json]
cocurdex provider model add <id> <model-id> --api <api> [--name <name>]
cocurdex provider model remove <id> <model-id>
cocurdex provider default [--agent <agent>] [--provider <id> --model <model-id>] [--json]
cocurdex provider import <file|->     # pi models.json format
cocurdex provider export [--output <file>]

Command	Notes
`add`	Needs `--base-url` or a `--template` from `provider templates`
`login`	Defaults to `--method oauth`; uses a terminal UI when stdin and stdout are TTYs, plain text with `--no-tui`
`models --refresh`	Fetches the catalog from the provider instead of the stored list
`model add --api`	One of `openai-completions`, `openai-responses`, `openai-codex-responses`, `anthropic-messages`, `google-generative-ai`, `mistral-conversations`
`default`	Without flags, lists the default provider and model per agent; with `--agent --provider --model`, sets one

Agent roles

Saved agent presets (agent + provider/model + permission + reasoning axes, avatar, description) that sessions, teammates, and script-run subagents can use. Manage them in the desktop UI; list them from the CLI:

cocurdex role list [--json]

What the CLI is not

A second source of truth — the desktop daemon still owns the local database
A full replacement for the multi-pane desktop workspace
A cloud team admin tool (that will be a separate console + API)
A license to open cocurdex.sqlite or private schema paths

Safety

Do not point scripts at cocurdex.sqlite or private schema paths. Those are implementation details and can change without a compatibility promise during pre-release. Prefer --json output and stable ids returned by the CLI.

CLI

On this page