CLI

DriftGate CLI is canonical and envelope-native.

Install Methods


npm i -g @driftgate/cli


brew tap driftgate/tap
brew install driftgate


docker run --rm ghcr.io/driftgate/cli:1.0.1 --help

Auth Bootstrap

Runtime session auth (human admin):


driftgate login --api-base https://api-staging.driftgate.ai

Machine admin auth (service-account key):


export DRIFTGATE_API_KEY=<your-api-key>

Auth contract:

session + execute commands require a user session token from driftgate login.
Admin/config commands (policies, routes, connectors, secrets, webhooks) and headless execution endpoints accept DRIFTGATE_API_KEY=dgk_....
dg_sa_* values are service-account IDs, not token secrets.
Canonical matrix: Auth + Token Contract.
Operator runbook: Operator Auth + Token Runbook.

Command Auth Matrix

Command Family	Required Credential	Example
`session`, `execute`, `execution status/events/wait`	Bearer session token from `driftgate login`	`driftgate execute --agent refund-agent --input '{"orderId":"123"}'`
`policies`, `routes`, `connectors`, `secrets`, `webhooks`	`x-driftgate-api-key` via `DRIFTGATE_API_KEY=dgk_...`	`driftgate policies list --workspace <workspaceId>`
Headless execution API endpoints (`/headless/`, `/r/`)	`x-driftgate-api-key` via `DRIFTGATE_API_KEY=dgk_...`, bearer session auth, or execution credentials where supported by the endpoint	`curl -H "x-driftgate-api-key: $DRIFTGATE_API_KEY" .../headless/executions`

Expected credential failures:

dg_sa_* in DRIFTGATE_API_KEY fails because it is an identifier, not a secret.
dgk_* on session or execute runtime commands fails because those commands require session auth; use dgk_* for admin/config commands or direct headless execution API calls.

Primary Commands


driftgate session start --agent refund-agent
driftgate session execute <sessionId> --input '{"orderId":"123"}'


driftgate execute --agent refund-agent --input '{"orderId":"123"}'


driftgate execution status <executionId>
driftgate execution events <executionId>
driftgate execution wait <executionId> --timeout-ms 15000


driftgate policies list --workspace <workspaceId>
driftgate routes list --workspace <workspaceId>

JSON Output Contract


driftgate execute --agent refund-agent --input '{"orderId":"123"}' --json


{
  "data": {
    "executionId": "exec_123"
  },
  "meta": {
    "requestId": "req_123",
    "timingMs": {
      "total": 127
    }
  },
  "error": null
}

Notes

CLI default output is the canonical envelope (data, meta, error)
Legacy run and status commands are deprecated from public UX
Container image ghcr.io/driftgate/cli:1.0.1 supports linux/amd64 and linux/arm64
If architecture auto-detection fails, pass --platform linux/amd64 or --platform linux/arm64