CLI Reference

Complete command reference for the ark CLI.

ark tui

Launch the interactive TUI dashboard.

$ ark tui

Opens the terminal dashboard with 6 tabs: Sessions, Agents, Tools, Flows, History, Compute. See the TUI Guide for keyboard shortcuts.

ark exec

Run a session non-interactively. Designed for CI/CD pipelines — blocks until the session completes, fails, or times out.

$ ark exec --repo . --summary "Fix the login bug" --flow bare
$ ark exec --repo /path/to/repo --summary "Add tests" --timeout 600 --output json

Option	Default	Description
`--repo`	—	Path to the repository
`--summary`	—	Task description for the agent
`--ticket`	—	Ticket identifier (e.g. JIRA key)
`--flow`	`bare`	Flow to run
`--compute`	—	Compute target name
`--group`	—	Assign to a group
`--autonomy`	—	Permission level: `full`, `execute`, `edit`, `read-only`
`--output`	`text`	Output format: `text` or `json`
`--timeout`	—	Maximum runtime in seconds

Exit codes: 0 = completed, 1 = failed, 2 = timeout.

ark session

Manage sessions across their full lifecycle.

ark session start [ticket]

Create a new session.

$ ark session start
$ ark session start PROJ-123 --repo . --summary "Add OAuth" --dispatch

Option	Description
`-r, --repo`	Repository path
`-s, --summary`	Task summary
`-p, --flow`	Flow name (default: `default`)
`-c, --compute`	Compute target name
`-g, --group`	Group name
`-d, --dispatch`	Dispatch immediately after creation
`-a, --attach`	Attach to tmux after dispatch
`--recipe`	Use a recipe template (e.g. `quick-fix`)
`--claude-session`	Import from an existing Claude Code session

ark session list

List all sessions.

$ ark session list
$ ark session list --status running --repo /path/to/repo

Option	Description
`-s, --status`	Filter by status (e.g. `running`, `waiting`, `stopped`)
`-r, --repo`	Filter by repository path
`-g, --group`	Filter by group

ark session show <id>

Show full details for a session including status, stage, flow, and recent events.

$ ark session show s-1a2b

ark session dispatch <id>

Dispatch the agent for the current stage. Launches a new Claude Code process in a tmux session.

$ ark session dispatch s-1a2b

ark session stop <id>

Stop a running session. Kills the agent process and tmux session.

$ ark session stop s-1a2b

ark session resume <id>

Resume a stopped or paused session by re-dispatching the agent.

$ ark session resume s-1a2b

ark session advance <id>

Advance to the next flow stage. Used to pass a manual gate.

$ ark session advance s-1a2b
$ ark session advance s-1a2b --force

Option	Description
`-f, --force`	Force advancement past a gate even if not satisfied

ark session complete <id>

Mark the current stage as done and automatically advance to the next stage.

$ ark session complete s-1a2b

ark session pause <id>

Pause a session without stopping the agent process.

$ ark session pause s-1a2b --reason "waiting for PR review"

Option	Description
`-r, --reason`	Human-readable reason for the pause

ark session attach <id>

Attach to a running agent's tmux session. If the agent is not yet running, dispatches first.

$ ark session attach s-1a2b

ark session output <id>

Show live output from the agent's tmux pane.

$ ark session output s-1a2b
$ ark session output s-1a2b --lines 100

Option	Description
`-n, --lines`	Number of lines to show (default: `30`)

ark session send <id> <message>

Send a message to a running agent via the MCP channel.

$ ark session send s-1a2b "Focus on the login flow only"

ark session clone <id>

Clone a session, creating a new session that resumes the original Claude Code conversation via --resume. The cloned session inherits the repo, flow, and compute of the original. Use --task to give the clone new instructions.

$ ark session clone s-1a2b
$ ark session clone s-1a2b --task "Now add tests" --dispatch

Option	Description
`-t, --task`	Override the task summary for the cloned session
`-d, --dispatch`	Dispatch immediately after cloning

ark session handoff <id> <agent>

Hand off the current session to a different agent (e.g. from implementer to reviewer).

$ ark session handoff s-1a2b reviewer
$ ark session handoff s-1a2b documenter --instructions "Focus on public API"

Option	Description
`-i, --instructions`	Additional instructions for the receiving agent

ark session fork <parent-id> <task>

Fork a child session from a parent for parallel work. The child inherits the parent's repo and compute.

$ ark session fork s-1a2b "Write unit tests for the auth module"

ark session join <parent-id>

Join all forked child sessions back into the parent.

$ ark session join s-1a2b
$ ark session join s-1a2b --force

Option	Description
`-f, --force`	Join even if some children have not completed

ark session events <id>

Show the full event history for a session (dispatches, completions, messages, errors).

$ ark session events s-1a2b

ark session delete <ids...>

Delete one or more sessions and their associated data.

$ ark session delete s-1a2b
$ ark session delete s-1a2b s-3c4d s-5e6f

ark session group <id> <group>

Assign a session to a group.

$ ark session group s-1a2b my-feature

ark search <query>

Full-text search across sessions, events, messages, and Claude Code transcripts. Uses FTS5 when the index is available; falls back to file scanning otherwise.

$ ark search "authentication bug"
$ ark search "OAuth" --transcripts --limit 50
$ ark search "login" --index

Option	Default	Description
`-l, --limit`	`20`	Maximum number of results
`-t, --transcripts`	—	Also search Claude Code JSONL transcripts
`--index`	—	Rebuild the FTS5 index before searching

ark index

Build or rebuild the FTS5 full-text search index over Claude Code transcripts in ~/.claude/projects/.

$ ark index

Note: The index is stored in ~/.ark/ark.db. Run this after importing many sessions or when search results seem stale.

ark agent

Inspect available agents.

ark agent list

List all agents with their model, tool count, and MCP server count.

$ ark agent list

ark agent show <name>

Show full agent configuration including system prompt, tools, and environment variables.

$ ark agent show implementer

ark flow

Inspect available flows.

ark flow list

List all flows with their stage names.

$ ark flow list

ark flow show <name>

Show full flow definition including stage breakdown, agents, and gates.

$ ark flow show default

ark skill

Manage reusable prompt fragments (skills) for agents. Skills are resolved with three-tier lookup: builtin (skills/), global (~/.ark/skills/), project (.ark/skills/).

ark skill list

List all available skills across all tiers.

$ ark skill list

ark skill show <name>

Show the full content of a skill.

$ ark skill show code-review

ark recipe

Manage session templates (recipes) with variables and repo fields. Recipes enable quick-launch sessions from presets. Three-tier resolution: builtin (recipes/), global (~/.ark/recipes/), project (.ark/recipes/).

ark recipe list

List all available recipes across all tiers.

$ ark recipe list

ark recipe show <name>

Show the full definition of a recipe including variables and defaults.

$ ark recipe show quick-fix

To use a recipe, pass --recipe to ark session start:

$ ark session start --recipe quick-fix --repo . --dispatch

Built-in recipes: quick-fix, feature-build, code-review. You can also create a recipe from an existing session with sessionToRecipe.

ark compute

Manage compute resources (local, Docker, EC2). See Compute Providers for setup details.

ark compute create <name>

Create a compute resource record.

$ ark compute create my-ec2 --provider ec2 --size m --region us-east-1
$ ark compute create dev-box --provider docker --image ubuntu:22.04 --devcontainer

Option	Description
`--provider`	Provider: `local`, `ec2`, or `docker`
`--size`	Instance size: `xs`, `s`, `m`, `l`, `xl`, `xxl`, `xxxl`
`--arch`	Architecture: `x64` or `arm`
`--region`	AWS region (EC2 only)
`--profile`	AWS CLI profile (EC2 only)
`--image`	Docker image name (Docker only)
`--devcontainer`	Use devcontainer configuration (Docker only)
`--volume`	Docker volume mount (Docker only)

ark compute provision <name>

Provision the infrastructure for a compute resource (e.g. launch an EC2 instance).

$ ark compute provision my-ec2

ark compute start <name> / ark compute stop <name>

Start or stop a compute resource without destroying it.

$ ark compute start my-ec2
$ ark compute stop my-ec2

ark compute destroy <name>

Destroy the provisioned infrastructure (e.g. terminate the EC2 instance). The compute record remains in the database.

$ ark compute destroy my-ec2

ark compute delete <name>

Delete the compute record from the database. Destroy first if still provisioned.

$ ark compute delete my-ec2

ark compute list

List all compute resources with their provider, status, and size.

$ ark compute list

ark compute status <name>

Show detailed status and live metrics for a compute resource.

$ ark compute status my-ec2

ark compute ssh <name>

Open an SSH session into a running compute resource.

$ ark compute ssh my-ec2

ark compute sync <name>

Sync the environment between local and remote compute.

$ ark compute sync my-ec2 --direction push
$ ark compute sync my-ec2 --direction pull

Option	Description
`--direction`	`push` (local → remote) or `pull` (remote → local)

ark compute metrics <name>

Show CPU, memory, disk, and network metrics for a running compute resource.

$ ark compute metrics my-ec2

ark compute update <name>

Update the configuration of a compute resource.

$ ark compute update my-ec2 --size l
$ ark compute update my-ec2 --idle-minutes 30 --set tag=production

Option	Description
`--size`	New instance size
`--arch`	New architecture
`--region`	New AWS region
`--profile`	New AWS CLI profile
`--ingress`	Ingress rule (CIDR or security group)
`--idle-minutes`	Auto-stop after N minutes of inactivity
`--set key=value`	Set an arbitrary metadata key

ark pr

Work with sessions bound to pull requests.

ark pr list

List all sessions that have an associated pull request.

$ ark pr list

ark pr status <pr-url>

Show the session bound to a given pull request URL.

$ ark pr status https://github.com/org/repo/pull/42

ark schedule

Create and manage recurring sessions driven by a cron expression.

ark schedule add

Create a new recurring session schedule.

$ ark schedule add --cron "0 9 * * 1-5" --repo . --summary "Daily standup sync" --flow bare

Option	Description
`--cron`	Required. Cron expression (e.g. `"0 9 * * 1-5"`)
`-f, --flow`	Flow name
`-r, --repo`	Repository path
`-s, --summary`	Task summary for each spawned session
`-c, --compute`	Compute target name
`-g, --group`	Group for spawned sessions

ark schedule list

List all schedules with their cron expression and enabled state.

$ ark schedule list

ark schedule delete <id>

Delete a schedule.

$ ark schedule delete sch-1a2b

ark schedule enable <id> / ark schedule disable <id>

Enable or disable a schedule without deleting it.

$ ark schedule enable sch-1a2b
$ ark schedule disable sch-1a2b

ark auth

Set up Claude authentication for remote compute. Runs claude setup-token to create a persistent OAuth token, then saves it to ~/.ark/claude-oauth-token. The TUI and dispatch read this token automatically — no environment variables needed.

$ ark auth
$ ark auth --host my-ec2

Option	Description
`--host <name>`	Run `setup-token` on a specific remote compute host instead of locally

Note: Run ark auth once before dispatching sessions to EC2 compute. The token persists across reboots and is synced to remote hosts during provisioning.

ark channel

Run the MCP channel server. This is an internal command used by remote agents to communicate with the conductor via stdio. It is normally launched automatically by the remote launcher — you do not need to run it manually.

$ ark channel

ark claude

Inspect Claude Code sessions stored on disk at ~/.claude/projects/.

ark claude list

List Claude Code sessions discovered on disk.

$ ark claude list
$ ark claude list --project my-repo --limit 50

Option	Description
`-p, --project`	Filter by project name
`-l, --limit`	Maximum number of results to show

ark conductor

Start the conductor HTTP server. The TUI runs the conductor automatically; use this command when running the conductor as a standalone process.

$ ark conductor
$ ark conductor --port 19200

Option	Default	Description
`-p, --port`	`19100`	Port for the conductor HTTP server

Note: The conductor port is used by agent hooks and MCP channels to report status back to Ark. All sessions on the same machine must point to the same conductor port.