Configuration

Config file, environment variables, exit codes, and networking behavior for the Arkveil CLI.

Settings are resolved with this precedence: flags > environment variables > config file > defaults.

Config file

Location: ~/.config/arkveil/config.json (or $XDG_CONFIG_HOME/arkveil/config.json, or the directory passed via --config-dir). Unknown keys are rejected.

{
  "baseUrl": "https://arkveil.example.com",
  "authBaseUrl": "https://auth.example.com/api/auth",
  "clientId": "arkveil-cli",
  "workspaceId": "00000000-0000-0000-0000-000000000000",
  "deviceCodePath": "/device/code",
  "deviceTokenPath": "/device/token",
  "timeoutMs": 30000,
  "retries": 2
}

Environment variables

Variable	Purpose	Default
`ARKVEIL_BASE_URL`	API base URL	`https://api.arkveil.com`
`ARKVEIL_AUTH_BASE_URL`	Auth service mount point	`<base-url>/api/auth`
`ARKVEIL_CLIENT_ID`	OAuth device-flow client id	`arkveil-cli`
`ARKVEIL_SCOPE`	Optional OAuth scope	unset
`ARKVEIL_TOKEN`	Bearer token override	unset
`ARKVEIL_WORKSPACE_ID`	Workspace id	unset
`ARKVEIL_TIMEOUT`	Request timeout (ms)	`30000`
`ARKVEIL_RETRIES`	Retry attempts	`2`
`ARKVEIL_CONFIG_DIR`	Config/credentials directory	`~/.config/arkveil`
`NO_COLOR`	Disable color output	unset

Networking

Every request is bounded by the configured timeout.
Idempotent requests (GET, PUT, DELETE) are retried with exponential backoff on 429, 502, 503, 504, and network errors, honoring Retry-After when present.
POST and PATCH requests are never retried.
Every request carries an x-request-id, visible with --verbose.
List commands are not paginated — they return the complete collection.

Exit codes

Code	Meaning
`0`	Success
`1`	Generic/unexpected error
`2`	Usage error
`3`	Auth required or rejected
`4`	Not found (404)
`5`	Network failure or timeout
`6`	API error response
`7`	Invalid local config
`8`	Test run failed (assertion mismatch)
`9`	Test run errored (couldn't run at all)
`130`	Cancelled at an interactive prompt

8 and 9 are designed as CI gates for arkveil tests run / run-all; when a batch contains both failures and errors, 9 takes precedence. Errors print a one-line message plus an actionable hint — never a raw stack trace; pass --verbose to see the underlying cause.

JSON output for scripting

Any command accepts --json to emit the raw API payload (or a small status object for delete/login) as JSON on stdout, with spinners, color, and status text suppressed:

arkveil tags list --json | jq '.[].slug'
arkveil eval explain -a orders:read --user '{"role":"admin"}' --json | jq .granted

In --json mode, errors go to stderr as a structured object, and the process exit code still reflects the failure category:

{ "error": { "message": "...", "hint": "...", "exitCode": 6 } }

Destructive commands (delete, admin reset-demo) always prompt for confirmation interactively, and refuse to run non-interactively unless --yes is passed — this applies even with --json.

JSON payload flags

Flags that accept a JSON payload (--data, --request-schema, --projection, --fixtures, --spec, and similar) accept three forms:

--data '{"a":1}'        # inline JSON
--data @payload.json     # from a file
--data -                 # from stdin
echo '{"a":1}' | arkveil schemas set user --data -