CLI Reference

The aps CLI has two implementations in v0.4.0:

• Native binary — scaffold projects, add integrations, lint specs, resolve the next work item, and diagnose installs (init, setup, lint, next, doctor)
• Bash fallback/vendored runtime — also carries legacy/update and orchestration helpers (update, migrate, start, complete, graph, audit, upgrade)

You can ignore orchestration and edit markdown by hand — the CLI is additive.

Command index

aps init [dir]              # Create APS structure
aps lint [file|dir]         # Validate APS documents
aps next [module]           # Show next ready work item
aps doctor                  # Diagnose global binary vs vendored CLI
aps setup [component]       # Add integrations (hooks, agents, tools)

# Bash fallback/vendored runtime only in v0.4.0:
aps update [dir]            # Refresh templates and tool files
aps migrate [dir]           # Convert v1 layout to v2 (.aps/)
aps start <ID>              # Mark Ready → In Progress
aps complete <ID>           # Mark In Progress → Complete
aps graph [module]          # Dependency graph
aps audit [module]          # Audit plan state against reality
aps upgrade [--apply]       # Remove generated bloat
aps --help                  # Top-level help

Project-scoped orchestration commands in the bash fallback accept --plans <dir> when plans are not at the default plans/ location. aps lint takes the plan path as its argument, for example aps lint packages/foo/plans/.

Project config discovery

Project-scoped commands resolve their plan root automatically. aps walks up from the current directory for the nearest .aps/config.yml and uses its plans_dir.

Resolution order: explicit target/--plans where supported → APS_PLANS env var → discovered plans_dir → plans/.

Add --strict (or APS_STRICT=1) to fail on toolchain version drift:

aps lint --strict

aps lint

aps lint                          # Lint plans/
aps lint plans/modules/auth.aps.md
aps lint . --json                 # Machine-readable output

See Validation rules → for error and warning codes.

Orchestration

The orchestration commands read and rewrite .aps.md files in place. Markdown stays the single source of truth. In v0.4.0 these commands are available in the bash fallback/vendored runtime; native-only installs should hand-edit equivalent status changes.

State machine

Draft ──→ Ready ──→ In Progress ──→ Complete

Command	Transition
aps next	Read-only
aps start	Ready → In Progress (dependencies must be Complete)
aps complete	In Progress → Complete
aps graph	Read-only
aps audit	Read-only (executes Validation commands by default)

aps next

$ aps next
AUTH-003: Implement token refresh
Module: AUTH | Dependencies: AUTH-001, AUTH-002 | Status: Ready
File: plans/modules/auth.aps.md

$ aps next auth          # Scope to one module

aps start <ID> (bash fallback/vendored runtime)

$ aps start AUTH-003
Marked AUTH-003 as In Progress
Suggested branch: work/auth-003
Context package: .aps/context/AUTH-003.md

On success:

• Rewrites - **Status:** to In Progress
• Suggests a branch name (work/<id>)
• Writes a context package at .aps/context/<ID>.md

aps complete <ID> (bash fallback/vendored runtime)

$ aps complete AUTH-003 --learning "Token refresh needs retry on network errors"
Marked AUTH-003 as Complete: 2026-05-12
Learning recorded for AUTH-003

aps graph [module] (bash fallback/vendored runtime)

$ aps graph auth
AUTH-001 [Complete] Create users
  <- none
AUTH-002 [Complete] Verify credentials
  <- AUTH-001[Complete]
AUTH-003 [Ready] Add token refresh
  <- AUTH-001[Complete] AUTH-002[Complete]

aps audit [module] (bash fallback/vendored runtime)

$ aps audit
Complete-item verification:
  AUTH-001     PASS     npm test -- auth.test.ts
  AUTH-002     FAIL     npm test -- session.test.ts

Findings:
  A001  AUTH-002     overstated: Validation failed
  A003  UI-002       stale: module last reviewed 89 days ago

Findings: 2 (23 items audited)

Options: --json, --no-run (skip executing validation commands), --stale-days N.

CI safety: Use aps audit --no-run in pull-request jobs.

aps doctor

Read-only diagnostics for global binary vs vendored CLI state:

$ aps doctor
  [ok  ] global binary: aps 0.4.0 at ~/.aps/bin/aps
  [warn] cli_version: project pins 0.3.0 but this binary is 0.4.0
  [warn] vendored CLI: leftover bin/aps, lib/ — run `aps upgrade`

End-to-end loop

This full loop uses the bash fallback/vendored orchestration helpers. With a native-only v0.4.0 install, use aps next, then edit the status fields in markdown manually.

aps next
aps start AUTH-003
git switch -c work/auth-003
# ...implement, test, commit...
aps complete AUTH-003 --learning "..."
aps next

MCP server

An optional MCP server in anvil-plan-spec mcp/ exposes orchestration commands as a single aps tool over stdio.

{
  "mcpServers": {
    "aps": {
      "command": "node",
      "args": ["/path/to/anvil-plan-spec/mcp/src/index.ts"],
      "env": { "APS_PLANS": "/path/to/your/project/plans" }
    }
  }
}

CI integration

name: Lint APS Documents

on:
  push:
    paths: ['plans/**/*.aps.md', 'plans/**/*.actions.md']
  pull_request:
    paths: ['plans/**/*.aps.md', 'plans/**/*.actions.md']

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install APS CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/EddaCraft/anvil-plan-spec/main/scaffold/install \
            | bash -s -- --global
      - name: Lint APS documents
        run: aps lint plans/ --strict

---

Back to: APS Overview →