Configuration

Environment variables, state management, and configuration options for Arial.

Authentication

See the Authentication guide for setup instructions.

Arial supports two auth methods:

Local credentials - Run claude login (recommended for development)
API key - Set ANTHROPIC_API_KEY environment variable

Environment Variables

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key (optional if using local credentials)
`CLAUDE_MODEL`	Override the Claude model used
`VERBOSE`	Set to `1` to see AI suggestion output during planning
`AXIOM_TOKEN`	Axiom logging token for production observability
`AXIOM_DATASET`	Axiom dataset name (required if using Axiom)

State File

Arial stores all run state in a single JSON file:

.arial/state.json

State Structure

{
  "status": "running",
  "baseBranch": "main",
  "specsDir": "./specs",
  "workstreams": [
    {
      "id": "auth",
      "title": "Add User Authentication",
      "description": "Implement JWT-based authentication.",
      "status": "done",
      "branch": "arial/auth-abc12345",
      "startedAt": "2024-01-15T10:00:00Z",
      "completedAt": "2024-01-15T10:02:15Z"
    },
    {
      "id": "api",
      "title": "Build User API",
      "description": "Create REST endpoints.",
      "status": "running",
      "branch": "arial/api-def67890",
      "startedAt": "2024-01-15T10:00:00Z"
    }
  ]
}

Top-Level Fields

Field	Type	Description
`status`	string	Overall run status: `pending`, `running`, `done`, `failed`
`baseBranch`	string	Git branch workstreams merge into
`specsDir`	string	Path to specs directory
`workstreams`	array	List of workstream objects

Workstream Fields

Field	Type	Description
`id`	string	Unique identifier (from filename)
`title`	string	Display title (from spec H1)
`description`	string	Brief description (from spec content)
`status`	string	`pending`, `running`, `paused`, `done`, `failed`
`branch`	string	Git branch name for this workstream
`startedAt`	string	ISO timestamp when execution started
`completedAt`	string	ISO timestamp when execution completed
`error`	string	Error message if status is `failed`

Workstream Status Values

Status	Description
`pending`	Ready to run, not yet started
`running`	Agent is currently executing
`paused`	Interrupted by user (Ctrl+C)
`done`	Completed successfully
`failed`	Agent encountered an error

Directory Structure

After initialization, Arial creates:

.arial/
├── state.json              # Run state
└── worktrees/              # Git worktrees during execution
    ├── auth/               # Worktree for "auth" workstream
    └── api/                # Worktree for "api" workstream

Worktrees

During execution, each workstream gets its own git worktree:

Located at .arial/worktrees/<workstream-id>/
Contains a full copy of the working tree
Shares git history with main repo (lightweight)
Automatically cleaned up after completion

State Persistence

State is saved after each workstream status change
On interrupt (Ctrl+C), workstreams are marked as paused
Run arial run to resume from saved state

Observability

Axiom Integration

For production observability, configure Axiom:

export AXIOM_TOKEN=xaat-your-token
export AXIOM_DATASET=arial
arial run

Axiom receives structured logs for:

Run start/complete events with timing
Workstream start/complete/fail events
Merge events and conflict detection

See the Axiom Observability guide for complete setup instructions, event schemas, and example queries.

Verbose Mode

See detailed output during execution:

# During planning
export VERBOSE=1
arial plan --specs ./specs

# During execution
arial run --verbose

Git Branches

Arial creates branches for each workstream:

arial/<workstream-id>-<hash>

Example:

arial/auth-abc12345
arial/api-def67890

Branch Lifecycle

Created when workstream starts
Used during agent execution
Merged to base branch on completion
Deleted after successful merge

Stale Branches

If a run is interrupted, branches may remain. Clean up with:

arial cleanup

Troubleshooting Configuration

Authentication Issues

See Authentication troubleshooting.

State File Corrupted

If .arial/state.json is corrupted:

# Option 1: Remove and re-plan
rm .arial/state.json
arial plan --specs ./specs

# Option 2: Edit manually (advanced)
# Ensure valid JSON structure matches schema above

Stale Worktrees

fatal: '/path/.arial/worktrees/auth' is already registered

Fix:

arial cleanup