faf-cli
Version:
π½ TURBO-CAT: The Rapid Catalytic Converter β’ Project DNA β¨ for ANY AI β’ Fully Integrated with React, Next.js, Svelte, TypeScript, Vite & n8n β’ FREE FOREVER β’ 10,000+ developers β’ Championship Edition
775 lines (534 loc) β’ 23.8 kB
Markdown
# faf-cli v3.0.3 - Championship Edition π
with Turbo Cat π½
<div align="center">
<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/icons/orange-smiley.svg" alt="FAF Logo" width="64" />
## **FREE FOR ALL DEVS** π β’ **Growing Fast** π β’ **TURBO-CAT Powered** π½
**Project DNA β¨ for ANY AI** β’ **Instant Context** β’ **Zero Faffβ’**
[](https://www.npmjs.com/package/faf-cli)
[](https://www.npmjs.com/package/faf-cli)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
**[Website](https://faf.one)** β’ **[GitHub](https://github.com/Wolfe-Jam/faf-cli)** β’ **[Community](https://github.com/Wolfe-Jam/faf-cli/discussions)** β’ **[npm](https://www.npmjs.com/package/faf-cli)**
</div>
**AI-Context: Avg. 0-55% kills projects π .faf 85-99% AI totally gets it β¨**
## π Wanna GO Now>>
```bash
# Install via npm (works everywhere)
npm install -g faf-cli
# Or via Homebrew (macOS/Linux)
brew install faf-cli
```
**One line. Zero config. Championship context.** π
## π What's New in v3.0.0
### The Championship Release
**The biggest release yet:**
- π **FREE FOREVER .faf Core-Engine** - 41 championship commands, always free, open source, MIT License
- π¨ **TURBO Model Introduced** - Like VS Code + Copilot, Spotify Free + Premium, Zoom Basic + Pro
- π½ **TURBO-CATβ’ Format Discovery** - Introduced in v2.0.0, now purring at full power in v3.0.0 - 153 validated formats organized in a perfect pyramid
- 𧬠**Birth DNA Lifecycle** - Track your project's evolution from birth to championship
- π **7-Tier Championship Scoring** - π π₯ π₯ π₯ π’ π‘ π΄ π€ - From Lonely Heart to Podium Champion
- βοΈ **AI | HUMAN Balance** - 50|50 system = Optimal Context for championship performance
- π **Context-Mirroring w/Bi-Sync** - Bidirectional .faf β CLAUDE.md synchronization
- β‘ **Championship Speed** - 8ms bi-sync, <50ms all commands, 18ms avg, 0ms operations achieved
- π **WJTTC GOLD Certified** - 1,000+ comprehensive tests, unique test suite
- π€ **BIG-3 AI Validation** - Verified by Google Gemini, Anthropic Claude, OpenAI Codex
- π **Universal AI Support** - Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, Warp, Copilot, Windsurf, ALL AI coding assistants
- π€ **AI-Automation Ready** - Reads n8n workflows, OpenAI Builder schemas, Google Opal, Make.com - Project DNA for automation platforms
## π€ What The AIs Said (During Verified Testing)
### The BIG-3 Validation
**Google Gemini CLI**
> "README evolution for AI era"
β *9.5/10 Rating during verified testing*
**Claude Code (Anthropic)**
> "Should become the standard"
β *9.5/10 Rating during verified testing*
**OpenAI Codex CLI**
> "Every project should have one"
β *9/10 Rating during verified testing*
### The Context Problem, Solved
**β .faf Inventor**
> "package.json wasn't built for this, .faf was"
**β Claude Code (Anthropic)**
> "package.json gives me a list of dependencies,
> .faf shows me how to use them"
**β Claude**
> "It's so logical if it didn't exist,
> AI would have built it itself"
**100% verified. Real AI responses. Not marketing copy.**
## π½ TURBO-CATβ’ - Full Official Launch
**The Rapid Catalytic Converter - Now Purring at Full Power**
Introduced in v2.0.0, TURBO-CAT reaches full championship form in v3.0.0. This format discovery engine knows 153 validated formats organized in a perfect pyramid structure. From `.faf` at the apex to infrastructure configs at the base, it rapidly converts raw project formats into AI-ready intelligence at championship speed.
Like a catalytic converter in an exhaust system, TURBO-CAT transforms digital waste into clean, usable output.
Now fully unleashed and purring. π½π¨
```bash
faf formats
```
```
π½ TURBO-CATβ’ v3.0.0 - Now Purring at Full Power
(Introduced v2.0.0, Perfected v3.0.0)
βββββββββββββββββββββββββββββββββββ
β‘οΈ Scanning project...
β
Found 10 formats in 68ms!
π Discovered Formats (A-Z):
β
package.json
β
tsconfig.json
β
Dockerfile
β
.github/workflows
β
jest.config.js
... and 5 more
π‘ Stack Signature: typescript
π Intelligence Score: 225
ββββββββββββββββββββββββββββββββββββββββ
π½ TURBO-CATβ’: "Detection that'll make your stack PURRR!"
ββββββββββββββββββββββββββββββββββββββββ
```
**The Pyramid:** 153 formats across 17 levels. Each level unlocks new intelligence. **TURBO** reveals what TURBO-CAT really knows... π€«
## π¨ FAF TURBO - World-Class Automation Intelligence
### Like **VS Code + Copilot** β’ Same model that works!
<div align="center">
<table>
<tr>
<td width="50%" valign="top">
### **FAF v3.0.3 (FREE FOR ALL DEVS)** π
β
**41 Championship Commands**
- Project initialization & auto-detection
- TURBO-CAT format discovery (153 formats)
- Birth DNA lifecycle tracking
- AI readiness scoring (0-100%)
- Context-mirroring (bi-sync)
- Health checks & diagnostics
β
**Performance**
- <50ms command execution
- 8ms bi-sync (championship speed)
- F1-inspired engineering
- 0ms operations achieved
β
**Universal Compatibility**
- Works with Claude, Codex CLI, Gemini CLI, Cursor
- Mac, Linux, Windows support
- Open source, MIT licensed
- Growing developer community
```bash
npm install -g faf-cli
```
</td>
<td width="50%" valign="top">
### **FAF v3.0.3 TURBO** π¨
β
**Everything in FREE, Plus:**
𧬠**Deep Format Intelligence**
- Pyramid-level insights (17 levels deep)
- Cross-format relationship analysis
- Stack health diagnostics
- Migration path recommendations
π€ **Universal Automation Intelligence**
- **n8n workflow parsing** - RAG, ETL, Multi-Agent patterns
- **OpenAI Assistants** - GPT Actions & function schemas
- **Google Opal** - Visual mini-app workflows
- **Make.com scenarios** - Module & integration analysis
- **FOUNDATIONAL FIRST** - ONE pattern for ALL platforms
π **Premium Features**
- Priority support & service plans
- Advanced TURBO-CAT capabilities
- Enterprise integrations
- Early access to new features
```bash
Learn more: faf.one/turbo
```
</td>
</tr>
</table>
</div>
**TURBO**: Where automation platforms (n8n, Make, Opal) get championship AI context.
**Foundational first, universal by default.**
## π Quick Start
```bash
# Install
npm install -g faf-cli
# Initialize in any project
cd your-project
faf init
# 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. π
## π The Meta-Proof: Even Claude Forgot .FAF
**The AI that built FAF scored it at 12% without `.faf`.**
We created this tool together across thousands of conversations. Yet without project DNA, even Claude couldn't recognize its own work. That's the problem FAF solves.
### Before `.faf` - Birth: 12%
<div align="center">
<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/birth-dna-12-percent.png" alt="FAF CLI birth score: 12% context" width="700" />
</div>
**Context Score: 12%** β Even the AI that built it couldn't recognize it
### The Transformation - 344ms Later
<div align="center">
<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/faf-init-demo.gif" alt="Running faf init - 344ms" width="700" />
</div>
**`faf init`** β One command. Zero configuration. Project DNA created.
### After `.faf` - Current: 89%
<div align="center">
<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/growth-to-89-percent.png" alt="FAF CLI after .faf: 89% context score" width="700" />
</div>
**Context Score: 89%** β Instant comprehension. Persistent memory.
**+77% improvement in 344ms.** That's what project DNA does for ANY AI, ANY project.
## π― What is FAF?
**`.faf` = Project DNA β¨ for AI**
Universal, shareable AI context that works with **Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor** - regardless of your stack, size, or setup.
### Why Context Quality Matters
**At 99% context quality**, AI knows exactly what you're building and helps at optimal levelsβtrusted decisions, accurate suggestions, championship performance.
**At 55% context quality**, you're flipping a coin on every decision. It's like handing a builder only half a blueprint and discussing it in a totally foreign language.
FAF's **Professional 0β99% Podium Scoring System** makes context collection measurable, fun, and championship-grade. Track your project's evolution from π€ Heart (0%) to π Trophy (100%).
### The REAL Problem: Project Health
**This isn't about saving 20 minutes at setup.**
Running projects on LOW AI context leads to:
- β **Project death** (worst case)
- β **Delays, costs, stress, heartache, disappointment**
- β **Wasted time, resources, and money**
- β **Poor outcomes for stakeholders and users**
- β **Burnout from constant re-explaining**
**It's not a one-time config. It's a relationship.**
A healthy Human + AI collaboration requires **high-quality, persistent context**. Without it, every interaction is a gamble. Every decision is questionable. Every suggestion needs verification.
**Ignoring poor context on your project is like not brushing your child's teeth.**
You're gonna end up with a **CAVITY**.
### The Solution: Project DNA
- β
**Championship context** (85-99% quality scores)
- β
**Persistent intelligence** - AI remembers your project perfectly
- β
**Seamless collaboration** - Human + AI working together optimally
- β
**Project health monitoring** - Track context quality over time
- β
**Works with every AI** - Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, all of them
- β
**Team alignment** - Everyone (human AND AI) on the same page
## π οΈ All 41 Commands
### ποΈ Power Commands
```bash
faf auto # ONE COMMAND TO RULE THEM ALL - Zero to Championship
faf init # Create .faf from your project
faf enhance # Real AI analysis & improvements
faf analyze # Claude-first intelligence
```
### π½ TURBO-CAT Commands
```bash
faf formats # 153 formats across 17-level pyramid
faf stacks # Technology stack signatures
faf vibe # Detect development platform
```
### 𧬠DNA & Evolution
```bash
faf dna # Show evolution journey (12% β 89% β 99%)
faf log # Complete evolution history
faf update # Save checkpoint
faf recover # Disaster recovery
faf auth # Birth certificate authentication
```
### π Scoring & Trust
```bash
faf score # Rate completeness (0-100%)
faf trust # Unified trust dashboard
faf credit # Technical credit dashboard
faf check # Comprehensive validation
faf validate # Structure validation
faf audit # Freshness check
```
### β‘ Creative & Quick
```bash
faf chat # Natural language generation (terminal only)
faf quick # One-liner instant context
```
### π Discovery & Verification
```bash
faf verify # Test with Claude Code, OpenAI Codex CLI, Gemini CLI
faf doctor # Diagnose & fix issues
faf search # Content search with highlighting
```
### π Sync & Mirror
```bash
faf bi-sync # Bidirectional .faf β CLAUDE.md (8ms!)
faf sync # Dependency updates
faf tsa # Inspect dependencies
```
### π Editing & Management
```bash
faf edit # Interactive editor
faf convert # YAML to Markdown/Text
faf to-txt # Quick text conversion
faf share # Secure sharing with auto-sanitization
```
### π Information & Help
```bash
faf show # Display stats
faf status # Quick health status
faf version # Show version (with ASCII art!)
faf index # Universal A-Z reference
faf faq # Frequently asked questions
faf welcome # Welcome guide
```
### π§Ή Utilities
```bash
faf clear # Clear caches & reset state
faf todo # Claude-inspired todo system
faf analytics # Usage analytics & telemetry
faf notifications # Email notifications
faf lint # Fix formatting issues
```
**Run `faf --help` for complete command reference**
## π€ Works with AI Assistants
FAF v3.0.3 fully supports **Claude Code, Warp, Cursor, Copilot, Windsurf, OpenAI Codex CLI, Gemini CLI** and ALL AI coding assistants.
**PLUS AI-Automation platforms:** n8n, OpenAI Builder, Google Opal, Make.com
### β
These Commands Work Everywhere
```bash
faf init # Create .faf file
faf auto # Auto-enhance context
faf enhance # Improve programmatically
faf score # Check readiness
faf bi-sync # Sync .faf β CLAUDE.md
faf formats # Format discovery
```
### π‘ Avoid in AI Assistants
```bash
faf chat # Requires interactive terminal
faf # Interactive menu (use faf auto instead)
```
**Why?** Interactive commands use `inquirer` for beautiful CLI menus. These work in regular terminals but AI assistants can't forward keyboard input. **This is expected behavior.**
**Solution:** Use `faf auto` - it's designed for AI assistants! β‘
## π Championship Scoring
Track your project's AI-readiness with F1-inspired tiers:
```
π Trophy (100%) - Championship - Perfect 50|50 AI|HUMAN balance
π₯ Gold (99%) - Gold standard
π₯ Silver (95-98%) - Excellence
π₯ Bronze (85-94%) - Production ready
π’ Green (70-84%) - Good foundation
π‘ Yellow (55-69%) - Getting there
π΄ Red (0-54%) - Needs attention
π€ Heart 0% - Starting Good Luck!
```
**Live output:**
```bash
faf score
```
```
π₯ Score: 89/100
ββββββββββββββββββββββββ 89%
Status: Bronze - Production Ready
Next milestone: 95% π₯ Silver (6 points to go!)
ποΈ FAF Championship Status
ββββββββββββββββββββββββββββββββββββββ
Initial DNA: 12% (born 2025-10-03)
Growth: +77% over 4 days
Next Milestone: 95% π₯ Silver (6% to go!)
```
## βοΈ AI | HUMAN Balance - The 50|50 Championship System
**NEW in v3.0.0:** Track the perfect balance between AI-readable and human-readable content.
### Normal Balance (Any Ratio)
<div align="center">
<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/ai-human-balance-50-50.png" alt="AI|HUMAN Balance at 50/50" width="700" />
</div>
**AI 50% | HUMAN 50%** β Working toward optimal context
### π PERFECT BALANCE ACHIEVED! (50|50)
<div align="center">
<img src="https://cdn.jsdelivr.net/npm/faf-cli@latest/assets/prd-balance-perfect-green.png" alt="PRD Balance - Perfect 50/50 goes GREEN" width="700" />
</div>
**βοΈ PERFECT BALANCE!** β When you hit exactly 50|50, the balance bar turns **GREEN π** signaling championship-level context optimization. This is the sweet spot where AI and human readers both get exactly what they need.
**PRD Balance = Production-Ready Balance** π
## π‘ Usage Examples
```bash
# Quick setup for new project
faf quick "my-app, react, typescript, vercel"
# Auto-detect existing project
faf auto
# Discover your formats
faf formats
# Check score with details
faf score --details
# Bidirectional sync with CLAUDE.md
faf bi-sync
# Track your evolution
faf dna
faf log
# Fix issues
faf doctor
# Optimize scoring
faf enhance
# Quiet mode (for AI assistants)
faf init -q
faf auto -q
```
## π Technical Specs
```yaml
Version: 3.0.3 - Championship Edition
Performance: <50ms all commands, 18ms avg, 8ms bi-sync, 0ms operations achieved
Engine: FAF-Engine-Mk3
TURBO-CAT: v3.0.0 - Full Power (Introduced v2.0.0, 153 validated formats)
TypeScript: 100% strict mode
Dependencies: 2 (inquirer, yaml)
Testing: WJTTC GOLD Certified (12,500+ test iterations)
Certification: https://faf.one/wjttc
Platform: Mac, Linux, Windows
AI Support: Universal - Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, Warp, Copilot, Windsurf, ALL AI coding assistants
Automation: n8n workflows, OpenAI Builder, Google Opal, Make.com - AI-Automation platforms
```
## ποΈ The .faf Pattern
### Why .faf vs RAG?
**.faf is pre-indexed intelligence.** Do the work once, use it forever.
| Aspect | RAG Approach | .faf Approach |
|--------|-------------|---------------|
| **Indexing** | Runtime embedding (slow, $$) | One-time at creation (fast, free) |
| **Retrieval** | Vector search per query ($$) | Instant file read (free) |
| **Quality** | Probabilistic, incomplete | Structured, validated, scored |
| **Latency** | Seconds (embedding + search) | Milliseconds (<50ms) |
| **Cost** | Per-query fees | Zero runtime cost |
| **Versioning** | Difficult | Git-friendly YAML |
**.faf is RAG's outputβcaptured once, reused infinitely.** Championship efficiency.
### Universal Pattern
Every source follows the same pattern:
```
interrogation β extraction β filtering β generation β .faf
```
**In FREE CLI:** Code projects β .faf (all languages, frameworks, stacks)
**In TURBO:** Automation platforms β .faf (n8n, OpenAI Assistants, Opal, Make.com)
Same pattern. Same output. Universal by design.
## π WJTTC Championship Testing
**FAF CLI v3.0.3 is WJTTC GOLD Certified** - tested to F1-grade standards.
### What is WJTTC?
**WolfeJam Technical & Testing Center** - F1-inspired testing methodology ensuring championship-grade reliability.
### Certification: π₯ GOLD (92/100)
**Battle-tested with 12,500+ test iterations across 5 testing tiers:**
- β
**BIG-3 AI Validation** (11,200 iterations - Claude, ChatGPT/Codex, Gemini)
- β
**287 Automated Tests** (191 Jest unit + 66 Championship Safety + 30 YOLO torture)
- β
**730 Empirical C.O.R.E Tests** (100% MCP protocol compliance)
- β
**301 Context-On-Demand Tests** (Torture testing, edge cases, stress scenarios)
- β
**35+ Test Documents** (Comprehensive validation reports)
**Performance Validated:**
- β‘ **0ms operations** achieved (unmeasurable speed!)
- β‘ **8ms bi-sync** verified (championship speed)
- β‘ **Sub-10ms** for 68% of all operations
**Safety Tested:**
- π‘οΈ **7 production-breaking bugs** fixed before release
- π‘οΈ **3 security vulnerabilities** patched proactively
- π‘οΈ **Zero critical failures** in production systems
**Platform Verified:**
- β
Mac, Linux, Windows
- β
Claude Code, Cursor, AI Assistants
- β
Big-3 AI Compatible (Claude Code, OpenAI Codex CLI, Gemini CLI)
## π¬ Context-Mirroring (Bi-Sync)
Keep `.faf` (structured data) and `CLAUDE.md` (human-readable) in perfect sync automatically.
### Features
- **As fast as 8ms** (typical 10-15ms, 95% under 50ms)
- **Bidirectional:** `.faf` β `CLAUDE.md`
- **Zero-slippage:** Atomic file operations design
- **Cross-platform:** Mac + Windows verified
- **Universal:** Works with any Tool.md format
### Live Output
```
π C-MIRROR LIVE
βββββββββββββββββββββββββ
ββ Syncing β claude-to-faf...
ββ ββββββββββββββββββββββββ 10% - Parsing CLAUDE.md...
ββ ββββββββββββββββββββββββ 40% - Merging updates...
ββ ββββββββββββββββββββββββ 70% - Updating metadata...
ββ ββββββββββββββββββββββββ 90% - Generating YAML...
ββ π Synchronized in 8ms ποΈβ‘οΈ
β
Integrity: PERFECT
π Technical Credit +1
```
## π The FAF Ecosystem
- π©΅ **[faf-cli](https://github.com/Wolfe-Jam/faf-cli)** - This command-line tool (FREE FOREVER)
- π§‘ **[claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp)** - MCP server for Claude Desktop
- π **[faf.one](https://faf.one)** - Documentation & guides
- π₯οΈ **[Chrome Extension](https://chromewebstore.google.com/detail/lnecebepmpjpilldfmndnaofbfjkjlkm)** - Browser integration
- π¨ **FAF TURBO** - Premium features - Launched πΈ
## ποΈ Development
```bash
# 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
```
## π Requirements
- **Node.js** 18+
- **OS:** macOS, Linux, or Windows
- **AI Tools:** Works with Claude, Codex, Gemini, Cursor, Warp etc.
## π€ Contributing
We welcome contributions! Join our [community discussions](https://github.com/Wolfe-Jam/faf-cli/discussions) or submit issues/PRs.
**Join our growing community** using `.faf` to accelerate their AI workflows:
- Share your projects
- Get help from the community
- Request features
- Learn best practices
## π Strategic Sponsorship Opportunities
**Position your brand alongside the universal AI context standard.**
FAF CLI is defining a new category: **Universal AI Context Infrastructure**. With BIG-3 AI validation (Google, Anthropic, OpenAI) and adoption by leading AI development tools, FAF is becoming foundational infrastructure for the AI development ecosystem.
### π Growth Momentum
- **Rapid adoption** - See live stats on npm
- **Category leader** - First universal AI context standard
- **Enterprise traction** - Infrastructure-level adoption
- **BIG-3 validated** - Tested and endorsed by Google Gemini, Anthropic Claude, OpenAI Codex
### π Strategic Partnership Opportunities
**Infrastructure Sponsor** - Align your brand with foundational AI developer tooling
**Category Leadership** - Be recognized as supporting the universal AI context standard
**Enterprise Integration** - Deep integrations with your platform
**Target sponsors:** Companies building AI development tools, deployment platforms, terminals, IDEs, and AI infrastructure.
**Examples:** Vercel, Warp, Anthropic, Cursor, Windsurf, n8n, and other AI-first platforms.
### π€ Let's Talk
**[πΌ Enterprise Sponsorship Inquiry](https://github.com/Wolfe-Jam/faf-cli/discussions)** - Strategic partnerships for category-defining infrastructure
FAF CLI is **FREE FOREVER** and open source (MIT). Sponsorship accelerates development, expands integrations, and positions your brand alongside the future of AI development.
## π License
MIT License - See [LICENSE](./LICENSE) file
## π The Race Track is Open
**Category-defining. Format-first development. Foundational.**
AI's biggest issue addressed head-on. Agnostic. Universal.
AI has Claude/tool.md - they need `.faf` to be Universal.
AI needed a README, its package.json - **it got one.**
### **SPEED. SECURITY. UNIVERSAL. FREE. OPEN-SOURCE.**
Copy cats? Why bother.
**Build your best, let's RACE π**
**See you at the Track! ποΈβ‘οΈ**
<div align="center">
## π v3.0.3 - Championship Edition
**FREE FOR ALL DEVS** π β’ **TURBO-CAT Powered** π½ β’ **Growing Fast** π
Made with π§‘ by **[wolfejam](https://github.com/Wolfe-Jam)**
**100% Open Source** β’ **Zero Faffβ’** β’ **F1-Inspired Engineering**
[β Star on GitHub](https://github.com/Wolfe-Jam/faf-cli) β’ [π¦ View on NPM](https://www.npmjs.com/package/faf-cli) β’ [π¬ Join Discussions](https://github.com/Wolfe-Jam/faf-cli/discussions)
The CLI is **FREE FOR ALL DEVS**.
Love it? **TURBO** for advanced features, ready for once you've kicked the tires! π½π¨
</div>