`excalibur-ctl` CLI reference¶

A small operator CLI that talks to the control API. Designed for shell-driven workflows, scripts, and CI integration.

Configuration¶

export EXCALIBUR_API_URL=http://localhost:8443      # default
export EXCALIBUR_API_TOKEN=…                         # required when RBAC is enabled

Commands¶

Each command targets the control API at EXCALIBUR_API_URL.

`status` / `health`¶

excalibur-ctl status
excalibur-ctl health

Quick stats and health probe.

`placeholder`¶

excalibur-ctl placeholder list
excalibur-ctl placeholder add \
  --name      XCALIBUR_GITHUB_TOKEN \
  --value     ghp_… \
  --provider  github

Adds or updates an upstream credential placeholder. add is upsert — same name, new value rotates atomically. See Rotating a credential.

`service-credential` (alias: `svc`)¶

excalibur-ctl svc list
excalibur-ctl svc create \
  --name   "ci-runner" \
  --user   ci \
  --source 10.0.0.0/8
excalibur-ctl svc rotate --id svc-…
excalibur-ctl svc revoke --id svc-…

Mints, rotates, and revokes long-lived service credentials. See Onboarding a workload.

`mode`¶

excalibur-ctl mode get
excalibur-ctl mode set discovery
excalibur-ctl mode set shadow
excalibur-ctl mode set enforcement

Switch the operating mode. The mode is persisted across restarts. enforcement is the production posture; discovery is observe- only.

`config`¶

excalibur-ctl config example > /etc/excalibur/config.json
excalibur-ctl config validate /etc/excalibur/config.json

example prints a fully-commented baseline configuration to stdout. validate checks a config file syntactically and semantically without applying it.

`help`¶

excalibur-ctl help
excalibur-ctl --help
excalibur-ctl -h

Exit codes¶

Code	Meaning
0	Success
1	Invalid arguments or unknown command
2	API call failed (non-2xx response)
3	Network / authentication failure

Common patterns¶

Copy-paste recipes for frequent operator tasks.

Bootstrap a new workload identity¶

excalibur-ctl svc create --name "ci-runner" --user ci --source 10.0.0.0/8 \
  | jq -r '"PROXY_TOKEN=" + .token'

Rotate a placeholder from a vault hook¶

NEW=$(vault read -field=value secret/stripe/live)
excalibur-ctl placeholder add \
  --name XCALIBUR_STRIPE_SECRET_KEY \
  --value "$NEW" \
  --provider stripe

Flip to enforcement after warm-up¶

excalibur-ctl mode set enforcement
echo "warmup complete; enforcement live at $(date -Iseconds)"

excalibur-ctl CLI reference¶