nself audit

Verify that the CLI wiki, command reference, and SPORT inventory are in sync with the live binary — and surface every stale page, missing flag, or undocumented subcommand before they reach users.

Quick start

# Run the full documentation audit
nself audit docs

# Audit and write a JSON report for CI
nself audit docs --json --output audit-report.json

Synopsis

nself audit <SUBCOMMAND> [FLAGS]

Description

nself audit cross-references the live CLI binary against its documentation sources — the wiki pages in cli/.wiki/, the SPORT inventory files, and the web docs at docs.nself.org. It produces a structured diff of:

• Commands present in the binary but missing from the wiki
• Wiki pages that document commands no longer in the binary
• Flags documented in the wiki that the binary does not expose
• Flags in the binary that the wiki has never documented
• Exit code mismatches between wiki and binary behavior
• Env-var references in wiki pages that are not in the canonical env-var inventory

The audit is designed to run in CI as a quarterly gate (the doc-sync.yml workflow triggers it on a cron). It exits 0 only if zero discrepancies are found. When used with --fail-on-drift it blocks the PR merge until documentation is brought back to parity.

nself audit docs does not modify any files. It is a pure read-and-compare operation — safe to run at any time.

Subcommands

nself audit docs

Run the full documentation audit. Inspects the CLI binary via nself --help introspection, walks the wiki page tree, and produces a discrepancy report.

nself audit docs
# COMMAND       STATUS      DETAILS
# account       ok          wiki current, all flags documented
# backup        drift       wiki missing --stream flag (added v1.1.0)
# dlq           missing     no wiki page found
# generate      ok          wiki current

nself audit docs --json
nself audit docs --json --output audit-report.json
nself audit docs --fail-on-drift

Report format

Each finding has a severity level:

• critical — command exists in binary but has no wiki page at all
• warning — wiki page exists but is missing flags, env vars, or exit codes added since the page was last updated
• info — minor discrepancies (wording, example drift, deprecated examples still present)

{
  "summary": {
    "total_commands": 84,
    "ok": 66,
    "drift": 12,
    "missing": 6
  },
  "findings": [
    {
      "command": "backup",
      "severity": "warning",
      "type": "missing_flag",
      "detail": "--stream flag present in binary (v1.1.0) but not in wiki page"
    },
    {
      "command": "dlq",
      "severity": "critical",
      "type": "missing_page",
      "detail": "no wiki page found for nself dlq"
    }
  ]
}

Examples

Quarterly CI audit gate

# .github/workflows/doc-sync.yml (quarterly cron)
nself audit docs --fail-on-drift --json --output /tmp/audit.json
# Exits 1 if any drift found — blocks release

Pre-release check (critical only)

nself audit docs --severity critical --fail-on-drift
# Only blocks on completely undocumented commands

Generate a report for triage

nself audit docs --json --output audit-$(date +%Y-%m-%d).json
# Pipe to jq for filtering
nself audit docs --json | jq '.findings[] | select(.severity == "warning")'

Audit a custom wiki directory

nself audit docs --wiki-dir ./docs/commands --sport-dir ./sport

Environment variables

• NSELF_WIKI_DIR — default wiki directory path (overrides --wiki-dir)
• NSELF_SPORT_DIR — default SPORT inventory path (overrides --sport-dir)

Exit codes

• 0 — audit complete, no drift found (or --fail-on-drift not set)
• 1 — drift detected and --fail-on-drift is set
• 2 — invalid arguments or wiki/sport directory not found

Related

• nself version — CLI version and build info
• nself doctor — system health and config diagnostics
• nself api — GraphQL API version and deprecation scan