AFD(1) — AI Foundry Desk command-line manual

NAME

afd — operate AI Foundry Desk

afd inspects and manages the AFD-owned workstation surface. It keeps agent credentials, private conversations, project content, and proprietary plugins outside the shared layer.

INSTALL

Install the npm preview for quick evaluation.

npm install --global ai-foundry-desk@0.6.3-rc.1
afd --version

The npm package is a release candidate; pin the exact version shown. The stable v0.6.2 release remains available through the checksummed GitHub bootstrap. Node.js 24 or newer is required.

SYNOPSIS

afd <command> [options]
afd tui
afd help
afd --version

Human-readable output is the default. Stable --json output exists only where documented.

COMMAND FAMILIES

Interactive

Terminal workspace

afd tui opens searchable, guided access to all 74 actions through the same application services as the CLI.

Read

Inspect

init, provenance, catalog, doctor, verify, status, review, pending

Preview / apply

Foundations

layer1, layer2, fix layer1, fix sandbox. Choose exactly one of --dry-run or --apply.

Review / write

Skills and profiles

sync, adopt, import, promote, reject, recover, hermes update.

Token-bound

Layer 3 recipes

recipes, show, plan, apply, verify, rollback, extract.

Local operation

Observability

Preview / apply

Maintenance

backup status|maintain and migrate.

INTERACTIVE TERMINAL WORKSPACE

Discover and run every AFD action without memorizing syntax.

afd tui

Search capabilities, edit guided inputs without shell quoting, review structured results, and move between responsive layouts using the keyboard or mouse. Monochrome, high-contrast, no-color, reduced-motion, mouse-free, and ASCII modes are supported.

Same safety contract: read-only actions can run directly. Writes show their scope and retain explicit confirmation, drift checks, receipts, and rollback protections. The TUI requires an interactive terminal; scripts and automation should keep using the CLI.

SCOPED MCP CONFIGURATION

Synchronize selected servers without copying secrets.

afd mcp status --scope effective --project C:/work/project
afd mcp sync --scope project --project C:/work/project --agents codex,claude-code --dry-run
afd mcp sync --scope project --project C:/work/project --agents codex,claude-code --confirm <plan-token>

Introduced in v0.5, this workflow supports status, verify, discover, sync, adopt, enable, disable, and move. Mutations revalidate a redacted, hash-bound plan and restore earlier writes if a compound update fails.

Capability boundary: adapters are verified per agent and scope. Default all-agent plans fail closed when a selected target lacks support. Pi support remains an explicit extension opt-in.

PROJECT HARNESSES

afd harness audit C:/work/project --json
afd harness plan C:/work/project --agents auto --json
afd harness stage C:/work/project --output C:/temp/stage
afd harness test C:/work/project --live --evidence C:/temp/evidence.json
afd harness apply C:/work/project --evidence C:/temp/evidence.json --confirm <plan-token>

audit is read-only. Staging and evidence stay outside the repository. Apply requires matching live evidence; verify and rollback use a receipt and refuse drift.

EXIT STATUS

0Command completed and checks passed.

2Drift, blockers, failed verification, or missing evidence were found.

1Invalid usage or operational error.

Exit code 2 is an actionable result, not a parsing failure.

SAFETY CONTRACT

Inspect before mutation. Prefer status, doctor, audit, verify, and dry-run forms first.
Bind consent to content. Recipe, MCP, and harness tokens become invalid when the plan changes.
Preserve unmanaged state. Drift remains visible; unrelated entries are not normalized.
Run as the intended user. Windows repair commands belong in that user’s regular PowerShell session, not an agent sandbox.