Command Reference

Complete reference for all Arial CLI commands.

Overview

Arial has 5 commands:

`arial init`

Initialize Arial in a git repository.

arial init [options]

Options

Examples

# Initialize in current directory
arial init

# Re-initialize (if already initialized)
arial init --force

What it does

• Verifies you're in a git repository
• Creates .arial/ directory for state management
• Outputs next steps

Output

Initialized Arial

Next steps:
  1. Create a specs directory with markdown files describing your work
     mkdir specs
     echo "# Build auth system" > specs/auth.md

  2. Plan the workstreams:
     arial plan --specs ./specs

  3. Run all workstreams:
     arial run

`arial plan`

Create workstreams from a directory of spec files.

arial plan --specs <path> [options]

Options

Examples

# Create workstreams from specs directory
arial plan --specs ./specs

# Skip confirmation prompts
arial plan --specs ./specs -y

# Use specs directly without AI suggestions
arial plan --specs ./specs --skip-suggestions

What it does

1. Reads all .md files from the specs directory
2. Optionally analyzes specs with AI (can skip with --skip-suggestions)
3. Shows workstream preview
4. Asks for confirmation (skip with -y)
5. Creates workstreams and saves state

Specs Directory

Each markdown file becomes a workstream. The file structure:

specs/
├── auth.md      → workstream "auth"
├── api.md       → workstream "api"
└── tests.md     → workstream "tests"

Output

Loading specs...
Found 2 spec file(s)

Workstreams (2):

  auth
    Add User Authentication
    Implement JWT-based authentication for the API.

  api
    Build User API
    Create REST endpoints for user management.

Create these workstreams? [y/N] y

Created 2 workstream(s)

Next steps:
  Run all workstreams:
    arial run

  Or view status:
    arial status

`arial run`

Execute all workstreams with a TUI dashboard.

arial run [options]

Options

Examples

# Run with TUI dashboard
arial run

# Run without TUI (console output)
arial run --no-tui

# See all agent output
arial run --verbose

What it does

1. Loads saved workstreams from state
2. Creates git worktrees for each pending workstream
3. Runs Claude Code agents in parallel
4. Shows live progress in TUI (or console with --no-tui)
5. Auto-merges completed branches to base branch
6. Cleans up worktrees

Interrupting

Press Ctrl+C to pause execution:

• First press: gracefully stops agents
• Second press: force exits

State is saved, so you can resume with arial run.

Resuming

If you interrupt a run or it crashes:

• Run arial run again to resume
• Paused workstreams continue where they left off

Output (TUI mode)

Arial Status
────────────────────────────────────

Base branch: main
Status: running

Progress: 1 done, 1 running (2 total)

Workstreams:

✓ auth - Add User Authentication
  Implement JWT-based authentication for the API.
  Completed in 2m 15s

● api - Build User API
  Create REST endpoints for user management.
  Running for 1m 30s

`arial status`

Show current run status.

arial status [options]

Options

Examples

# View status
arial status

# Get JSON output
arial status --json

Output

Arial Status
────────────────────────────────────

Base branch: main
Specs: ./specs
Status: running

Progress: 1 done, 1 running (2 total)

Workstreams:

✓ auth - Add User Authentication
  Implement JWT-based authentication for the API.
  Completed in 2m 15s

● api - Build User API
  Create REST endpoints for user management.
  Running for 1m 30s

────────────────────────────────────
Workstreams are running. Use `arial run` to view TUI.

JSON Output

With --json, outputs the full state object:

{
  "status": "running",
  "baseBranch": "main",
  "specsDir": "./specs",
  "workstreams": [
    {
      "id": "auth",
      "title": "Add User Authentication",
      "status": "done",
      "startedAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:02:15Z"
    },
    {
      "id": "api",
      "title": "Build User API",
      "status": "running",
      "startedAt": "2024-01-15T10:00:00Z"
    }
  ]
}

`arial cleanup`

Remove stale worktrees and branches from aborted runs.

arial cleanup [options]

Options

Examples

# Clean up stale resources (with confirmation)
arial cleanup

# See what would be cleaned
arial cleanup --dry-run

# Clean without confirmation
arial cleanup --force

What it does

1. Finds git worktrees registered under .arial/worktrees/ that no longer exist on disk
2. Finds arial/* branches not associated with an active run
3. Shows what will be removed
4. Asks for confirmation (unless --force)
5. Runs git worktree prune and deletes orphan branches

When to use

If arial run was interrupted (Ctrl+C, crash, terminal closed) and you see this error:

fatal: '/path/.arial/worktrees/prd' is a missing but already registered worktree;
use 'add -f' to override, or 'prune' or 'remove' to clear

Run arial cleanup to fix it.

Auto-cleanup

arial run automatically cleans up stale resources before starting. The arial cleanup command is useful for manual cleanup or to see what would be cleaned with --dry-run.

Output

Found stale resources from aborted runs:

Worktrees:
  .arial/worktrees/prd (stale)
  .arial/worktrees/auth (stale)

Branches:
  arial/prd-05818ed8
  arial/auth-a1b2c3d4

Remove these resources? [y/N] y

Cleaned up 2 worktrees and 2 branches.

Environment Variables

Examples

# Set API key (required)
export ANTHROPIC_API_KEY=sk-ant-...

# Enable verbose planning output
export VERBOSE=1
arial plan --specs ./specs

# Enable Axiom logging
export AXIOM_TOKEN=xaat-...
export AXIOM_DATASET=arial
arial run

Global Options

These work with all commands:

Quick Reference

# Setup
arial init                              # Initialize
arial init --force                      # Re-initialize

# Plan
arial plan --specs ./specs              # Create workstreams
arial plan --specs ./specs -y           # Skip confirmation
arial plan --specs ./specs --skip-suggestions  # No AI analysis

# Run
arial run                               # Run with TUI
arial run --no-tui                      # Console output
arial run --verbose                     # All agent output

# Status
arial status                            # View status
arial status --json                     # JSON output

# Cleanup
arial cleanup                           # Clean stale resources
arial cleanup --dry-run                 # Preview cleanup
arial cleanup --force                   # Skip confirmation