troubleshooting & revocation
Start with:
castia doctor --json
castia auth status --json
castia capabilities list --jsonKeep the requestId from an error envelope when contacting support. Never include a token, secret file, or raw authorization header.
exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Terminal operation or unexpected failure |
| 2 | Usage, config, compatibility, protocol, or unavailable capability |
| 3 | Authentication, authorization, or Organization binding failure |
| 4 | Human approval required |
| 5 | Held, stale, conflicting, cleanup-required, or outcome-uncertain state |
| 6 | Retryable network/dependency/size failure |
common failures
| Error or symptom | Safe response |
|---|---|
| authentication_required | Run castia auth login, or inject CASTIA_TOKEN from a trusted vault. |
| credential_invalid, expired, or revoked | Remove/unset the stale credential and authenticate or rotate it. |
| organization_required | Set --org, CASTIA_ORG, or use an authorized profile. |
| organization_not_authorized | Sign in with a separate profile and explicitly approve that Organization. |
| forbidden | Discover the capability and request the missing role/scope; do not broaden to * by default. |
| workspace_access_required | Restore the Organization's active workspace entitlement; credentials cannot bypass it. |
| approval_required | Inspect the safe review and have an authorized human approve or reject the exact fingerprint. |
| stale revision/fingerprint | Re-read the resource/operation and decide again; do not reuse an old approval. |
| idempotency_conflict | Do not change a request under an existing key. Use the original exact request or a new key for genuinely new work. |
| network_unavailable | Verify the final HTTPS origin and network, then replay only with the original deterministic idempotency key. |
| redirect_refused | Set CASTIA_URL to the final trusted HTTPS origin. |
| credential_store_unavailable | Fix Keychain/Secret Service/DPAPI, or use a vault-injected CASTIA_TOKEN. |
| capability_unavailable | Re-run discovery. The CLI never falls back to legacy routes. |
| response_too_large or stream_too_large | Narrow the request or resume the stream from its last cursor. |
credential revocation and incident runbook
Use this runbook for a planned rotation, lost device, leaked secret, suspicious agent activity, or partner/model exposure. Preserve the credential ID, Organization ID, actor, time window, request IDs, and operation IDs before removing local evidence. Never copy the credential itself into a ticket, prompt, transcript, or chat.
revoke a human cli credential
castia auth logout --profile workLogout asks the server to revoke the credential before deleting it locally. If the network fails and revocation cannot be confirmed, the CLI intentionally keeps the local credential and returns credential_cleanup_required; retry logout when the server is reachable. If the server confirms the credential is already expired/revoked, local deletion proceeds.
auth logout cannot revoke a token supplied through CASTIA_TOKEN. Unset it locally and revoke the service credential by ID.
revoke a service credential
From a separate active admin/human profile:
castia token list --profile admin --json
castia token revoke CREDENTIAL_ID --profile admin --jsonThen delete the corresponding entry from the CI/agent secret manager and stop jobs that may still hold it in process memory. Listing returns safe metadata and prefixes, never the secret.
If the creating profile is unavailable, use another authorized Organization admin. A lost secret cannot be recovered; revoke the ID and create a replacement with new material.
suspected compromise
Revoke the credential server-side immediately.
Remove it from the OS store or vault and terminate processes using it.
Create a replacement with a different ID, the narrowest scopes, and an expiry.
Review the Organization-scoped operation ledger and partner audit logs by credential/actor and time.
Investigate any external provider separately; CLI revocation does not revoke downstream provider credentials.
Treat a token copied into a prompt, transcript, repository, or log as exposed.
If Microsoft Copilot or another partner gateway is involved, also disable the partner integration, revoke its Castia credential, terminate relevant Entra/OBO sessions when deployed, preserve tenant audit events, and ask the partner to apply its retention/deletion procedure. Castia credential revocation does not erase provider prompts, telemetry, exports, or backups.
tabletop verification checklist
Run this checklist with a non-production Organization and synthetic data at least before partner launch and after material auth, adapter, or incident-process changes:
Record the test Organization, credential ID/prefix, actor, scopes, expiry, start time, and incident owner without recording the secret.
Confirm castia auth status --json and one allowlisted read succeed before revocation; save request and operation IDs.
Revoke the exact human or service credential from a separate authorized admin session.
Confirm the revoked credential fails both an existing-resource read and a mutation with authentication/authorization exit code 3.
Confirm another Organization-bound credential cannot read the test Organization and that changing X-Castia-Organization fails closed.
Confirm an already-open agent/job is terminated and the secret is removed from the OS store, vault, CI variables, caches, and queued jobs.
Review the Operator ledger by credential/actor and time; reconcile every prepared, running, held, completed, failed, and outcome_uncertain operation.
For approval incidents, verify stale revisions and fingerprints cannot be reused and a service identity cannot approve or reject.
For Microsoft/partner incidents, disable the adapter, preserve partner/tenant logs, verify its allowlist and prompt-minimization policy, and exercise the partner's deletion/retention process.
For external-provider activity, revoke provider credentials separately and reconcile uncertain side effects; do not infer provider revocation from Castia revocation.
Confirm logs, CLI JSON/JSONL, support artifacts, prompts, and error output redact the secret and authorization header.
Create a replacement only after containment, using new material, the narrowest scopes, an expiry, and a recorded owner.
Record timestamps and evidence for detection, revocation, job termination, downstream containment, recovery, and lessons learned.
A tabletop is evidence that the runbook was exercised, not proof of production security. Do not test campaign delivery through campaign.launch@v1; delivery is not connected.
installation and publication
If npm install -g @castia/cli returns a registry-not-found error, the package has not yet been published to that registry. Reviewers can use npm install -g ./packages/cli from the repository. Do not work around publication by installing an unverified third-party package or a curl | sh script.
The app renders docs/cli/*.md through dedicated /docs/cli routes. If that page is missing in an environment, verify that the environment is running a version containing those routes; a local documentation or package test does not deploy them.