docs / cli / auth

authentication & credentials

The Castia CLI is the supported, agent-friendly client for the versioned Castia Operator API. It gives humans, Claude, Codex, CI, and partner tooling one governed route into Castia without depending on the UI. It does not bypass Castia policy: control extends only to capabilities the authenticated server advertises.

current status

Surface	Status
CLI package and executable	Implemented and clean-package tested on Node.js 20+
Human device login	Implemented with PKCE and OS credential storage
Organization-bound service tokens	Implemented with roles, scopes, optional expiry, and revocation
Capability discovery, safe reads, governed actions, operation follow/control	Implemented for the advertised set
Campaign draft and run control	Implemented through exact pinned revisions
Usage and credit read commands	Implemented through castia usage, castia usage history, castia credits, and castia credits controls
Real Campaign message delivery	Unavailable; launch binds approval and starts zero delivery
Generic operation retry	Unavailable and fail-closed
Full parity with every UI function	Planned; only advertised capabilities are controllable
Public npm release	Published to the approved registry
Public /docs/cli website route	Implemented and live

install

Node.js 20 or newer is required.

From the approved registry:

sh · from the approved registry

npm install -g @castia/cli
castia version

For CI, install it as an exact development dependency so the package lock pins the approved release:

sh · CI, exact pinned release

npm install --save-dev --save-exact @castia/cli@latest
npx castia capabilities list --json

For review from this repository before publication:

sh · review build from the repository

npm ci
npm run build --workspace @castia/cli
npm install -g ./packages/cli
castia version

The package has no runtime dependencies and deliberately has no curl | sh installer. See Testing and review for the clean tarball and HTTP E2E checks.

human sign-in

sh · PKCE device login

castia auth login --profile work
castia auth status --profile work
castia org list --profile work
castia org use ORGANIZATION_ID --profile work
castia doctor --profile work --json

Login opens the Castia approval page, displays a short-lived code, and exchanges it with PKCE. The resulting human credential is bound to the approved Organization and stored in macOS Keychain, Linux Secret Service, or Windows current-user DPAPI. If a secure store is unavailable, login fails closed.

One profile cannot silently switch to another membership. Sign in under another profile and approve the other Organization instead.

agent or CI sign-in

An Organization admin first creates a least-privilege service credential from a human-authenticated profile:

sh · admin, from a human-authenticated profile

castia token create \
  --name codex-ci \
  --role member \
  --scopes capability:read,company:read,operation:read \
  --secret-file /secure/new/path/castia.token

The destination must be a new exclusive file; the CLI writes mode 0600 and never prints the token. It can instead use --store-profile NEW_PROFILE to place the credential in the OS store.

Headless agents should receive the secret from their vault at process start:

sh · vault at process start

export CASTIA_URL=https://app.castia.ai
export CASTIA_ORG=ORGANIZATION_ID
export CASTIA_TOKEN="$(your-secret-manager read castia/operator-token)"
castia capabilities list --json
castia usage --json
castia credits --json

Do not paste the token into an AI prompt, command argument, repository, transcript, or log. Claude and Codex need only shell access to the installed CLI; they do not require a Castia-specific SDK.

publication note

The canonical source of these pages is the product repository's CLI documentation, which the Castia app also renders through its own /docs/cli routes. Command grammar and the capability list are checked against the CLI and the production registry in CI.

the cli guide command reference docs home