Skip to content
VelerionVelerion Docs

CLI Reference

Terminal window
npm install -g @velerion/cli
velerion --version

Global flags

Section titled “Global flags”
Flag Description
--env <name> Target environment. Defaults to the value of velerion env use.
--workspace <slug> Target workspace. Defaults to velerion workspace use.
--json Machine-readable output. Stable across releases; the table output is not.
--yes Skip confirmation prompts. Required in non-interactive shells.
--verbose Log every HTTP request with its request ID.

Authentication

Section titled “Authentication”
Terminal window
velerion login                      # browser-based device flow
velerion logout
velerion whoami                     # prints identity, workspace and environment
velerion service-account create <name> --role <role> --environments <list>
velerion service-account revoke <id>

Workspaces and environments

Section titled “Workspaces and environments”
Terminal window
velerion workspace list
velerion workspace use <slug>
velerion env list
velerion env use <name>
velerion env set KEY=value --env staging
velerion env unset KEY --env staging

Agents

Section titled “Agents”
Terminal window
velerion deploy --agent <name> [--env <name>]
velerion promote --agent <name> --from <env> --to <env>
velerion rollback --agent <name> --env <env> [--to <revision>]
velerion agents list
velerion agents show <name> --env prod
velerion dev --agent <name>          # run locally against dev connections
velerion run <name> --input @ticket.json

rollback without --to returns to the previously deployed revision.

MCP catalog

Section titled “MCP catalog”
Terminal window
velerion mcp search <query> [--reviewed-only] [--workspace]
velerion mcp show <id>@<version> [--tools]
velerion mcp install <id>@<version> --env <env> --connection <name>
velerion mcp upgrade <id> --env <env> --to <version>
velerion mcp diff <id> <from> <to>
velerion mcp validate <path>
velerion mcp publish <path> --visibility workspace|public

Connections and secrets

Section titled “Connections and secrets”
Terminal window
velerion connection create <name> --type <type> --env <env> --secret <KEY>
velerion connection test <name> --env <env>
velerion secret set <KEY> --env <env>       # value read from stdin
velerion secret list --env <env>            # names only, never values

Observability

Section titled “Observability”
Terminal window
velerion logs --agent <name> --env prod --follow
velerion traces list --agent <name> --since 1h
velerion traces show <trace-id>
velerion usage --since 2026-07-01 --group-by agent
velerion audit export --since <date> --format jsonl

Exit codes

Section titled “Exit codes”
Code Meaning
0 Success.
1 Generic failure — read the message.
2 Invalid usage or arguments.
3 Authentication or authorisation failure.
4 Validation failure, for example a rejected manifest or breaking tool change.
5 Rate limited after exhausting retries.