Audrail CLI

Local-first CLI for capturing AI-assisted engineering runs.

Install

Run directly with npx:

npx audrail init my-project

Or install globally:

npm install -g audrail
audrail init my-project

Usage

npx audrail connect --name="my-project" --base-url="http://localhost:8000" --token="<cli-token>" --workspace="engineering" --project="my-project"
npx audrail init my-project
npx audrail run:start "first captured task"
npx audrail event:add prompt "Describe the first AI-assisted task"
npx audrail event:add verification "Run the project checks" --command="npm run build" --status=completed
npx audrail run:finish completed --owner="[email protected]" --next-action="Open a PR and request review"
npx audrail status
npx audrail doctor --fix
npx audrail hooks:install codex
npx audrail hooks:status
npx audrail hooks:doctor
npx audrail sync
npx audrail pr:summary

audrail run:finish can also capture resumability fields:

audrail run:finish blocked \
  --blocker="Waiting for staging credentials" \
  --next-action="Retry the migration after credentials are available"

On finish, Audrail now generates local checkpoint and handoff artifacts under .audrail/checkpoints/ and .audrail/handoffs/. A later audrail sync includes that current state in the web app snapshot so the dashboard can show:

• the latest resume status
• the last successful verification point
• the next step for the next agent or teammate
• the owner and whether the run is safe to resume
• files and failed checks since the last verified point

Handoff And PR Summary

Use these commands when you want a compact resume brief outside the web app:

audrail status
audrail handoff:print
audrail handoff:markdown
audrail handoff:markdown --pr
audrail pr:summary

When the repo is on GitHub, audrail sync also captures branch, commit, repo slug, and compare URL so the web app can bridge directly into PR-ready handoff flow.

Doctor

Use audrail doctor to diagnose local state before syncing or resuming work.

audrail doctor
audrail doctor --json
audrail doctor --fix

audrail doctor --fix only performs safe local repairs:

• removes stale .audrail/state.lock
• removes malformed or dangling .audrail/active-run.json
• creates a missing .audrail/runs/ directory
• removes orphan temporary state files under .audrail/

It does not create a missing project config or delete run records. Use audrail init for missing project configuration.

Agent Hooks

Use hooks when you want Audrail to capture useful run history automatically while an AI agent is already working inside the repo.

audrail hooks:install codex
audrail hooks:install claude
audrail hooks:install gemini
audrail hooks:status
audrail hooks:doctor

The installer writes repo-local agent config and points each agent at the matching Audrail hook command:

• Codex: .codex/hooks.json and .codex/config.toml
• Claude Code: .claude/settings.json
• Gemini CLI: .gemini/settings.json

The audrail hook:codex, audrail hook:claude, and audrail hook:gemini commands are called by those agents through stdin JSON payloads. They are not intended as normal manual commands. Hook payloads are normalized into Audrail events such as prompt, command, verification, file_write, and note.

Codex hooks are experimental and require the codex_hooks feature flag. audrail hooks:install codex writes that flag into .codex/config.toml.

Use diagnostics when hook capture is not appearing:

audrail hooks:status
audrail hooks:status codex
audrail hooks:doctor
audrail hooks:doctor claude --json

hooks:status gives a compact installed/missing/partial view. hooks:doctor checks each required hook group, configured command, and Codex's feature flag.

One-Command Connect

If the web dashboard gives you a ready-to-run setup script, audrail connect is the command behind it.

It performs these steps in one shot inside the current repo:

• initializes .audrail/
• logs the CLI into the web app
• links the local repo to the selected workspace/project
• syncs the current local snapshot immediately

Init Bootstrap

audrail init now bootstraps the repo-local instruction files that markdown-aware agents can follow.

It always creates or updates:

• .audrail/project.json
• .audrail/AI_WORKFLOW.md
• AGENTS.md
• CLAUDE.md
• GEMINI.md

Existing files are not overwritten wholesale. audrail init manages a small Audrail section and appends or updates that block in place.

Example:

audrail init my-project
audrail init my-project --sync-mode=manual --sync-interval=10
audrail init my-project --sync-on-finish=false

Run audrail init without arguments in an interactive terminal to use the setup wizard. It asks for:

• project name
• sync mode
• default verification commands
• agent hooks to install
• whether to create or update instruction files

Non-interactive usage remains script-friendly and never prompts.

The generated workflow tells agents to:

• keep local run history under .audrail/runs/
• log concise prompt, file_write, command, and verification events
• finish runs with a terminal status
• run audrail sync on finish and at periodic checkpoints when the project is linked

What It Writes

Audrail stores local project state in .audrail/:

• .audrail/project.json for project configuration
• .audrail/AI_WORKFLOW.md for shared agent instructions
• .audrail/runs/ for local run records
• .audrail/active-run.json for the currently active run pointer

Raw run history is local-first by default.