castiadocscli

ENDE
docs / cli

The Castia CLI

Operate Castia from the tools your team already has — under the same organization scope, capability policy, audit trail, and human approval checkpoint as every other client.

Your agents can operate Castia. They cannot outrank its controls.

CLI + Operator API · a held launch reads deliveryStarted: false and sends no message

what it is

A bounded command set over the Operator API. Not a shell into the product — a fixed grammar whose reach is set by the capabilities the server actually advertises, not by who is typing. A command can be syntactically valid while the server still rejects an unavailable capability.

Every client enters the same way. A human operator, Claude, Codex, or Microsoft Copilot — each one gets the same organization scope, the same capability policy, the same immutable audit trail, and the same human approval checkpoint.

install, authenticate & discover

Install @castia/cli (Node.js 20 or newer), authenticate, check the connection, then always discover what the server advertises before automating it:

start in a test Organization with non-production data
npm install -g @castia/cli
castia auth login --url https://app.castia.ai
castia doctor --json
castia capabilities list --json

your first governed session

Six commands take a campaign run from discovery to a watched, human-approved operation. The sequence below uses the real public grammar; placeholders like RUN_ID come from your own workspace.

  1. Choose the organization scope

    Everything is scoped to an Organization. Entering one loads its capability policy and turns the audit trail on.

    sandbox
    castia org use ORG_ID

  2. Find the work waiting on a human

    --needs-human lists operations blocked on a person — the queue the checkpoint feeds.

    sandbox
    castia work --needs-human --json

  3. Review the evidence

    Read the evidence view before acting. The projection carries the revision you will pin in the next step; the server decides what it contains.

    sandbox
    castia show campaign-run:RUN_ID --view evidence --json

  4. Request the launch — it holds

    A launch request pins the exact revision you reviewed and uses a stable idempotency key. The operation lands held: campaign.launch@v1 verifies the frozen scope, requires exact human approval, and returns deliveryStarted: false — it sends no message.

    sandbox
    castia do campaign.launch@v1 campaign-run:RUN_ID \
  --expected-revision REVISION \
  --idempotency-key launch-RUN_ID-1 \
  --wait --json

  5. Approve as a human operator

    Approval binds to the operation's fingerprint — the exact request reviewed, not a class of similar ones. The underlying capability is human actor only: an agent session can prepare everything up to this point, and no further.

    sandbox
    castia approve OPERATION_ID \
  --fingerprint 64_CHARACTER_LOWERCASE_HEX \
  --json

  6. Watch the audit trail

    Follow the durable operation events as newline-delimited envelopes — every decision, actor, and binding on the record.

    sandbox
    castia wait OPERATION_ID --follow --jsonl

the rails

The refusals are not error handling bolted on afterwards; they are the product's shape:

unavailable capability
Grammar is not permission. A command the server does not advertise fails closed with capability_unavailable — there is no fallback to legacy UI routes.
unpinned mutation
Actions marked with an exact revision require --expected-revision. If the resource moved since your review, the pin fails closed instead of executing something unreviewed.
unbound approval
approve requires --fingerprint and binds to it exactly. “Approve whatever is pending” does not exist here.
agent at the checkpoint
operation.approve@v1, operation.reject@v1, draft.approve@v1, and draft.reject@v1 are human actor only. Agent clients prepare; a human decides.
dry run
--dry-run is an offline request preview. It never grants authority or starts an effect.

for agents

Claude and Codex issue the same bounded requests through the CLI; Microsoft Copilot goes through a server-enforced allowlist that excludes launch and approval. Same scope, same policy, same audit trail, same human checkpoint either way. A machine-readable index of these docs lives at /llms.txt, and every command on this page is copyable as it runs.

more guides

llms.txt the full command reference see it run on the homepage docs home