faf-cli
_{CONTEXT, versioned.}

project/
├── package.json     ← npm reads this
├── project.faf      ← AI reads this
├── README.md        ← humans read this
└── src/

Every building requires a foundation. FAF is AI's foundational layer.

You have a package.json. AI needs you to add a project.faf. Done.

Git-Native. project.faf versions with your code — every clone, every fork, every checkout gets full AI context.
No setup, no drift, no re-explaining.

bunx faf auto                 # Bun — zero install, fastest path
npx faf auto                  # npm — works everywhere
pnpm dlx faf auto             # pnpm — zero install
brew install wolfe-jam/faf/faf-cli && faf auto   # Homebrew (auto-taps)

faf with no arguments shows your project's score; faf auto detects and fills.

# ANY GitHub repo — one shallow clone, no install, 2 seconds
bunx faf-cli git https://github.com/facebook/react

# Your own project
bunx faf-cli init              # Create .faf
bunx faf-cli auto              # Fill every tech slot from the repo, then score
bunx faf-cli go                # Interactive interview to gold code

Run faf with no arguments:

faf-cli dogfoods itself — project.faf is source DNA; CLAUDE.md and GEMINI.md are authored from it via faf. AGENTS.md is the BETTER ops briefing (hand-kept for agents; faf export --agents still authors AGENTS.md for other repos).

Run faf --help for the full command set and options.

Portable agent memory in the IANA-registered .fafm format. Same INTEROP as claude-fafm-sdk 1.0.

# Claude Code memory dir → soul.fafm
faf memory convert ~/.claude/projects/.../memory -o soul.fafm

faf memory ls                    # ranked facts
faf memory recall "your query"   # deterministic filter + rank
faf memory etch "a durable fact" --id my-fact
faf memory show

faf-cli reads SvelteKit 3 projects: SvelteKit, its adapter and its hosting, from vite.config and devDependencies.

npx faf-cli@latest auto     # in a SvelteKit 3 app

frontend: SvelteKit · backend: SvelteKit · hosting: Cloudflare · build: Vite 8

• SvelteKit 3 moved its config into vite.config. faf-cli reads the adapter there (and still in svelte.config.js for SvelteKit 2), and finds the kit in devDependencies, where SvelteKit apps list it.
• The build slot names Vite's major version: Vite 8.

From nothing to listed in one command: faf card init asks seven questions and writes your agent.fafa, your AI Catalog entry and your ARD entry.

The same always-33 engine, plus cards.

npx faf-cli@latest card init     # seven questions → agent.fafa → A2A card, AI Catalog, ARD

• Scripts ask nothing: every answer is a flag (--name, --domain, --url or --package, --skill, --example, --set-version).
• Help says what each command touches, with a "What touches what" footer and docs.faf.one/side-effects.

One engine, one number: faf-cli v8 scores with the always-33 kernel — the same score faf-kernel, faf-rust-sdk and rust-faf-mcp give.

• The always-33 engine. Every .faf is scored against all 33 Mk4 slots by one Rust kernel (faf-scoring-kernel 3.0.0, WASM). Verified identical to the reference always-33 scorer on the project.faf of all 80 FAF repos.
• Your 21 slots, and the 12 enterprise slots in view. faf-cli fills the 21 base slots. The 12 enterprise slots — infra, app, ops — are marked slotignored unless your app-type uses them, and faf score shows all 33.
• Upgrading from 7.x: a .faf without the 12 enterprise markers now scores against 33, so its number can drop (21 filled = 64%). Run faf auto — it writes the markers and your score returns.

✪ TROPHY 100% 21/21 slots — project.faf
  ● project.name
  …
  ● stack.cicd
  — stack.monorepo_tool: slotignored
  …
  — monorepo.remote_cache: slotignored

Recent sprint

• ✪ 8.1.1 SvelteKit 3 read in full — kit, adapter, Vite 8
• ✪ 8.1.0 The Always33+ Edition — from nothing to listed in one command
• ✪ 8.0.1 pnpm installs work — faf-scoring-kernel from npm
• ✪ 8.0.0 The Always33 Edition — one engine, one number
• 🧱 7.16.2 faf compile emits FAFb wire v2 — same bytes as the faf-fafb golden
• 🧭 7.16.1 faf back in step with faf-cli
• 🧭 7.16.0 The Discoverable Edition
• 🎴 7.15.0 The Pack Edition
• 🛂 7.14.0 The Passport Edition
• 🛡️ 7.13.1 security: detection reads stay inside the project
• 🤝 7.13.0 The Co-Author Edition
• 🧩 7.12.0 The Open Renderers Edition
• 🖥️ 7.11.0 The VS Code Edition
• 📚 7.10.0 The Full-Facts Edition
• 🌱 7.9.0 The Git-Flow Edition
• 🎬 7.8.0 The Projector Edition
• 🐦 7.7.0 The Swift Edition
• 💎 7.6.0 The Ruby Edition
• ☕ 7.5.1 The JVM Edition

Your own rules for the AI — "use full words in identifiers," "use bun, not npm" — go in project.faf under ai_instructions.warnings. They land at the top of every AGENTS.md faf writes, verbatim and non-destructive.

→ How to add custom rules · docs.faf.one

✪ Trophy 100% — all or nothing. From v6.6.0 onward, faf-cli recommends only Trophy. 100% on the FCL is what makes the layers above (MD instructions, Agents, AI tooling) work — sub-Trophy leaves gaps that AI guesses on. Sub-Trophy tiers (including Bronze 85) remain on the ladder as honest interim states — they are not deleted; we just no longer aim for 85 as the goal.

Always-33. The score is filled ÷ active across all 33 Mk4 slots. Your app-type decides which slots are active; the rest are slotignored and stay visible. Same file, same engine, same number — see docs/SCORING.md.

One score, three glyphs: ✪ work (CLI · docs · receipts) · 🏆 social (X · blogs) · Trophy Mark PNG (brand). Source of truth: src/core/tiers.ts.

sync:      .faf  ──── 8ms ───→  CLAUDE.md   (pull: Trophy-gated backfill)
tri-sync:  .faf  ──── 8ms ───→  CLAUDE.md + Claude Code's MEMORY.md   (Pro: faf's block only; Claude's notes kept)

The full manual lives at docs.faf.one — facts for devs, faf-cli first. One-page overview: faf-cli.vercel.app.

• Getting started — install · run · use
• Cards — one .fafa → A2A · Server Card · registry · AI Catalog · ARD
• Custom rules — pin instructions your AI must follow

For a specific agent: Grok, xAI & Cursor 👀 · Claude Code 👀 · Bun 👀

Pivotal releases — full history in CHANGELOG.md:

• v8.0 — Always33 — one engine, one number: the same score everywhere.
• v7.1 — AGENTS.md — faf export --agents authors a complete, non-destructive AGENTS.md.
• v7.0 — GIT — context goes git-native: faf diff / log / hooks.
• v6.16 — Know Your Stack — every emitted file labels your stack identically.
• v6.15 — Copilot — faf export --copilot writes the file GitHub Copilot reads.
• v6.14 — Loop — faf loop drives any repo to ✪ 100% or the honest human wall.
• v6.7 — HTML — faf show renders a .faf to a browsable page. (FAF defines. AGENTS.md instructs. AI codes. HTML shows.)
• v6.6 — Trophy — 100% or nothing.
• v6.0 — Bun — ground-up rewrite; single portable binary, four platforms.

Bun's single-file compiler produces standalone binaries — no runtime needed.

bun run compile                # Current platform
bun run compile:all            # darwin-arm64, darwin-x64, linux-x64, windows-x64

Ship faf as a single binary for CI/CD, Docker, or air-gapped environments.

src/
├── cli.ts              ← Entry point (Commander registrations)
├── commands/           ← one file per faf subcommand
├── core/               ← Types, slots (Mk4), tiers, scorer, schema
├── detect/             ← Framework detection, stack scanner
├── interop/            ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md
├── ui/                 ← Colors (#00D4D4), display
└── wasm/               ← faf-scoring-kernel wrapper (Rust → WASM)

Toolchain: Bun (test, build, compile) · TypeScript (strict) · WASM (scoring kernel)

Robust. Reliable. Next-level WJTTC tested. — The Foundation Edition.

bun test                       # extensive WJTTC + e2e suite

• WJTTC Build Resilience — regression classes locked.
• WJTTC Kernel Stress — WASM kernel boundary tests.
• e2e lifecycle — commands in sequence.

Test reports in reports/.

• GitHub Discussions — Questions, ideas, community
• Email: team@faf.one

If faf-cli has been useful, consider starring the repo — it helps others find it.

If you use faf-cli or the .faf / .fafm / .fafa formats in research or production, please cite the format papers:

Wolfe, J. (2025). Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory. Zenodo. https://doi.org/10.5281/zenodo.20348942

Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641

@article{wolfe2025faf,
  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
  author    = {Wolfe, James},
  year      = {2025},
  month     = {nov},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18251362},
  url       = {https://doi.org/10.5281/zenodo.18251362}
}

@article{wolfe2026fafm,
  title     = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {may},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20348942},
  url       = {https://doi.org/10.5281/zenodo.20348942}
}

@article{wolfe2026fafa,
  title     = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {aug},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21951641},
  url       = {https://doi.org/10.5281/zenodo.21951641}
}

MIT — Free and open source

IANA-registered: application/vnd.faf+yaml (Context Layer) · application/vnd.fafm+yaml (Memory Layer) · application/vnd.fafa+yaml (Agent Layer)

format | driven 🏎️⚡️ wolfejam.dev · faf.one/cli