CLI command reference

The full convoy command surface. Narrative setup guides live in CLI & AI integrations; this page is the flat catalog.

Global options

Available on every command (and repeatable after subcommands):

Environment variables:

The CLI reads these at startup, so restart convoy connect after changing them. The desktop app starts the CLI through your login shell ($SHELL -lc), which is not interactive: for zsh, set them in ~/.zshenv or ~/.zprofile, not ~/.zshrc.

Setup and configuration

convoy setup

Interactive setup wizard. All flags are optional prefills, enabling non-interactive use:

When run interactively without --api-key, setup asks whether to log in with the browser (recommended) or paste a key.

convoy login

Browser-approve login: prints an approve link plus a backup device code, waits for approval in the web app, then continues with the same project selection and profile save as convoy setup. Accepts the same flags as setup except --api-key.

convoy config

convoy paths

convoy keys

Manage model providers stored locally in config.toml. These are Bedrock or Mantle credentials for Claude Code — or a credential-free entry pinning a Claude.ai subscription — not the Convoy API key used to authenticate the CLI with the backend. See Model provider keys for the walkthrough.

keys add <name> options:

--provider anthropic stores no credential: profiles using that entry run Claude Code on the machine's own Claude sign-in (a Claude.ai subscription), overriding Bedrock or Mantle settings the machine enables globally.

On ordinary profiles, --runtime codex stores a Bedrock or Mantle key as codex_provider_key; see Provider keys.

keys use and keys unassign accept --profile <key> to select a profile explicitly. Without it, normal profile resolution applies. Assignment changes take effect on the next convoy connect.

For isolated projects, managed OpenAI, Anthropic, Mantle, Bedrock and Cursor credentials (OpenAI and Anthropic also for OpenCode) use a separate private store. They are not legacy config.toml tokens:

Add --env <name> to manage keys in a host-managed environment, or --remote <name> for a remote target. These routes manage only the managed entries above, not the legacy Claude providers. Apply changes to running projects with service reload --profile <key> --interrupt. See Model provider keys for revocation, rotation and native-login behavior. api-key is an authentication mode name, not a placeholder for the secret.

convoy status

Show configuration and connection status.

Agent bridge

convoy connect

Start the long-running agent connection.

Managed environments and isolated projects

Run host-managed commands on your Mac or Linux host with Docker running. environment has the alias env; --environment has the alias --env. Project, service, attachment, managed-key and browser-smoke commands accept --env <name> to select a managed container. Without it, they operate in the current execution environment. A manually configured VM uses the latter route.

convoy run and convoy environment

Every environment subcommand requires --env <name> and accepts --json. run accepts --no-attach to return after readiness, --json for NDJSON attachment, --deployment <name> and --domains <comma-separated-domains> for initial network setup, and --package <tgz> for a local image-build candidate. A local archive does not replace an existing installation volume. See Managed local environments for setup and recovery.

convoy devcontainer [directory]

Write a devcontainer definition into the selected folder, defaulting to the current directory. --projects selects the multi-project isolation template; --force allows overwriting an existing definition. This command writes files, whereas convoy run builds and starts a host-managed environment. See Use in your project.

convoy project

project add accepts --profile-key <key>, --project <id-or-alias> to select an existing accessible project, or --create with --org <id-or-slug>, --project-name <name> and --project-alias <alias>. Interactive creation defaults the name from the profile key and suggests an alias. --clone <https-url> clones inside the boundary; --reuse accepts an existing privately owned directory. --non-interactive requires complete inputs. Deployment/authentication flags include --url and --api-key; prefer the masked prompt for interactive secrets. See Isolated projects for worker-key scope and recovery.

convoy service and convoy attach

Operational logs are distinct from agent transcripts. For service crashes and stopped containers, see Diagnose a stopped service. attach requires a running service; run provisions and starts it first.

convoy remote

attach, service, project and keys commands accept --remote <name>, which cannot be combined with --env. See Remote targets. --target <name> on the same commands picks the remote or managed environment with that name.

convoy service runs

All commands require --profile <key> and accept --json and --env <name>.

List/history default to 20 entries; --limit accepts 1 to 50. Use returned continueCursor until isDone. Transcript --after defaults to -1. These reads require a live service and backend access. See Persistent project service.

convoy browser

Both accept --session <name> for retained private browser state, --headed for an existing display and --no-browser-sandbox as an explicit sandbox override. Local smoke also accepts --allowed-url and --blocked-url for network probes. On the host, only browser smoke --env <name> --profile <key> is supported, with --session and --no-browser-sandbox. Pause the project's connection first. There is no browser install command; distributed images include Chromium. See Browser automation for VM installation and scripts.

Integrations

convoy init mcp

Create or update MCP server config for selected CLI targets (.mcp.json and/or .codex/config.toml).

convoy init skill

Install Convoy skills for Claude Code and/or Codex.

Bare convoy init accepts the union of both subcommands' flags and runs both steps.

Listing commands

Tasks

All task commands support --output <text|json>; list-like commands support pagination via --limit <n> and --cursor <cursor>. --org <org> takes an organization ID or slug and is used together with --project as an alias.

convoy tasks list

convoy tasks search <query>

convoy tasks get <taskId>

Get a task with external links, artifacts, files, subtasks, and optional comments (--comments <n>, 1–50). Text output prints Assignee: (the human owner) and, when the task is delegated, Delegated to: (the executing agent).

A Runs: section lists the CLI threads that have worked the task — status, title, thread ID, runtime, and who ran it — newest first. This includes your teammates' runs, not just your own, so it answers "is an agent already on this ticket?" before you start. Pass a thread ID to convoy threads get for its runtime target, or threads send to message it.

convoy tasks refs <refs...>

Get tasks by refs (e.g. convoy tasks refs ABC-1 ABC-2). Supports --comments <n>.

convoy tasks create

convoy tasks update <taskId>

Same field flags as create, plus clearing variants: --clear-description, --clear-due-date, --unassign, --clear-delegation, --clear-tags, and --label <label> / --clear-label. --unassign clears the owner (any delegation is kept); --clear-delegation clears the delegated agent (the owner is kept) and is mutually exclusive with --delegate-to-agent. Delegating a task with no owner auto-sets you as owner.

convoy tasks move <task>

Move a task (ID or ref) to a new parent (--parent <task>) or to top-level (--top-level).

convoy tasks move-to-list <tasks...>

Move 1-25 task IDs/refs to a persisted List or Backlog in one mutation.

convoy tasks comments add <taskId>

Create an ordinary markdown task comment. Pass exactly one of --message <text> or --message-file <path>. Raw IDs, bare refs, and scoped refs are supported.

convoy tasks delete <taskId>

Lists

Managing Lists requires List management permissions (project members and admins).

convoy lists create

convoy lists update <list>

<list> is a raw List ID or bare List ref (e.g. SPRINT-1); system Lists like BACKLOG cannot be updated. Requires at least one flag.

Archiving, deleting, and changing the default List stay in the web UI.

Project agents

Project-agent commands use the standard --project / --org resolution and support --output <text|json>.

convoy project-agents create

Requires --name <name> and --color <palette-color>. Optional fields: --description, --prompt, and --category.

Assignment automation is a whole-value configuration:

• --automation enabled|disabled
• --automation-prompt <text>
• --automation-cli-type <type>
• --automation-cli-model <model>
• --automation-cli-effort <effort>
• --automation-mode <mode>
• --automation-workspace local|worktree

convoy project-agents update <projectAgentId>

Supports the create fields plus --clear-description, --clear-prompt, --clear-category, and --clear-automation. Automation detail flags require --automation enabled|disabled; providing automation replaces the complete stored configuration.

Prompts

Prompts (slash commands) live either on a project or on an organization. Every prompt command supports --output <text|json> and picks its scope with --scope project|organization (default project).

Under --scope organization, --org <orgId|orgSlug> names the target organization on its own — including an organization with no projects you can access; leave it out to use the organization of the resolved project. Under project scope, --org only disambiguates --project and cannot be used alone.

convoy prompts list

List active prompts for the resolved project or organization.

convoy prompts create

Requires --key <key> (without the leading slash) and --content <content>. Optional: --description, --category, --auto-expand, --auto-submit.

convoy prompts create --key review --content "Review this contract." --project WEB
convoy prompts create --scope organization --org acme --key handoff --content "Write a handoff doc."

convoy prompts update <promptId>

Updates only the flags you pass: --key, --content, --description, --category, --auto-expand / --no-auto-expand, --auto-submit / --no-auto-submit, plus --clear-description and --clear-category. No scope flags — the stored prompt carries its own scope.

Deleting a prompt stays in the web UI.

Skills

A Skill is a SKILL.md plus optional additional files. list and create take --scope project|organization, defaulting to the profile's project, and --org <orgId|orgSlug> for organization scope — the same flags the prompt commands take. show, update, and remove take a Skill ID, which carries its own scope. Managing organization Skills requires organization owner or admin; a project Skill requires project admin or member.

convoy skills list

Lists the project's or the organization's Skills with their version, name, description, and category.

convoy skills show <skillId>

Prints the Skill's columns, its SKILL.md, and the paths of its other files. --output json includes every file's content. A Skill copied out of a Git repository also prints whatever provenance was recorded, as repoUrl/subpath@commitSha (ref) — the commit is the version an upstream check compares against, and every part of it is optional.

convoy skills create

Requires --name and either --content <content> or --content-file <path>. Optional: --description, --category, --scope, --org.

convoy skills create --name pdf-tools --content-file ./SKILL.md --project WEB
convoy skills create --name pdf-tools --content-file ./SKILL.md --scope organization --org acme

convoy skills install <name>

Installs an organization Skill into the project, by name, looked up in the project's own organization. The install copies it: the project copy is independent, so editing it never changes the template.

convoy skills install pdf-tools --project WEB
convoy skills install /pdf-tools --org acme --project WEB

Takes --org to disambiguate a project alias two organizations share. Looking the name up reads the organization's Skills, so an API key narrowed to specific projects cannot resolve it — use an unnarrowed key, or install from project settings.

Installing a Skill the project already has under that name fails. Updating an installed copy from its template is done in project settings, where it warns before discarding local edits.

convoy skills update <skillId>

Updates only the flags you pass: --name, --content / --content-file, --description, --category, plus --clear-description and --clear-category. SKILL.md is stored verbatim and never rewrites the name or description.

convoy skills remove <skillId>

Deletes the Skill. Files inside it are unreachable afterwards.

Editing a Skill file by file — adding, renaming, or patching one file — is an MCP operation: see MCP tools.

Workflows

Workflows are project-scoped. Both commands support --output <text|json>; --org only disambiguates --project.

convoy workflows list

List active Workflows for the resolved project. Text output marks a Workflow whose draft changed since its last run with draft changed.

convoy workflows get <workflowId>

Show a Workflow's identity fields, then its Lanes and each Stage's Steps. JSON output is the stored record; its draftDefinition is the shape the editor saves, so it can be edited and sent back with workflows update.

convoy workflows create

Exactly one of --definition-file and --from is required. Lane, Stage, and Step ids are plain strings that only need to be unique within the definition, so a hand-written file can use readable ids:

{
  "lanes": [{ "laneId": "main", "name": "Main", "type": "single", "defaults": { "cliType": "claude-code" } }],
  "stages": [
    {
      "stageId": "build",
      "name": "Build",
      "steps": [
        { "stepId": "test", "laneId": "main", "action": { "type": "bash", "script": "pnpm test", "timeoutMs": 600000, "reportOutput": "on_failure" } }
      ]
    }
  ]
}

Save checks structure only; the full checks run when a run starts. Pass --validate to run them right after saving (exits non-zero when the draft is not runnable), or use workflows validate. With --output json the verdict rides in the same object: { "workflowId": "...", "validation": { "ok": false, "error": "..." } }.

convoy workflows update <workflowId>

Same identity flags as create, plus --clear-description, --clear-category, --clear-color, --definition-file <path> to replace the draft, and --validate. At least one field flag is required.

convoy workflows validate <workflowId>

Runs the version-cut checks without starting a run: the stored draft by default, or --definition-file <path> checked against that Workflow's project before you save it. Prints the first failing rule and exits non-zero. JSON output is { "ok": true } or { "ok": false, "error": "..." }, and a failed verdict exits non-zero in JSON mode too, so it works as a CI gate.

convoy workflows start <workflowId>

Starts a run: cuts a version from the draft when it changed, creates the run's container thread, and dispatches the first Step. Runtime, model, and mode come from the definition, so there is no --cli-type.

Prints the run ID and its container thread ID; --output json returns both.

convoy workflows runs ...

Run babysitting from the terminal. Every command here is gated by the backend to the user who started the run; anyone else gets "not found".

<stepId> is the run-step ID that runs get prints, not the definition's step id. All commands support --output json.

convoy workflows delete <workflowId>

Soft-deletes the Workflow. Its active runs are canceled; version and run history are kept.

convoy workflows list --project WEB
convoy workflows get k17... --output json > release.json
convoy workflows update k17... --definition-file release.json --validate
convoy workflows validate k17... --definition-file draft.json
convoy workflows create --name "Release train (copy)" --from k17... --project WEB
convoy workflows start k17... --profile-id j57... --path-id 3f1c... --task WEB-42 --worktree-branch web-42
convoy workflows runs get k57... --output json
convoy workflows runs approve k57... kd7...

Labels

Project labels are single-valued, colored, ordered task classifications (managed set, distinct from free-form tags). Managing labels requires project admin permissions; assigning one to a task needs only task-update permission. Wherever a command takes a <label>, you may pass the label's raw ID or its exact name (case-insensitive).

convoy labels list

List a project's labels in board-column order. Supports --output <text|json> and --org <org>.

convoy labels create

convoy labels update <label>

convoy labels delete <label>

Deletes the label and resolves every task that references it (including soft-deleted and archived tasks) in one mutation.

Label reordering is not exposed on the CLI — board-column order is managed in the web UI.

Task links

convoy tasks links ...

External links on a task (commits, branches, pull requests, generic URLs). Use a deterministic --id (e.g. github-pr-acme-app-12) so repeated upserts update instead of duplicating. The link URL flag is --link-url (--url is the global backend override).

Task artifacts

convoy tasks artifacts ...

CLI profiles

convoy profiles list

List your CLI profiles in a project, with the online state, CLI version, and available runtimes each connected machine reports, plus its working paths and path IDs. Supports --output <text|json> and --org <org>.

This is the server's view of your machines — convoy paths and convoy status read local config instead.

Threads

Read-only views of CLI threads. A thread group is a container row with no transcript of its own: it lists as a single row with a child count, and its members come from threads list <containerId>.

convoy threads list [<containerId>]

List the project's threads, newest activity first. Pass a group's container ID to list that group's members instead.

Listing a group's members needs no project and is never paginated — a group holds at most 100 threads and is read in one pass.

convoy threads get <threadId>

Get one thread: its status, runtime, target profile with online state, working path, and queue state. Given a group's container ID, prints the group's metadata (kind, child count, group status, origin thread) instead of a runtime target.

convoy threads messages <threadId>

Read a thread's most recent messages, oldest first. --limit <n> takes 1–20 (default: 10). Text is composed from the agent's prose only — tool calls, tool output, and reasoning are not included, so a turn that only ran tools reads as empty. A group has no transcript and is an error.

convoy threads attach <threadId> <file...>

convoy threads attach <threadId> shot.png notes.txt --message-id <replyId> --session-id <sessionId>

Attaches files to a running agent's current reply. Images render inline, or as a gallery when several are adjacent; other files render as download pills. You rarely type this yourself: each run's prompt gives the agent the exact command with its reply and session IDs. It fails once that run has finished. Up to 10 files per reply, 50 MB each. JSON output is { "threadId": "...", "messageId": "...", "storageIds": [...] }.

convoy threads done <threadId>

convoy threads done <threadId>
convoy threads done <threadId> --json

Marks your thread done and read, acknowledging current attention. A group or workflow run also marks its children done. Running threads or containers with running members are rejected; wait for execution to finish. New activity makes the thread not done again. JSON output is { "threadId": "..." }.

convoy threads attach-task <threadId> <task>

convoy threads attach-task <threadId> OS-1713
convoy threads attach-task <threadId> OS-1713 --json

Attaches a task to your thread when the thread was started without one, so the thread shows on the task's Runs column, timeline and Threads field. <task> is an ID or bare ref (OS-5, not acme/OS-5) in the thread's project. Re-attaching the same task does nothing; a thread already attached to another task is rejected. JSON output is { "threadId": "...", "taskId": "..." }.

See also

• One-shot commands — usage patterns and examples
• Config file (config.toml) — what setup writes and how profiles resolve
• MCP tools reference — the equivalent catalog for the MCP server