Agents and scripts

Start with the guide and catalogCopy Anchor Link

airship guide
airship commands --json
airship whoami --json

guide adapts to the caller and setup. The catalog lists flags, effects, output schemas, exit codes and agent_safe metadata. Check caller capabilities before performing a write.

Use the ready gateCopy Anchor Link

airship start worker --runtime codex --worktree --json
airship wait worker --until ready --timeout 60 --json
airship send worker --text "Review the tests" --queue --json

Run from a Git repository when using --worktree. Use wait and queued delivery rather than typing directly into a tmux pane. A failed wait does not grant permission to send.

Ask for a human decisionCopy Anchor Link

An outside agent identifies itself when asking:

airship ask --as nightly --question "Run the extended checks?" --rec "Run them" --json

Set decision_id to the id returned above, then wait:

airship decisions get "$decision_id" --wait 60 --json

Agents must never answer decisions or invent operator messages. A human answers in the app or from an external shell. agent_safe metadata is guidance, not a security sandbox.

Parse the protocolCopy Anchor Link

Use --json or AIRSHIP_JSON=1. Ordinary JSON results contain one airship/v1 envelope. On success, ok is true and data holds the result. Failures contain error.kind, error.code, error.message and error.hint; warnings is always present.

Streaming commands emit event lines before their final envelope. A line containing ok is the final result. status --watch continues until stopped. attach is interactive and schema --raw emits a bare schema.

airship schema envelope --raw
airship schema status --raw
airship schema error-codes --raw

Inspect the specific code and hint. Partial results and move outcomes may include useful data even on failure. Do not blindly retry writes.

Read the version-pinned wire protocol for full shapes, and the generated CLI reference for commands.