Agent Ledger CLI

import { Steps, Card, CardGrid } from ‘@astrojs/starlight/components’;

The agent ledger CLI is the write surface — how machines create and mutate issues without a TUI. It is non-interactive, JSON-first, and carries actor attribution on every mutation. Humans audit the results with prog status, prog board, or prog ui.

The contract

Every mutating command supports --json and produces a stable envelope:

{ "ok": true, "issue": { ... } }
{ "ok": true, "issues": [ ... ] }
{ "ok": false, "error": "issue not found: abc" }

Exit codes

Code	Meaning
`0`	Success
`1`	Domain error (issue not found, invalid transition)
`2`	Usage error (bad args)
`3`	Not a ProGit project (no `.project/`)

Commands

Create an issue

prog issue create --title "Fix auth race" --tag agent --actor agent:voxis --json
# → { "ok": true, "issue": { "id": "abc123", ... } }

Transition an issue

prog issue set abc123 --status in-progress --actor agent:voxis --json
# → { "ok": true, "issue": { "id": "abc123", "status": "in-progress", ... } }

Append a note

prog issue note abc123 --body "found root cause in foo.rs" --actor agent:voxis --json

List for context packing

prog issue list --status in-progress --json
prog issue get abc123 --json

Board snapshot for planning
Terminal window
```
prog board --json
```

Actor attribution

Every mutation accepts --actor agent:<name> (or --actor human:<name>). The actor is recorded in two places:

last_actor field on the issue.

.project/events.jsonl — an append-only audit log:

{"ts":"2026-08-11T18:00:00Z","actor":"agent:voxis","op":"issue.set","id":"abc123","fields":{"status":"in-progress"}}

This event log is the foundation for time-tracking plugins (deferred) and for cross-machine drift reasoning.

Non-interactive guarantees

If stdout is not a TTY or --json is set → never prompt.
prog issue * never prompts.
Agents never hang waiting for human input.