CLI reference
The crosscode CLI is minimal and scriptable. Every command
supports a stable --json output mode for agents and scripts;
default human output is concise. From a cloned checkout, invoke it with
pnpm crosscode <command>.
Agents: don't parse this page or
--help. Run
crosscode commands --json for the entire command tree —
every command, argument, option, and description — as machine-readable
JSON. See the
install & quickstart guide
for these commands in context.
Getting set up
| Command | Purpose |
|---|
crosscode init | Initialize local Crosscode state for this checkout. Run this first; signup and login both need it. |
crosscode signup --email <email> --password <password> --service <url> | Create an account, log in, and get a personal workspace in one step. Prompts for the credentials if you leave them off in a real terminal. |
crosscode login --web <site-url> | Sign in through the browser; the CLI collects the session on a loopback callback. --web (or CROSSCODE_WEB_URL) is required, as there is no default site yet. Add --no-browser to print the URL instead. |
crosscode login --email <email> --password <password> | The headless sign-in, for agents and CI. No browser, no TTY, no --web. Tokens are never printed. |
crosscode logout | Clear the stored Supabase session for this checkout. |
crosscode join --workspace <id> | --invite <code> | --pair <code> | Join someone else's workspace. --pair works before any login. |
crosscode status | Show repository, daemon, outbox, cursor, and service health. |
Declaring what you're working on
| Command | Purpose |
|---|
crosscode task create "Implement checkout API" --path server/routes/checkout | Declare a task and the paths it covers, so others can see it. |
crosscode claim path src/checkout --task <id> | Advertise an advisory claim on a path for a task. |
crosscode intent "Add paymentStatus to CheckoutResponse" --task <id> | Publish a plain-language intent for a task. |
crosscode handoff request <operation-id> --note "..." | Ask someone else to take over reviewing an operation you produced. |
crosscode handoff respond <id> --decision accepted|declined | Answer a handoff request. |
Reviewing incoming work
| Command | Purpose |
|---|
crosscode proposals list | List remote operations awaiting review in this checkout. |
crosscode proposals inspect <id> | Show a proposal and a readable analysis of what it would do. |
crosscode proposals diff <id> | Show the per-path diff: base, local, and proposed content, plus classification and risk. |
crosscode proposals artifacts <id> | Show conflict artifacts recorded for a proposal. |
crosscode accept <operation-id> | Apply a proposal, after re-checking the local base and creating a checkpoint. |
crosscode reject <operation-id> | Reject a proposal; no local files are changed. |
Safety net, validation, and publishing
| Command | Purpose |
|---|
crosscode checkpoint [--message "..."] | Create a hidden Git checkpoint without moving HEAD or the index. |
crosscode checkpoint inspect <ref> | Show what a checkpoint contains. |
crosscode checkpoint restore <ref> <path> | Restore a single path from a checkpoint. |
crosscode validate [--profile fast] | Run commands from a committed .crosscode/config.yaml validation profile. Arbitrary commands are never accepted as arguments. |
crosscode publish --branch <branch> --profile <name> [--dry-run] | Create ordinary commits on a branch from accepted, validated state. Both flags are required. Prompts for confirmation unless you pass --yes. Never force-pushes. |
crosscode run -- <tool-and-arguments> | Run a local command with the daemon context available. Propagates that command's own exit code. |
Workspace settings
| Command | Purpose |
|---|
crosscode workspace autonomy get | Show how much this workspace applies automatically. |
crosscode workspace autonomy set <0|1|2> | Set it: 0 always ask, 1 auto-apply only when clean, 2 auto-apply always. Owner/admin only. |
crosscode billing status --workspace <id> | Read the workspace's plan and usage counters. Reads the service database directly, so it needs DATABASE_URL set. Nothing is charged today — see limitations. |
crosscode commands | Print the full command tree as machine-readable JSON. |
JSON output and exit codes
Every command accepts a position-independent --json flag.
Scripts and agents should always pass it: stdout becomes exactly one line
of compact JSON, {"value":…} on success and
{"error":{"code":…,"message":…,"hint":…}} on failure, with
nothing else written to stdout. Default (non-JSON) output is for humans
reading a terminal and is not a stable interface.
Exit code 0 on success and 1 on any error, with
the failure described by error.code. The one exception is
crosscode run, which passes the wrapped command's exit code
through unchanged. The error codes worth branching on are listed in the
repository's
README.