vercel-axi is an AXI-compliant CLI that wraps the official first-party Vercel CLI. It keeps Vercel responsible for authentication and operations while adding strict arguments, compact deterministic output, useful next steps, secret redaction, and explicit production safety gates.
- AXI specification:
axi/1.0-2026-07 - Required Vercel CLI: exactly
59.10.0 - Node.js: 20 or newer
Install the official CLI and this wrapper:
npm install --global [email protected]
npm install --global vercel-axiFor repository development, [email protected] is pinned as a development dependency, so npm install provides the exact CLI used by tests and validation.
Confirm the versions:
vercel --version
vercel-axi --versionAuthentication is delegated to the official Vercel CLI. The wrapper never stores or logs tokens.
vercel loginFor CI or other non-interactive environments, set VERCEL_TOKEN using the environment's secret manager:
export VERCEL_TOKEN="..."
vercel-axi project listDo not pass a token on the command line. If authentication is missing, vercel-axi exits with a structured setup message.
Default output is compact TOON on stdout. Commands whose official Vercel counterpart supports JSON expose --json; JSON is passed through after any required secret redaction. Successful commands keep stderr silent.
0: success or no-op1: authentication, Vercel CLI, or operational failure2: invalid usage or missing confirmation
Every command group and leaf command supports --help:
vercel-axi --help
vercel-axi deployment --help
vercel-axi deployment list --helpUse --scope <team-or-user> to select a Vercel scope explicitly and --cwd <directory> to run against a particular project directory. These flags are available on operational commands unless the underlying operation does not accept them.
The wrapper refuses operations that affect production or make sensitive infrastructure changes unless --confirm is present. A refusal prints the exact intended change and exits 2 without launching Vercel.
Confirmation is required for:
- production deploys through
--prodor--target production - deployment promotion and rollback
- domain additions and removals
- DNS additions and removals
- environment variable additions and removals
Preview deployments do not require confirmation. A dry run does not make a change and does not require confirmation, even if a production target is supplied.
Environment variable values are recursively redacted from env list output by default. --show-secret-values is the explicit loud override. The official CLI normally returns metadata rather than decrypted secret values, but the wrapper still redacts any returned value, secret, or decryptedValue fields unless this flag is present.
For environment variable input, prefer a prompt or piped stdin so the value is not placed in shell history:
printf '%s' "$VALUE" | vercel-axi env add API_TOKEN production --value-stdin --type secret --confirmvercel-axi deployment list
vercel-axi deployment list my-app --status READY --limit 20
vercel-axi deployment list --all --environment production --jsonSupports --all, --environment, --status, --limit, --next, --json, --scope, and --cwd.
vercel-axi deployment inspect dpl_123
vercel-axi deployment inspect my-app.vercel.app --wait --timeout 90s --json
vercel-axi deployment inspect dpl_123 --logsvercel-axi deployment logs --project my-app --level error --since 1h
vercel-axi deployment logs dpl_123 --status-code 500 --json
vercel-axi deployment logs --environment production --query "status:500 error"Logs are bounded rather than followed indefinitely. Filters include project, environment, level, time range, limit, status code, query, branch, request ID, source, and expanded messages.
vercel-axi deployment deploy .
vercel-axi deployment deploy . --project my-app --no-wait --json
vercel-axi deployment deploy . --prod --confirm
vercel-axi deployment deploy . --target production --confirm
vercel-axi deployment deploy . --dry --jsonPreview is the default. Production requires --confirm. Additional flags include --prebuilt, --force, --logs, --skip-domain, and --cwd.
vercel-axi deployment promote dpl_123 --confirm
vercel-axi deployment rollback dpl_123 --confirm
vercel-axi deployment promote dpl_123 --timeout 5m --scope my-team --confirmBoth operations affect production and always require confirmation.
vercel-axi project list
vercel-axi project list --filter api --limit 50 --json
vercel-axi project list --update-requiredvercel-axi project create my-app
vercel-axi project create my-app --scope my-teamLinking requires an explicit existing project. This avoids an interactive path that could accidentally create a project.
vercel-axi project link --project my-app
vercel-axi project link ./apps/web --project my-app --team my-teamvercel-axi domain list
vercel-axi domain list --limit 50 --json
vercel-axi domain inspect example.com
vercel-axi domain add example.com my-app --confirm
vercel-axi domain add example.com my-app --force --confirm
vercel-axi domain remove example.com --confirmDomain additions and removals always require confirmation. --force can move a domain from an existing project and should be used deliberately.
vercel-axi dns list
vercel-axi dns list example.com --limit 100
vercel-axi dns inspect rec_123
vercel-axi dns inspect rec_123 --json
vercel-axi dns add example.com api A 198.51.100.100 --confirm
vercel-axi dns add example.com @ MX mail.example.com 10 --confirm
vercel-axi dns remove rec_123 --confirmRecord creation accepts the official Vercel CLI's type-specific positional details. Additions and removals require confirmation.
vercel-axi env list
vercel-axi env list production --project my-app
vercel-axi env list preview feature-branch --json
vercel-axi env list --json --show-secret-valuesValues are redacted unless the loud override is supplied.
printf '%s' "$API_TOKEN" | vercel-axi env add API_TOKEN production --value-stdin --type secret --confirm
printf '%s' "$API_URL" | vercel-axi env add API_URL preview,development --value-stdin --type config --confirm
printf '%s' "$API_TOKEN" | vercel-axi env add API_TOKEN preview --value-stdin --git-branch feature-x --force --confirmvercel-axi env remove API_TOKEN production --confirm
vercel-axi env rm API_TOKEN preview feature-x --project my-app --confirmenv rm is an alias for env remove.
vercel-axi team list
vercel-axi team list --json
vercel-axi team switch my-team
vercel-axi project list --scope my-teamPrefer per-command --scope for deterministic automation. team switch changes the official Vercel CLI's default team for later commands.
npm install
npm run build
npm test
npm run lint
npm run skill:gen
npm run skill:check
axi-axi validate "node bin/vercel-axi.js" --dir . --strict --timeout 30000Tests replace the official Vercel executable at the subprocess boundary and cover every wrapper command, Vercel failure propagation, authentication guidance, confirmation refusals, JSON behavior, and secret redaction. Tests never call live Vercel services.
A live smoke test is intentionally left as a follow-up because it requires the captain's Vercel login and an authorized account scope.