faf-cli

IANA-Registered Format for AI Context · application/vnd.faf+yaml

Universal CLI for FAF (Foundational AI-context Format) - Terminal-based tooling for creating, scoring, and improving project.faf files that provide persistent AI context

---

TL;DR

Problem: AI needs persistent project context to work at its best.

Solution: The .faf format provides that context. This CLI creates, scores, and improves .faf files from your codebase in the IANA-registered format.

How it works: Run faf init to create your .faf file. Get a score (0-100%) showing context quality. Higher scores = AI more in-tune with your project. Use faf auto and other commands to improve your score quickly.

Install:

# npm (works everywhere)
npm install -g faf-cli

# Homebrew (macOS/Linux)
brew install faf-cli

Quick start:

cd your-project
faf init        # Creates project.faf file
faf score       # Check AI-readiness (0-100%)

CLI vs MCP clarity:

• faf-cli (this): Terminal-based tool for scripts, automation, and local development
• claude-faf-mcp (npm): MCP server for Claude Desktop via protocol integration

Same .faf format, different execution layers. Same Project DNA and scoring. Same capabilities (create, score, improve). Choose based on your workflow.

Website | GitHub | Discussions

---

Project DNA Positioning

project.faf lives at the project root, between package.json and README.md

At 55% you are building your project with half a blueprint and basically flipping a coin with AI. .FAF defines, and AI becomes optimized for Context with the project.faf file.

---

Quick Start

Installation

# npm (works everywhere)
npm install -g faf-cli

# Homebrew (macOS/Linux)
brew install faf-cli

Generate Your First .faf File

# Initialize with IANA-registered format
faf init

# Output: project.faf with official media type
# Content-Type: application/vnd.faf+yaml

What just happened:

• Created project.faf file (IANA-registered format)
• Generated project DNA (architecture, dependencies, quality score)
• Ready for any AI (Claude Code, Gemini, Cursor, Codex, Warp, etc.)
• Official Internet standard format

More Commands

# Auto-detect and enhance
faf auto

# Check your AI readiness
faf score

# Discover your stack's formats
faf formats

# Sync with CLAUDE.md
faf bi-sync

That's it! Your AI now has perfect context.

---

Human Context (The 6 Ws)

Boost your score by 25-35% with human context - the information only YOU know about your project.

Auto-Extract from README

# Preview what can be extracted
faf readme

# Apply extracted content to empty slots
faf readme --apply

# Overwrite all slots (even filled ones)
faf readme --apply --force

Manual Entry

# Non-interactive (works in Claude Code)
faf human-set who "Frontend team at Acme Corp"
faf human-set what "Customer dashboard with real-time analytics"
faf human-set why "10x faster than previous solution"

# Interactive mode (terminal only)
faf human

Quality Check & Protection

# Inspect quality of human_context fields
faf check

# Output shows quality levels:
#   empty     - Not filled
#   generic   - Placeholder or too short
#   good      - Quality content
#   excellent - High-value content

# Lock good content from being overwritten
faf check --protect

# Remove all protections
faf check --unlock

Protected fields are skipped by faf readme and faf auto, preventing accidental overwrites of quality content.

---

Core Features

44 Championship Commands

• faf auto - Zero to Podium in one command
• faf init - Create project.faf from your project
• faf readme - Smart 6 Ws extraction from README.md
• faf human - Interactive human context entry
• faf human-set - Non-interactive field setting (Claude Code compatible)
• faf check - Quality inspection + field protection
• faf enhance - Real AI analysis and improvements
• faf score - AI-readiness scoring (0-100%)
• faf formats - 153 formats across 17-level pyramid
• faf bi-sync - Bidirectional .faf ↔ CLAUDE.md (8ms!)
• faf dna - Evolution journey tracking

Run faf --help for complete command reference

IANA-Registered Standard

• Official MIME type: application/vnd.faf+yaml
• Recognized at Internet scale (same as PDF, JSON, XML)
• Proper HTTP Content-Type headers
• Browser and email client support
• Universal format for AI context

Championship Performance

• <50ms all commands target
• 18ms average execution
• 8ms bi-sync achieved
• 0ms operations possible (unmeasurable speed!)
• F1-grade engineering

Universal AI Support

Works with Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, Warp, Copilot, Windsurf, and all AI coding assistants.

PLUS: AI-Automation platforms (n8n, OpenAI Builder, Google Opal, Make.com)

---

Documentation

• CHANGELOG - Version history and release notes
• FAQ - Common questions
• Commands Reference - All 41 commands
• Website - Complete guide and documentation
• Discord Community - Join the discussion

---

Why FAF CLI?

"README for the AI era" — Gemini CLI

Persistent Context - Your project's DNA lives in project.faf, readable by any AI or human

Universal Format - IANA-registered standard works across Claude, Gemini, Codex, any LLM

Terminal-Native - Built for scripts, automation, and developer workflows

Championship Engineering - F1-inspired performance with strict TypeScript, zero runtime errors

---

Ecosystem

• FAF Format Spec - Official IANA specification
• claude-faf-mcp - MCP server for Claude Desktop
• Chrome Extension - Browser integration
• faf.one - Official website and documentation

---

Development

# Clone
git clone https://github.com/Wolfe-Jam/faf-cli.git
cd faf-cli

# Install & Build
npm install
npm run build

# Test
npm test

# Link locally
npm link

---

License

MIT License - Free and open source

---

Built with F1-inspired engineering principles

"It's so logical if it didn't exist, AI would have built it itself" — Claude