CLI Reference

The todos CLI is the local control surface for projects, tasks, plans, and runs.

Setup

Command	Purpose
`todos status`	Show local project health.
`todos projects`	List known projects.
`todos project-bootstrap . --name <slug>`	Register the current repo as a project.
`todos focus <project>`	Focus an agent on one project.

Status

todos status

Tasks

Command	Purpose
`todos list`	List tasks.
`todos show <id>`	Show one task.
`todos add <title>`	Create work.
`todos start <id>`	Claim work.
`todos done <id>`	Complete work.
`todos deps <id>`	Inspect dependency blockers for a task.
`todos blocked`	List tasks blocked by incomplete dependencies.
`todos ready`	List tasks that are pending, unlocked, and unblocked.
`todos next`	Pick the best ready task for an agent.
`platform-todos tasks list --ready --overdue`	List hosted scheduled tasks ready for agents.
`platform-todos tasks add <title> --due <date> --start-after <date> --recurrence weekly --sla-minutes 120`	Create a hosted scheduled task.
`platform-todos tasks claim --worker <agent>`	Worker-safe claim of the next hosted task.

Add

todos add "Review launch checklist"

Offline Queue

Use the hosted CLI queue when an agent needs to record write intent while the network is unavailable, then replay those writes with idempotency when connectivity returns.

Command	Purpose
`platform-todos tasks add <title> --offline`	Queue a hosted task create without calling the API.
`platform-todos tasks start <id> --offline`	Queue a hosted task start.
`platform-todos tasks done <id> --offline`	Queue a hosted task completion.
`platform-todos queue list`	Show pending and conflicted queued writes.
`platform-todos queue sync`	Replay pending writes with idempotency keys.

Sync queue

platform-todos queue sync --json

Dependencies

Use dependencies when a plan has work that must happen in order. Agents should claim ready work, not blocked work.

Command	Purpose
`todos deps <task-id> --needs <blocked-by-id>`	Mark a task as waiting on another task.
`todos deps <task-id> --remove <blocked-by-id>`	Clear a blocker after the prerequisite is done.
`todos blocked`	Review blocked tasks and missing prerequisites.
`todos ready`	Show unblocked tasks safe for agents to claim.

Ready work

todos ready

Agent Flow

Command	Purpose
`todos agents`	List registered agents.
`todos init <name>`	Register an agent.
`todos heartbeat <agent>`	Mark an agent as active.
`todos comment <id> <text>`	Add progress or verification notes.

Notifications

Command	Purpose
`platform-todos notifications list`	List org-scoped webhook subscriptions.
`platform-todos notifications create <url> --events task.done,run.completed`	Create an outbound agent webhook.
`platform-todos notifications disable <id>`	Disable a webhook subscription.
`platform-todos notifications deliveries`	Review delivery attempts and dead letters.

Webhook

platform-todos notifications create https://agent.example.test/hook --events task.blocked,task.done,run.completed

Billing

Command	Purpose
`platform-todos billing status`	Show plan and quota state when hosted mode is configured.
`platform-todos billing checkout`	Start Pro upgrade from the CLI.
`platform-todos billing portal`	Open billing settings for a hosted account.

Hosted Runs

The paid remote CLI is platform-todos. Use it for hosted queue, logs, artifacts, and cancellation without opening a browser.

Command	Purpose
`platform-todos runs list`	List hosted runs visible to the configured organization.
`platform-todos runs create <slug> --body <json>`	Queue a hosted run.
`platform-todos runs show <id>`	Inspect status, worker lease, sandbox, and attempt metadata.
`platform-todos runs logs <id>`	Read redacted run logs.
`platform-todos runs artifacts <id>`	List run artifact records.
`platform-todos runs cancel <id>`	Cancel queued or running work.

Queue hosted run

platform-todos runs create website-launch --body '{"goal":"ship"}' --max-attempts 2 --timeout-ms 900000

Inspect hosted run

platform-todos runs show <run-id>

Hosted Credentials

Use the paid remote CLI as platform-todos for hosted service accounts and scoped API keys.

Command	Purpose
`platform-todos service-accounts list`	List service accounts in the configured organization.
`platform-todos service-accounts create <name> --scopes tasks:read,runs:create`	Create an agent service account with least-privilege scopes.
`platform-todos service-accounts key <id> --name codex-ci`	Mint a one-time API key for a service account.
`platform-todos api-keys list`	List API key metadata without secret material.
`platform-todos api-keys create --name ci --scopes tasks:read --select`	Create a scoped key and store it for the active profile with redacted output.
`platform-todos api-keys select --key <key>`	Store an existing scoped key for the active profile.
`platform-todos api-keys revoke <id>`	Revoke a key by ID.
`platform-todos api-keys rotate <id> --select`	Revoke a key and store the replacement for the active profile.

Raw API

Use raw API commands when a new endpoint is not wrapped yet.

Health

platform-todos api get /api/health

Capabilities

platform-todos api get /api/v1/capabilities

Run shared task work with agents.