Convoy CLI

CLI agent for Convoy - connects your local repository to the web app.

Quick Start

# First time setup (interactive wizard)
convoy

# Or if already configured
convoy          # Starts agent connection directly

Installation

npx @useconvoy/cli --help

Run once without installing:

npx @useconvoy/cli connect

Install globally so convoy is available in your terminal:

npm install -g @useconvoy/cli
convoy --help

Windows notes:

npx @useconvoy/cli --help
npm install -g @useconvoy/cli
convoy --help

npm/npx will create the platform-specific launcher automatically:

• macOS/Linux: convoy
• Windows: convoy.cmd and convoy.ps1 (invoked as convoy)

Publishing is automated: bump version in apps/cli/package.json and merge to main. See docs/agents/publishing-the-cli.md.

Global Options

All commands support these global options:

--url <url>       Convex backend URL (overrides profile)
--api-key <key>   API key (overrides profile)
--profile <key>   Profile key for lookup
--project <id>    Project ID (overrides profile)

Options can be placed before or after the command:

convoy --profile work connect
convoy connect --profile work      # Same result

Commands

Default (no command)

Running convoy without a command:

• If a profile matches the current directory: starts the agent connection
• If no profile matches but profiles exist: prompts with three choices (create new, add folder to existing, connect once)
• If no profiles exist: runs the setup wizard

setup

Interactive setup wizard. Guides you through:

1. Convex URL
2. API key (validated against server)
3. Project selection
4. Profile name and key
5. Workspace folder
6. Starts agent connection

convoy setup
convoy setup --url https://xxx.convex.cloud --api-key sk_user_xxx  # Prefill URL and key
convoy setup --profile work                                         # Prefill profile name
convoy setup --project proj_abc123                                  # Skip project selection
convoy setup --url https://xxx.convex.cloud --api-key sk_user_xxx --project proj_abc123 --profile-key work --profile "Work" --path .  # Fully non-interactive create-only
convoy setup --url https://xxx.convex.cloud --api-key sk_user_xxx --project proj_abc123 --profile-key work --force           # Overwrite existing key

setup becomes fully non-interactive when --url, --api-key, --project, and --profile-key are all provided. In that mode it validates inputs, writes the profile, and exits without starting connect. Use --path . to explicitly save the current directory; if omitted in non-interactive mode, the current directory is still saved for backward compatibility.

connect

Start agent connection (long-running process).

convoy connect
convoy connect --profile work
convoy connect --name "My Laptop"     # Custom connection name (defaults to hostname)
convoy connect -c 8                   # Allow up to 8 concurrent chat subprocesses
convoy connect --buffered             # Turn off live token streaming (on by default)
convoy connect --codex-exec           # Run Codex through `codex exec` instead of app-server

connect serves the runtimes detected on this machine (Claude Code, Codex, OpenCode). If none is installed, startup fails with a clear error. Use -c / --concurrency to control max simultaneous chat subprocesses per convoy connect process (valid range: 1-50). Without the flag, the resolved profile's optional concurrency value is used, then the default 5. Partial (delta) agent event streaming is on by default, so responses render token-by-token in the web app. Use --buffered to send whole events only (a profile can default this with streaming = false in config.toml; the flag wins). Codex threads are served over the codex app-server protocol by default — this enables mid-run approval prompts and questions, read-only Plan mode, steering queued messages into a running turn, live deltas, and the context-window meter. Use --codex-exec to fall back to non-interactive codex exec. The app-server transport needs codex-cli ≥ 0.142; an older binary is detected at connect time and downgraded to codex exec with a warning.

Debug logging

Use SDK debug logs to inspect spawned command args, resume/fork behavior, and streamed frames:

CONVOY_CLI_DEBUG=1 convoy connect   # Debug logs, truncated at 400 chars
CONVOY_CLI_DEBUG=2 convoy connect   # Debug logs, full JSON output (no truncation)

With level 1, you can fine-tune truncation length via CONVOY_CLI_DEBUG_MAX_CHARS (default: 400 chars, 0 = no truncation):

CONVOY_CLI_DEBUG=1 CONVOY_CLI_DEBUG_MAX_CHARS=0 convoy connect

Simulation mode

Use -s / --stream to replay a JSONL fixture file instead of spawning a real agent. Each line is sent to the backend with a delay, simulating a live agent session. This is useful for developing and testing the web UI without running an actual AI agent.

convoy connect -s fixtures/claude-code-review.jsonl          # Stream fixture with default 1500ms delay
convoy connect -s fixtures/claude-code-grep.jsonl -d 500     # Custom delay (500ms between lines)
convoy connect -s fixtures/claude-code-grep.jsonl -c 4       # Fixture mode with bounded parallel chat workers

During development you can use the pnpm dev shorthand:

pnpm dev connect -s fixtures/claude-code-review.jsonl
pnpm dev connect -s fixtures/claude-code-overview.jsonl -d 200

Available fixtures in fixtures/:

| File | Description | |---|---| | claude-code-grep.jsonl | Fixture for grep-style responses | | claude-code-review.jsonl | Code review session | | claude-code-overview.jsonl | Codebase overview session | | claude-code-tool-askuserquestion.jsonl | Session with user question tool use |

config

Manage stored profiles.

convoy config                       # Show profile summary
convoy config list                  # List all profiles
convoy config show                  # Show resolved profile for current directory
convoy config delete <key>          # Delete a profile
convoy config default <key>         # Set default profile

paths

Manage paths within a profile. The profile is resolved from the current directory or --profile flag.

convoy paths list                   # List paths for the resolved profile
convoy paths add                    # Add current directory to profile
convoy paths add /path/to/repo      # Add a specific path to profile
convoy paths remove /path/to/repo   # Remove a path from profile

A profile must always have at least one path. Removing the last path is not allowed.

status

Show current configuration and connection status.

convoy status
convoy status --profile work

projects list

List accessible projects.

convoy projects list
convoy projects list --profile work
convoy projects list --org org_abc123

orgs list

List accessible organizations (derived from accessible projects).

convoy orgs list
convoy orgs list --profile work
convoy orgs list --output json

task-types list

List the task types available in the resolved project.

convoy task-types list --project WEB
convoy task-types list --project WEB --output json

profiles list

List your CLI profiles in the resolved project, with online state, CLI version, available runtimes, and each working path's ID. This is the server's view of your connected machines — paths and status read local config instead.

convoy profiles list
convoy profiles list --project WEB
convoy profiles list --output json

threads

Read and drive CLI threads. A thread group lists as one row with a child count; pass its container ID to list the members.

convoy threads list --project WEB
convoy threads list --project WEB --include-done --limit 5
convoy threads list <containerId>

convoy threads get <threadId>
convoy threads messages <threadId> --limit 3

convoy threads create --profile-id <profileId> --path-id <pathId> \
  --cli-type claude-code --content "Review the invoice rounding"
convoy threads create --source <threadId> --content "Review my work"
convoy threads send <threadId> "Ship it"
convoy threads send <threadId> --attach ./screenshot.png

threads messages takes --limit 1-20 (default 10) and prints oldest first. Message text is the agent's prose only — no tool calls, tool output, or reasoning.

threads create --source spawns beside an existing thread — inheriting its profile, path, and runtime — which groups the two. Pass a container ID to join an existing group. --attach takes up to 10 files per message and uploads them before the send; a failed send discards the uploads.

project-agents

Manage Project agents through direct Convex one-shot commands.

convoy project-agents list --project WEB
convoy project-agents create --project WEB --name "Reviewer" --color "#3b82f6"
convoy project-agents create --project WEB --name "Planner" --color "#8b5cf6" --automation enabled --automation-cli-type codex --automation-workspace worktree
convoy project-agents update <projectAgentId> --description "Reviews pull requests"
convoy project-agents update <projectAgentId> --clear-automation

tasks

One-shot task commands (non-interactive, run once and exit).

Manual command catalog for this workspace:

• See /src/docs/specs/cli-one-shot-manual-tests.md

convoy tasks list
convoy tasks list --project WEB --org acme
convoy tasks list --status "Triage" "Plan Review"
convoy tasks list --archived --output json

convoy tasks search "billing bug"
convoy tasks search "billing bug" --project WEB --org acme --limit 5
convoy tasks search "billing bug" --archive-mode archived --status "Plan Review"
convoy tasks search "billing bug" --assignee-id user_123 --output json

convoy tasks get task_abc123
convoy tasks get task_abc123 --comments 5
convoy tasks refs WEB-12 WEB-42 --project WEB --org acme
convoy tasks refs WEB-12 WEB-42 --project WEB --comments 5

convoy tasks attach WEB-12 ./spec.pdf ./screenshot.png --project WEB
convoy tasks attachments list WEB-12 --project WEB
convoy tasks attachments download WEB-12 attachment_abc123 --output ./spec.pdf --json
convoy tasks attachments delete WEB-12 attachment_abc123 --yes
convoy task attachment list WEB-12 --project WEB            # singular aliases also work

convoy tasks artifacts list task_abc123
convoy tasks artifacts get artifact_abc123
convoy tasks artifacts create task_abc123 --name "Implementation plan" --content-file ./tmp/plan.md
convoy tasks artifacts update artifact_abc123 --name "Revised plan" --clear-run-id
convoy tasks artifacts delete artifact_abc123

convoy tasks create --name "Fix login bug" --project WEB --org acme --priority High --task-type-key bug
convoy tasks update task_abc123 --status "Plan Review" --task-type-key feature --assignee-id user_123
convoy tasks update task_abc123 --clear-due-date --unassign
convoy tasks move WEB-12 --parent WEB-42 --project WEB --org acme
convoy tasks move task_abc123 --top-level
convoy tasks move-to-list WEB-12 WEB-42 --list SPRINT-1 --project WEB
convoy tasks move-to-list task_abc123 --list BACKLOG --project WEB --json
convoy tasks comments add WEB-12 --message "Ready for review" --project WEB
convoy tasks comments add task_abc123 --message-file ./tmp/comment.md --json
convoy tasks delete task_abc123 --cascade keep_children

Notes:

• --project accepts project ID or alias.
• --org accepts organization ID or slug, and is used to disambiguate alias lookups.
• If --project is omitted, task commands use the resolved profile project_id.
• Status values are normalized locally but validated by the backend/project configuration.
• --task-type-key is passed through to the backend and validated there.
• tasks search uses cursor pagination with --limit and --cursor.
• tasks move accepts raw task IDs, bare refs, or scoped refs like acme/WEB-12, and computes rank server-side.
• tasks move-to-list resolves up to 25 task IDs/refs and moves them in one atomic backend mutation; targets accept List IDs, bare refs, or BACKLOG.
• tasks comments add creates ordinary task comments from --message or --message-file; artifact comments remain under tasks artifacts comments.
• tasks attach uploads one or more local files to a task; tasks attachments list/download/delete manages task file attachments.
• Multi-file tasks attach is best-effort: it prints uploaded attachments and failed files, then exits nonzero if any file failed.
• task and attachment are aliases for tasks and attachments.
• tasks attachments download uses --output <path> for the local file path; use --json for JSON output on that command.
• tasks artifacts create and tasks artifacts update support --content or --content-file; update also supports --clear-content and --clear-run-id.
• tasks get and tasks refs text output now includes artifact summary sections without embedding artifact markdown content.
• tasks get and tasks refs omit comments by default; pass --comments <n> to include the latest 1-50 comments.

One-shot output mode

All one-shot commands support:

--output <text|json>
--json

Default output mode is text.

init

Initialize MCP config and/or install Convoy skills for supported CLIs.

convoy init                                 # MCP + skill setup
convoy init mcp                             # MCP config for selected targets
convoy init skill                           # prompt target(s): claude/codex (default both)
convoy init skill --cli claude --scope user
convoy init skill --cli codex --scope project
convoy init --cli claude,codex --scope user
convoy init mcp --cli codex                 # writes only .codex/config.toml
convoy init mcp --cli claude                # writes only .mcp.json

init skill options:

• --cli <target...>: claude, codex (repeat or comma-separated)
• --scope <scope>: Skill scope (user, project)
• --force: overwrite existing skill files or links without prompts

init mcp options:

• --cli <target...>: MCP target(s): claude, codex (repeat/comma-separated; default both)
• --output-dir <path>: write config files under this directory
• --force: overwrite existing convoy entries without prompts

Behavior notes:

• If --cli is omitted, target selection is prompted with both selected by default.
• init uses one --cli selection for both MCP setup and skill setup.
• MCP file mapping: claude -> .mcp.json, codex -> .codex/config.toml.
• If Claude is selected but claude is unavailable, Claude is skipped and other targets continue.
• Project-scoped raw skills are stored once in .agents/skills/convoy-tasks.
• Project-scoped Claude raw installs link .claude/skills/convoy-tasks to that .agents copy.
• Existing skill files or links prompt before overwrite unless --force is passed.
• Codex install does not require a detected codex binary.
• If no selected target installs successfully, the command exits non-zero.

skills.sh alternative

convoy init skill uses the bundled Convoy skill files and keeps installation deterministic. If you prefer the external skills.sh manager, install the same skill directly:

npx skills add https://github.com/packtrain/convoy/tree/main/plugins/convoy/skills --skill convoy-tasks

Use --agent claude-code or --agent codex to target one client, --global for user-wide installation, and --copy if you do not want skills.sh to use its default symlink-based install.

Configuration

Unified Config File

All configuration is stored in a single TOML file at ~/.config/convoy/config.toml:

[settings]
default_profile = "my-project"  # Optional fallback when no profile matches

[profiles.my-project]
name = "My Project"
url = "https://xxx.convex.cloud"
api_key = "sk_user_xxx"
project_id = "proj_abc123"
paths = ["/Users/me/my-project"]
concurrency = 8

[profiles.work]
name = "Work"
url = "https://work.convex.cloud"
api_key = "sk_user_yyy"
project_id = "proj_def456"
paths = ["/Users/me/work/frontend", "/Users/me/work/backend"]

Profile Resolution

When you run the CLI, it resolves a profile in this order (highest priority first):

1. --profile CLI flag
2. CONVOY_PROFILE environment variable
3. Path match (any entry in profile's paths matches current directory or is ancestor)
4. settings.default_profile from config
5. No match (prompts to create, add folder, or connect once)

When multiple profiles match, the most specific path (longest match) wins.

Environment Variables

CONVOY_URL         # Override Convex URL (also pre-fills `convoy setup` prompt)
CONVOY_API_KEY     # Override API key
CONVOY_PROFILE     # Specify profile key

Set on the spawned coding runtime (not read by the CLI):

CONVOY_THREAD_ID   # Convoy thread the run belongs to (all runtimes except opencode)

Multiple Paths

A single profile can manage multiple directories. This is useful when you have several repos or worktrees that all belong to the same project:

[profiles.my-project]
name = "My Project"
url = "https://xxx.convex.cloud"
api_key = "sk_user_xxx"
project_id = "proj_abc123"
paths = [
  "/Users/me/my-project",
  "/Users/me/my-project-worktree",
  "/Users/me/other-repo"
]

All paths are synced to the backend when the agent connects. The web UI lets you select which path to use when creating a new chat.

Add or remove paths with the paths command:

cd /Users/me/other-repo
convoy paths add              # Adds current directory to the resolved profile
convoy paths remove /old/path # Removes a path

Running from Any Directory

The CLI can run from any directory:

• If a profile matches the directory (via any path in paths), it uses that profile
• If no profile matches but profiles exist, you're prompted with three choices:
  • Create new profile — runs the setup wizard
  • Add folder to existing profile — adds the current directory to the selected profile's paths, then connects
  • Connect once — connects using the selected profile without saving the directory

Development

pnpm dev                  # Run CLI (no args = setup wizard or connect)
pnpm dev setup            # Run setup command
pnpm dev config list      # Run with args
pnpm dev:watch            # Run with file watching (not for interactive prompts)
pnpm test                 # Run tests
pnpm test:once            # Run tests once
pnpm build                # Build for production