Castia CLI command reference

This page separates the CLI grammar from the Operator capabilities the server actually advertises. The CLI is generic: a command can be syntactically valid while the server still rejects an unavailable capability. Always discover the current server before automating it:

discover before automating

castia capabilities list --json
castia capabilities show company.show@v1 --json

public grammar

This block is checked against castia --help in CI.

castia --help · checked in CI

Usage: castia [global options] <command>

Commands:
  auth login|logout|status
  org list|show|use
  token create|list|revoke
  usage [--days <1-365>]
  usage history [--cursor <opaque>] [--limit <1-100>]
  credits
  credits controls [set --input <@file|->]
  capabilities list|show
  work [--needs-human]
  list <resource>
  show <kind:id>
  do <action@v1> [kind:id]
  approve <operation-id> --fingerprint <hash>
  reject <operation-id> --reason <text>
  wait <operation-id> [--follow]
  watch <operation-id>
  watch <kind:id>
  operation show|cancel <operation-id>
  config list|get|set
  doctor
  completion bash|zsh|fish|powershell
  version

Aliases: login, whoami, capabilities, inspect, run, follow

Global options:
  --org <id>  --profile <name>  --url <https-origin>
  --json  --jsonl  --quiet  --dry-run  --wait
  --input <@file|->  --idempotency-key <key>  --expected-revision <revision>
  --cursor <cursor>  --after <cursor>  --limit <1-100>
  --days <1-365>
  --fingerprint <hash>  --reason <text>
  --needs-human  --view <evidence|audit|review>

--json emits one versioned envelope. --jsonl emits newline-delimited envelopes for follow/watch flows. --quiet suppresses normal output. Those three modes are mutually exclusive. Use --input @file or --input -; action input is capped at 64 KiB. --dry-run is an offline request preview and never grants authority or starts an effect.

available Operator capabilities

The list below is checked against the production capability registry. Role and scope are minimums. revision means the action must name the exact current resource revision.

campaign-run.show@v1
read one Campaign Run
membercampaign:read
campaign.audience.create@v1
create a visible audience pinned to one Segment Playbook Version
membercampaign:write
campaign.audience.freeze@v1
freeze the pinned audience
membercampaign:writerevision
campaign.drafts.generate@v1
create the first immutable draft revision
membercampaign:writerevision
campaign.hold@v1
hold a Campaign Run with a reason
membercampaign:writerevision
campaign.launch@v1
bind a human approval to the exact frozen launch scope
membercampaign:launchrevisionhuman approvalCurrent limitation: it starts zero delivery.
campaign.outcome.record@v1
record an allowlisted outcome
membercampaign:writerevision
campaign.prepare@v1
prepare the frozen Campaign Run scope
membercampaign:writerevision
campaign.resume@v1
resume a held Campaign Run
membercampaign:writerevision
campaign.run.create@v1
create a manual or mailbox-draft run from one visible audience
membercampaign:write
capability.list@v1
discover capabilities and their schemas
membercapability:read
company.archive@v1
soft-archive a Company
admincompany:archiverevisionhuman approval
company.followup.schedule@v1
schedule a Company follow-up
membercompany:writerevision
company.import@v1
import or de-duplicate a Company
membercompany:write
company.list@v1
list visible Companies
membercompany:read
company.research@v1
run governed external Company research
membercompany:researchrevision
company.show@v1
read one visible Company
membercompany:read
credit-controls.show@v1
report whether credit-control writes are currently supported
admincredits:readCurrent limitation: writes are unavailable until a server budget policy exists.
credits.show@v1
read current credit balance and billing state
admincredits:read
draft.approve@v1
human approval of one immutable draft revision
membercampaign:writerevisionhuman actor only
draft.reject@v1
human rejection of one immutable draft revision
membercampaign:writerevisionhuman actor only
draft.revise@v1
append an immutable draft revision
membercampaign:writerevision
icp.list@v1
list published ICP selections
membericp:read
icp.show@v1
read one published ICP selection
membericp:read
operation.approve@v1
approve one exact operation fingerprint
adminoperation:approverevisionhuman actor only
operation.cancel@v1
cancel eligible queued or approval-held work
memberoperation:controlrevision
operation.follow@v1
stream durable operation events
memberoperation:read
operation.reject@v1
reject one exact operation fingerprint with a reason
adminoperation:approverevisionhuman actor only
operation.show@v1
read one safe operation projection
memberoperation:read
segment-playbook-version.list@v1
list immutable published Segment Playbook Versions
memberplaybook:read
segment-playbook-version.show@v1
read one immutable published Segment Playbook Version
memberplaybook:read
usage-event.list@v1
list recent credit ledger events
admincredits:read
usage.show@v1
read bounded credit usage
adminbilling:readcredits:read
work.list@v1
list tenant-scoped Operator work
memberoperation:read

resource commands

sh · reads and follows

castia list company --limit 25 --json
castia show company:COMPANY_ID --json
castia list icp --json
castia show icp:PUBLICATION_ID --json
castia list segment-playbook-version --json
castia show segment-playbook-version:VERSION_ID --json
castia usage --days 30 --json
castia usage history --limit 25 --cursor OPAQUE_CURSOR --json
castia credits --json
castia credits controls --json
castia show campaign-run:RUN_ID --view review --json
castia work --needs-human --json
castia operation show OPERATION_ID --json
castia wait OPERATION_ID --follow --jsonl
castia watch campaign-run:RUN_ID --jsonl

The optional show views are review, evidence, and audit. The server decides what each safe projection contains; the CLI does not reinterpret or expand it.

usage and credits

All four reads require an Organization admin. Use a human admin login, or an Organization-bound admin service credential with the minimum scopes needed:

Command	Required scopes	Behavior
castia usage [--days 1-365]	billing:read, credits:read	Read a bounded usage summary. Omitting --days uses the server's current-period default.
castia usage history [--cursor ...] [--limit 1-100]	credits:read	Page through the Organization credit ledger using an opaque cursor.
castia credits	credits:read	Read the current balance and safe billing-state projection.
castia credits controls	credits:read	Read whether server-side credit controls are available; currently reports read-only/unavailable.

These commands do not mutate balances, purchase or top up credits, open a Stripe portal, change a subscription, or issue/revoke credit grants. The server remains the authority for tenant, role, scope, period, ledger, and balance calculations.

action inputs

Every mutation should use a stable idempotency key. Actions marked with an exact revision also require --expected-revision.

Action	Target	Required JSON input
campaign.audience.create@v1	segment-playbook-version:VERSION_ID	name, relationship (cold or warm), targets (1–20 exact objects with companyId and optional companyContactId)
campaign.audience.freeze@v1	campaign-run:RUN_ID	{}
campaign.drafts.generate@v1	campaign-run:RUN_ID	targetId, subject, body
campaign.hold@v1	campaign-run:RUN_ID	reason
campaign.launch@v1	campaign-run:RUN_ID	{}
campaign.outcome.record@v1	campaign-run:RUN_ID	targetId, kind (delivered, replied, meeting_booked, or converted)
campaign.prepare@v1	campaign-run:RUN_ID	{}
campaign.resume@v1	campaign-run:RUN_ID	{}
campaign.run.create@v1	campaign-audience:AUDIENCE_ID	name, channel (manual or personal_draft), and 1–2 exact variants with key, subjectTemplate (1–500 characters), bodyTemplate (1–3,500 characters); optional routingMode, angle; personal_draft also requires senderMailboxId and accepts dailyDraftLimit, draftTimeZone
company.archive@v1	company:COMPANY_ID	{}
company.followup.schedule@v1	company:COMPANY_ID	followUpDate; optional followUpReason, temperature, draftMessage
company.import@v1	none	exactly one of url or domain; optional Company/contact fields
company.research@v1	company:COMPANY_ID	optional campaignPlayId
draft.approve@v1	campaign-run:RUN_ID	targetId, revisionId, revision, contentHash
draft.reject@v1	campaign-run:RUN_ID	approval fields plus reason
draft.revise@v1	campaign-run:RUN_ID	targetId, previousRevisionId, previousRevision, subject, body

sh · pinned, idempotent, held

castia do campaign.audience.create@v1 \
  segment-playbook-version:PLAYBOOK_VERSION_ID \
  --input @audience.json \
  --idempotency-key audience-PLAYBOOK_VERSION_ID-1 \
  --wait --json

castia do campaign.run.create@v1 campaign-audience:AUDIENCE_ID \
  --input @run.json \
  --idempotency-key run-AUDIENCE_ID-1 \
  --wait --json

castia do company.followup.schedule@v1 company:COMPANY_ID \
  --input @follow-up.json \
  --expected-revision 2026-08-12T08:00:00.000Z \
  --idempotency-key followup-COMPANY_ID-20260812 \
  --wait --json

Example creation files use only caller-selectable fields; Organization, actor, role, playbook pin, run relationship, mailbox owner, delivery policy, provider fields, and internal revisions remain server authority:

json

{"name":"Founder audience","relationship":"cold","targets":[{"companyId":"COMPANY_ID"}]}

json

{"name":"Founder campaign","channel":"manual","variants":[{"key":"control","subjectTemplate":"Hello","bodyTemplate":"Body"}]}

Manual creation is bound to draft_only; personal draft creation is bound to mailbox_draft_only. Neither action sends a message or starts delivery.

approval, rejection, cancellation

Approval is a separate human command bound to the receipt's current fingerprint:

sh · human actor only

castia approve OPERATION_ID \
  --fingerprint 64_CHARACTER_LOWERCASE_HEX \
  --expected-revision 1 \
  --idempotency-key approve-OPERATION_ID-1 \
  --json

castia reject OPERATION_ID --reason "Scope is not approved" --json
castia operation cancel OPERATION_ID --json

If approve omits --expected-revision, the CLI first reads the safe operation projection and derives the revision only when the fingerprint still matches exactly. Reject and cancel also inspect before executing and bind to the current revision and fingerprint.

explicitly unavailable

castia operation retry OPERATION_ID is reserved grammar and always fails closed with capability_unavailable. operation.retry@v1 is not advertised.
castia credits controls set --input ... fails locally with capability_unavailable. It does not read the input or make a network request. The current product has read-only credit controls only; write controls need a real server-side budget policy first.
A Campaign retry capability is not advertised.
Real Campaign delivery is not connected. campaign.launch@v1 currently freezes and verifies the scope, requires exact human approval, records that binding, and returns deliveryStarted: false; it sends no message.
The coverage matrix still labels many UI-only resources and mutations as planned. CLI syntax is not permission to call them, and there is no fallback to legacy UI routes.

the cli guide docs home