CLI Reference

Two entry points: aoc (the Go binary — scaffolding, daemon, spawning, everything mechanical) and pinard (the launcher shell script — starts the conductor tiers and workers).

L · Launcher
pinard · --maitre · --worker E · Estate setup
init · add vigne · config R · Runtime
daemon · spawn · maitre O · Observe
status · dashboard · track-mr X · Remote & funding
uncork · webterm · capsule-* A · Administration
create-user · cleanup · internals

• LLauncher — enter a control tier, attach to a session, or start a worker with pinard.
• EEstate setup — create the vignoble and register repositories, schedules, and configuration.
• RRuntime — operate the daemon, agents, maîtres, and notifications.
• OObserve — inspect status, dashboards, merge requests, schedules, and browser terminals.
• XRemote & funding — bootstrap isolated hosts and manage optional Capsule Protocol commands.
• AAdministration — provision accounts, archive completed work, and support launcher internals.

pinard (launcher)

pinard                              # in a vignoble dir: start the régisseur
pinard                              # anywhere else: fzf-pick a running session and attach
pinard --maitre <parcelle>         # start/attach a parcelle maître
pinard --worker …                  # run as a worker (see Remote Workers)
pinard --restart                   # kill and restart pinard tmux sessions

The launcher resolves its runtime as bundled > nvm > PATH, so a release bundle needs no system Node.

aoc — setup

aoc init [name]

Scaffold a vignoble and start its daemon.

aoc init myproject --gitlab-host gitlab.com --gitlab-group mygroup [--path ~/vignoble-myproject]

aoc add vigne <name>

Register a repository in the current vignoble’s vignes.yaml.

aoc add vigne my-api --path ~/my-api --repo mygroup/my-api [--auto-merge]

aoc add schedule <name> / aoc schedule

Add a cron-scheduled spawn (see Scheduling).

aoc add schedule nightly --project my-api --cron "0 2 * * *" --prompt "…"

aoc config get|set <path> [value]

Read or write vignes.yaml with dot-path notation.

aoc config set vignes.my-api.auto_merge true
aoc config get models.worker.id

aoc — daemon

aoc daemon start        # start detached (self-daemonizing, PID in .state/daemon.pid)
aoc daemon status       # liveness
aoc daemon stop
aoc daemon restart

aoc daemon (no subcommand) runs the watchers in the foreground. The one-shot compat commands aoc watch-mrs, aoc watch-issues, and aoc run-schedules run a single cycle — prefer the daemon for continuous operation.

aoc — agents

aoc spawn

Launch a worker in its own git worktree + tmux session.

aoc spawn --project my-api --prompt "Fix the auth bug in login.go"
aoc spawn --project my-api --prompt "Task" --target-branch cuvee/batch-1
aoc spawn --project my-api --issue 42 --parcelle semantic-search

aoc attach <session>

Stream a vendangeur’s terminal output over NATS to your local terminal — read-only, no browser or web gateway required. Resolves the session from the pinard-agents KV by name, agentId, or runId.

aoc attach my-session             # stream by session name
aoc attach abc123def              # stream by agentId or runId
aoc attach my-session --timeout 5m  # detach after 5 minutes idle

For sessions on the local tmux host, aoc attach also starts an in-process PTY pump so output is available over NATS without a separate aoc webterm-responder process. Press Ctrl+C to detach.

For a browser-based view, see aoc webterm-link and Web Terminal.

aoc maitre spawn|attach|list

Manage per-parcelle maître windows.

aoc maitre attach --parcelle semantic-search   # spawn-if-missing, then switch to its window
aoc maitre list                                 # windows in the conductor session

aoc notify <message>

Publish a notification to the conductor over NATS.

aoc notify "Task complete, opened MR !42"

aoc — merge requests

aoc track-mr --session <s> --mr <n> --project <p>   # register an MR with the watcher
aoc untrack-mr --session <s>                          # stop watching

aoc — status & schedules

aoc status              # tracked MRs, issues, workers, schedules
aoc dashboard           # live TUI: workers, MRs, schedules, notifications
aoc list-schedules      # schedules and their last run times
aoc unschedule --name <name>

aoc — web terminal

aoc webterm-link --target <session>            # print a read-only browser link
aoc webterm-link --target <session> --auto     # same, but print nothing (exit 0) when webterm/post_links is off
aoc webterm-responder                          # run the host responder (standalone/HPC hosts)

The link is unsigned when Cognito SSO is enabled (gateway grants only SSO’d operators) or signed + expiring otherwise. --auto is intended for automated callers that want to append a link only when one exists.

See Web Terminal.

aoc uncork

Materialize a credential/config bundle for a sandboxed or HPC worker. Reads a JSON manifest from a URL or stdin and writes each listed file under $HOME.

aoc uncork                          # read manifest from stdin
aoc uncork --url <endpoint>         # fetch manifest from URL (default: $PINARD_UNCORK_URL)
aoc uncork --url <endpoint> --home /custom/home  # write files under a different base dir

The manifest is a JSON object:

{
  "files": [
    { "path": ".config/pinard/credentials.yaml", "content": "…", "mode": "0600" },
    { "path": "encoded.bin", "content": "<base64>", "encoding": "base64", "checksum": "sha256:<hex>" }
  ]
}

The command fails fast on any non-2xx response, a 410 Gone (revoked bundle), or malformed JSON. See Remote Workers — Sandboxed bootstrap for the full workflow.

aoc — capsules

Buddy Capsules fund a vendangeur’s LLM quota through Mnemosyne. See Buddy Capsules for the full workflow.

aoc capsule-keygen

Generate the ed25519 identity keypair for this Pinard host (one-time setup).

aoc capsule-keygen            # writes ~/.config/pinard/capsule_key.pem
aoc capsule-keygen --force    # rotate: overwrite existing keypair

aoc capsule-pubkey

Print the base64-encoded raw ed25519 public key to share with funders.

aoc capsule-pubkey

aoc capsule-contract

Create a Mnemosyne ContractAction and post the contract_id as a comment on a GitLab issue.

aoc capsule-contract \
  --title "Short label (≤60 chars)" \
  --description "What work is requested" \
  --repo mygroup/myproject \
  --issue 42

Authentication via device-auth flow (once); tokens cached at ~/.config/pinard/mnemosyne-tokens.json.

aoc capsule-redeem

Redeem a funded Mnemosyne contract and print a bare Claude API token to stdout. Called automatically by the worker startup path when PINARD_CAPSULE_CONTRACT is set; you normally don’t call it directly.

aoc capsule-redeem <contract_id>

aoc capsule-post-result

Render <rundir>/capsule-report.md to HTML and PATCH the contract’s result URL. Called by the babysitter at the end of a funded run.

aoc — admin & internals

aoc create-user --name alice --vignoble myproject     # NATS account/user (requires nsc)
aoc cleanup archive --project <p> --change <name>     # archive a completed openspec change

Additional internal subcommands (resolve-model, vigne-args, env-exports, ensure-proxy-provider, governance-prompt, nats-publish) exist for the launcher and daemon; you won’t normally call them directly.

aoc governance-prompt --process <name> [--host <gitlab-host>] prints the no-op bootstrap prompt used for process workers. The launcher calls it automatically when no explicit prompt is given; expose it here so custom launch scripts can stay in sync without hard-coding the text.