@velmhq/cli

Command-line interface for Velm. Quiet at the terminal, predictable in CI, first-class for AI coding agents. Same control surface as app.velm.run, exposed twice: as a velm <verb> CLI for humans and as an MCP server for agents.

Install

npm install -g @velmhq/cli

Authenticate

export VELM_API_KEY=vk_test_...
# or
velm login

Quickstart

velm templates list                                                   # pick a category
velm agents create --from-template support_qa --name "Acme Support"   # create
velm runs create --agent acme-support --input '{"message":"reset my key"}'
velm improvements list --status draft
velm improvements approve <id>   # opens the signed approval link in the dashboard

The dashboard at app.velm.run is the primary authoring surface. The CLI is for AI agents (Claude Code, Cursor, Codex) and humans who prefer the terminal. Every verb maps to a single SDK call so both surfaces stay honest.

velm agents export <slug> returns the full server-side agent record as JSON. velm agents update <slug> --set config.<key>=... edits any config field; velm agents update <slug> --config '<json>' applies a wider patch.

Commands

Agents

Command	Summary
velm agents list	List agents
velm agents get <slug-or-id>	One agent
velm agents create --from-template <category> --name <n>	Instantiate from a template
velm agents update <slug-or-id> --config '<json>'	Patch the config block inline
velm agents update <slug-or-id> --set config.key=value [...]	Sugar for scalar config edits
velm agents update <slug-or-id> --status active|paused|archived	Status transition
velm agents update <slug-or-id> --mode test|live	Mode transition
velm agents pause / resume / archive <slug-or-id>	Status-transition sugar
velm agents export <slug-or-id>	Full SDK Agent record as JSON
velm agents test-delivery <slug-or-id>	Opens the dashboard probe (requires a signed-in operator)
velm agents test-escalation <slug-or-id>	Opens the dashboard probe (requires a signed-in operator)
velm agents get-output-schema <slug-or-id>	JSON Schema for the agent's output
velm agents rotate-webhook-secret <slug-or-id> --yes	Returns plaintext once; old secret dies immediately
velm agents update-embed <slug-or-id> [--origins <csv>] [--rotate-identity-secret]	Embed allowlist + identity secret
velm agents source-summary <slug-or-id>	Preview of agent's docs / integrations / endpoints
velm agents delete <slug-or-id> --yes	Archive (soft delete)

Runs

Command	Summary
velm runs list [--agent <slug>] [--status <s>] [--limit <n>]	Search runs
velm runs get <id>	One run
velm runs create --agent <slug> --input @path|'<json>'|-	Enqueue a run (- reads stdin)
velm runs replay <id> [--agent <slug-override>] [--wait]	Re-submit a historical run's input
velm runs cancel <id> --yes	Cancel a pending or running run
velm runs watch <id>	Stream status transitions to terminal status
velm logs <id>	Tool calls, timing, output for one run

Improvements

Command	Summary
velm improvements list [--agent <slug>] [--status <s>] [--limit <n>]	Drafts / approved / rejected / rolled-back
velm improvements get <id>	One improvement
velm improvements approve <id>	Opens the signed approval link in the dashboard
velm improvements reject <id>	Opens the signed rejection link in the dashboard
velm improvements relevant --agent <slug> --query <text> [--limit <n>]	Top-K approved improvements scored against a query

Integrations

Command	Summary
velm integrations apps	Catalog of supported apps
velm integrations list	Active connections (keyed by app slug)
velm integrations get <app>	One connection
velm integrations connect <app>	OAuth bootstrap (alias: velm connect <app>)
velm integrations disconnect <app> --yes	Remove a connection

Secrets / API keys / Templates / Tenant / Feedback / Billing / Skills

Command	Summary
velm secrets list / get / set / put / delete	set creates only (409 if exists); put upserts; get returns metadata (no plaintext)
velm api-keys list / create / delete	All open the dashboard at /settings/api-keys (API keys cannot mint or revoke other API keys)
velm templates list [--category <c>] [--task <t>]	Static catalog filtered by template slug or task type
velm tenant show	Workspace record
velm tenant update [--name <n>] [--slug <s>] [--notifications-slack-channel <id>]	Workspace mutation
velm feedback capture --from-run <id> --event-type <t> [--surface <s>]	Auto-derive envelope from a run
velm feedback capture --from-file @<path>	Full envelope from JSON
velm feedback list [--event-type <t>]	Captured events
velm billing portal	One-time Stripe portal URL
velm billing usage	Current-period usage + safeguard state
velm skills list / get <name> / create --from <path> / patch <name> --patch ... / eval --from <path>	Tenant skills (keyed by name)

Meta

Command	Summary
velm	Tenant + key + recent run status
velm whoami	Identity check
velm doctor	Connectivity + sanity checks
velm context	Resolved CLI configuration
velm mcp	MCP stdio server for Claude Code, Cursor, Codex
velm completion	Shell completion script (zsh / bash / fish)
velm help [<cmd>]	Long-form help
velm login / logout	Manage ~/.config/velm/credentials

Common workflows

# review the self-improvement queue from the terminal and open the
# approval link for any drafts you want to ship
velm improvements list --status draft --json | jq '.data[] | .id'
velm improvements approve <id>   # prints a signed dashboard link

# rotate a webhook secret with no overlap window (caller must
# update its handler BEFORE this command lands)
velm agents rotate-webhook-secret support --yes

# inspect an agent's full server-side record
velm agents export support --json | jq

# replay a historical run for regression testing
velm runs replay run_abc --agent support-v2 --wait

# stream tenant-wide feedback events for a triage pipeline
velm feedback list --event-type thumbs_down --json

Exit codes

Stable contract for scripts and agent orchestrators:

Code	Meaning
0	Success
2	Usage (bad args, unknown command)
3	Auth (401 / 403 / missing key)
4	Not found (404)
5	Conflict (409)
6	Validation (422 / local config invalid)
7	Rate limited (429)
8	Server error (5xx, unexpected)
9	Network failure (transport / DNS / timeout)

logs <id> --json and runs watch --json emit one JSON object per line (NDJSON event stream). All other commands emit a single canonical JSON object on stdout in --json mode, with errors on stderr as a structured envelope.

Global flags

--json, --quiet, --no-color, --debug, --no-input, --api-key, --base-url, --help.

Non-interactive prompts are skipped when stdin is not a TTY, or when --no-input is set, or when VELM_NONINTERACTIVE=1. Destructive operations (delete, rotate-webhook-secret, disconnect) still require explicit --yes in non-interactive mode.

MCP

claude mcp add velm "$(which velm) mcp"

Default exposes read tools only. Set VELM_MCP_ALLOW=all to enable writes (runs.create, agents.update, secrets.put, integrations.disconnect, ...). See velm mcp --help for the full tool list. Dashboard-only verbs (api-keys, improvements approve/reject, agents test-delivery/test-escalation) are intentionally not exposed through MCP.

Documentation

Full reference at velm.run/docs/cli.

License

MIT. See LICENSE.