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:

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.

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.

convoy status

Show configuration and connection status.

Agent bridge

convoy connect

Start the long-running agent connection.

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.

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 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.

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.

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