CLI reference

The cavalry binary is distributed as @cavalry/cli on npm. Install globally:

npm install -g @cavalry/cli
cavalry --help

Configuration

Resolution order (first match wins):

1. --url / --token flags
2. ./cavalry.json in the current directory or any ancestor
3. CAVALRY_URL / CAVALRY_TOKEN env vars
4. ~/.cavalry/config.json

Commands

login

cavalry login --url https://cavalry.company.com --token cav_...

Saves credentials to ~/.cavalry/config.json.

logout

cavalry logout

whoami

Shows the active gateway + token prefix.

init

Creates a cavalry.json in the current directory — used by publish for installable project metadata.

publish [path]

cavalry publish ./my-skill

Packs the directory into a tarball and uploads it to your org's private registry. Requires a token with scope skills:write.

install <ref>

cavalry install acme/kafka-wrapper               # internal
cavalry install tessl:stripe/stripe              # upstream
cavalry install tessl:stripe/stripe@^2.0.0       # semver range

Streams the artifact into .cavalry/skills/<ns>/<name>. Exit codes:

• 0 — installed
• 2 — hard deny by policy (see cavalry policy list)
• 3 — pending approval (retry after approval is decided)
• 1 — other errors (network, invalid ref, etc.)

policy list

cavalry policy list [--json]

Shows active policies from the gateway's /v1/policies endpoint.

doctor

Basic config + connectivity check.

Environment variables