Sessions

Generated from the CLI catalog at fd47c2b.

`start`

Start a managed unit in its own tmux session.

airship start [<name>] [--idle | --prompt T | --prompt-file F] [--role ROLE] [--runtime claude|codex] [--cwd DIR] [--worktree] [--base REF] [--branch B] [--tier T] [--model M] [--effort E] [--ctx-limit N|PCT] [--weight light|heavy] [--permissions ask|auto] [--tag k=v]... [--cap +cap,…] [--set key=value]... [--resume SID]

Effects: write. Agent safe: yes. Scope: auto.

Exits: 0, 1, 2, 3, 4, 6, 7, 14.

--host: host id or auto. --dry-run: accepted.

Related JSON schema: airship schema unit.

Argument	Meaning
`name`	unit name (omitted: role template or role-N)
`--idle`	wait at the runtime prompt without a framework kickoff
`--role`	orchestrator \| lane \| agent \| a framework orchestrator role
`--runtime`	agent runtime
`--cwd`	working directory on the target host
`--worktree`	new git worktree under $AIRSHIP_HOME/worktrees
`--base`	worktree base ref (default: the remote's default branch)
`--branch`	worktree branch name
`--prompt`	first message
`--prompt-file`	first message from a file
`--tier`	framework tier
`--model`	model id
`--effort`	effort level
`--ctx-limit`	refresh/compact point (350k, 70%)
`--weight`	placement weight
`--permissions`	stricter than the host only
`--tag`	framework tag k=v
`--cap`	add capabilities to an agent (+inbox,+refresh,+restart)
`--set`	framework setting for this unit
`--resume`	start on an existing session id

`adopt`

Bring a hand-started Claude or Codex pane under management.

airship adopt <pane> [--as NAME] [--role agent|orchestrator] [--in-place | --reparent] [--wait S] [--force]

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Related JSON schema: airship schema unit.

Argument	Meaning
`pane`	[host:]server:%pane
`--as`	unit name
`--role`	role after adopting
`--in-place`	tag the pane where it is (default for agent)
`--reparent`	resume the same session on the airship server
`--wait`	reparent: wait up to S seconds for readiness (max 14400)
`--force`	reparent without waiting (loses the turn in flight)

`release`

Undo an in-place adopt (nothing is killed).

airship release <target>

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name

`send`

Type a message into a unit through the ready gate.

airship send <target> (--text T | --file F | --stdin) [--queue]

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)
`--text`	message text
`--file`	message from a file (- = stdin)
`--stdin`	message from stdin
`--queue`	if not ready, deliver at the next ready point

`upload`

Copy local files to a host and print their paths there.

airship upload <file>…

Effects: write. Agent safe: yes. Scope: controller.

Exits: 0, 1, 2, 4, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`files`	local files or directories

`attach`

Attach a terminal to a unit or pane (the only interactive command).

airship attach <target> [--nest]

Effects: interactive. Agent safe: no. Scope: remote.

Exits: 0, 1, 2, 4, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)
`--nest`	attach inside another tmux (TMUX unset)

`stop`

Kill a unit's process tree (the unit stays; restart resumes it).

airship stop <target>

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)

`restart`

Respawn a unit on the same session id.

airship restart <target> [--message T] [--fresh]

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)
`--message`	send this once ready
`--fresh`	start a new session instead

`refresh`

Request a context refresh now.

airship refresh <target> [--queue]

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)
`--queue`	if the gate is closed, refresh at the next ready point

`close`

Archive a unit to history and remove it.

airship close <target>

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Related JSON schema: airship schema history.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)

`rename`

Rename a unit.

airship rename <target> <new>

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Related JSON schema: airship schema unit.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)
`new`	new unit name

`auto`

Turn tick nudges and restarts on or off for a unit.

airship auto <target> <state>

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)
`state`	on or off

`set`

Change model, effort or ctx limit of a running unit.

airship set <target> [--model M] [--effort E] [--ctx-limit N|PCT] [--apply next-restart|idle|now]

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 4, 5, 6, 7, 9.

--host: host id. --dry-run: accepted.

Argument	Meaning
`target`	[host:]name, or a pane ([host:]server:%pane)
`--model`	model id
`--effort`	effort level
`--ctx-limit`	refresh/compact point
`--apply`	when to restart for the change

`history resume`

Start a new unit on an archived session.

airship history resume <id> [--as NAME]

Effects: write. Agent safe: yes. Scope: remote.

Exits: 0, 1, 2, 3, 4, 6, 7.

--host: host id. --dry-run: accepted.

Related JSON schema: airship schema unit.

Argument	Meaning
`id`	history id
`--as`	unit name (default: the original name)

`history forget`

Delete a history record.

airship history forget <id>

Effects: write. Agent safe: yes. Scope: local.

Exits: 0, 1, 2, 4.

--host: host id. --dry-run: accepted.

Argument	Meaning
`id`	history id

`reap`

Close finished oneshot units and dead agent panes into history.

airship reap [--role orchestrator|lane|agent]

Effects: write. Agent safe: yes. Scope: fanout.

Exits: 0, 1, 2, 7, 8.

--host: host id or all. --dry-run: accepted.

Argument	Meaning
`--role`	only this role

startCopy Anchor Link

adoptCopy Anchor Link

releaseCopy Anchor Link

sendCopy Anchor Link

uploadCopy Anchor Link

attachCopy Anchor Link

stopCopy Anchor Link

restartCopy Anchor Link

refreshCopy Anchor Link

closeCopy Anchor Link

renameCopy Anchor Link

autoCopy Anchor Link

setCopy Anchor Link

history resumeCopy Anchor Link

history forgetCopy Anchor Link

reapCopy Anchor Link

`start`

`adopt`

`release`

`send`

`upload`

`attach`

`stop`

`restart`

`refresh`

`close`

`rename`

`auto`

`set`

`history resume`

`history forget`

`reap`