⚡ TidyFactor Multi-Platform CLI & Shell Installers Guide¶

Comprehensive guide to the TidyFactor command-line interface, 3-step interactive setup wizard, dual-redundant installation architecture, and standalone zero-dependency shell engines supporting 18+ Agentic AI IDEs.

🌟 Executive Overview¶

TidyFactor provides a developer-first, zero-friction distribution system for mounting AI coding agent skills across 18+ AI Agent IDEs (Trae, Cursor, Windsurf, Google Antigravity, GitHub Copilot, RooCode, OpenCode, KiloCode, Warp, Kiro, Claude Code, Zed, JetBrains, Blackbox, Cline, AMP, OpenClaw, Codex).

TidyFactor Interactive CLI Setup Wizard AI Agent Slash Commands Autocomplete (/tidy)

🏛️ Dual-Redundant Fallback Architecture¶

The TidyFactor CLI implements a 3-tier resilient fallback pipeline that guarantees 100% skill delivery regardless of network anomalies or registry availability:

graph TD
    Start["npx @tidyfactor/cli add &lt;skill&gt;"] --> LocalCheck{"1. Local Workspace Check (Dev Mode)"}
    LocalCheck -->|Directory Found| FastLocal["Fast-Path Local Sync (0ms latency)"]
    LocalCheck -->|Not Found| NPMPrimary{"2. Primary Network: NPM Registry (@tidyfactor)"}

    NPMPrimary -->|npx add-skill Succeeded| SyncTargets["Mount & Mirror into Target Agent Folders"]
    NPMPrimary -->|Timeout / Rate-Limit / Offline| DirectCDN{"3. Secondary Fallback: TidyFactor Hub CDN"}

    DirectCDN -->|Download & Extract .skill Archive| SyncTargets
    SyncTargets --> Completed["✔ Skill Verified, Mounted & Ready in Chat"]

Tier 1 (Fast-Path Local Sync): If developing inside the TidyFactor monorepo, skills are copied locally with zero network latency.
Tier 2 (Primary Network — NPM / NPX): Executes npx -y @tidyfactor/<skill> add-skill, taking advantage of NPM's global edge caching and local ~/.npm/_npx/ cache.
Tier 3 (Secondary Fallback — Self-Hosted Binary CDN): Automatically falls back to downloading .skill binaries directly from https://tidyfactor.com/downloads/skills/<skill>.skill and extracting natively with zero Node.js scripts.

🤖 Supported 18+ Agentic IDEs Matrix¶

Agent / IDE Environment	Mount Path	Detection Signatures	CLI Direct Target Flag
Trae AI IDE	`.trae/skills/`	`.trae`, `.traerules`	`--trae`
Cursor IDE	`.cursor/skills/`	`.cursor`, `.cursorrules`	`--cursor`
Windsurf Cascade	`.windsurf/skills/`	`.windsurf`, `.windsurfrules`	`--windsurf`
Google Antigravity / Gemini	`.agents/skills/`	`.agents`, `GEMINI.md`	`--antigravity`
GitHub Copilot	`.github/prompts/`	`.github/copilot-instructions.md`	`--copilot`
RooCode (Roo Cline)	`.roo/skills/`	`.roo`, `.roomodes`, `.roo/rules`	`--roo`, `--roocode`
OpenCode / Zen	`.opencode/skills/`	`.opencode`, `opencode.json`	`--opencode`
KiloCode	`.kilocode/skills/`	`.kilocode`, `kilo.jsonc`, `.kilo`	`--kilocode`, `--kilo`
Warp Terminal	`.warp/skills/`	`.warp`, `.warp/workflows`	`--warp`
Kiro (AWS Spec-Driven IDE)	`.kiro/skills/`	`.kiro`, `.kiro/steering`	`--kiro`
Claude Code	`.claude/skills/`	`.claude`, `CLAUDE.md`	`--claude`
Zed AI Agent	`.zed/skills/`	`.zed`, `.zed/settings.json`	`--zed`
JetBrains AI (IDEA/Junie)	`.jetbrains/skills/`	`.idea`, `.idea/ai`	`--jetbrains`
Blackbox AI	`.blackbox/skills/`	`.blackbox`, `.blackboxrules`	`--blackbox`
Cline (VS Code)	`.cline/skills/`	`.clinerules`, `.cline`	`--cline`
AMP AI	`.amp/skills/`	`.amprules`, `.amp`	`--amp`
OpenClaw	`.openclaw/skills/`	`.openclaw`, `.clawdbot`	`--openclaw`
Universal Workspace Default	`.agents/skills/`	Automatic fallback	default
Global Cross-Project Hub	`~/.gemini/config/skills/`	Shared across all repositories	`--global`, `-g`
⚡ Multi-Mount (All Active)	All detected agents	Automatic environment discovery	`--all-agents`

⚡ Quick Start: 3-Step Interactive Setup Wizard¶

The interactive wizard guides developers through discovering their project environment, choosing target agents, and installing curated packs:

npx @tidyfactor/cli init

Wizard Breakdown:¶

[Step 1/3] Environment & Agent Discovery: Auto-detects workspace type (PHP Monolith, Next.js SaaS, Static HTML, JS SPA) and active IDE configurations.
[Step 2/3] Choose Target Agentic IDE(s):
1) Universal Default (.agents/skills/)
2) Trae AI IDE (.trae/skills/)
3) Cursor IDE (.cursor/skills/)
4) Windsurf Cascade (.windsurf/skills/)
5) GitHub Copilot (.github/prompts/)
6) RooCode (.roo/skills/)
7) OpenCode / Zen (.opencode/skills/)
8) KiloCode (.kilocode/skills/)
9) Warp Terminal (.warp/skills/)
10) Kiro Spec IDE (.kiro/skills/)
11) Claude Code (.claude/skills/)
12) Zed AI Agent (.zed/skills/)
13) JetBrains AI (.jetbrains/skills/)
14) Global User Hub (~/.gemini/config/skills/)
15) ⚡ Auto Multi-Mount (Mount to ALL active agents simultaneously)
[Step 3/3] Choose Skill Package / Track:
1) 🌟 Auto-Recommended Kit (Tailored to detected stack)
2) 👑 Master Suite (All 12 production skills)
3) 🎨 Design & Frontend Triad (pack:design)
4) 🚀 SaaS & Next.js Stack (pack:saas)
5) ⚙️ Monolith & PHP Engine (pack:engineering)
6) 🏛️ Governance & Operations (pack:governance)
7) 📦 Browse Curated Workflow Packs
8) 🗂️ Browse by Category
9) 🧩 Custom Selection by ID

📦 Official Curated Workflow Packs¶

Pack ID	Included Skills	Target Use Case	Command
`pack:design`	`tidyfactor-cinematic` `tidyfactor-design` `tidyfactor-styler`	Luxury Landing Pages, Code-Native Prototyping & RTL Polish	`npx @tidyfactor/cli add pack:design`
`pack:saas`	`tidyfactor-next` `tidyfactor-design` `tidyfactor-marketing` `tidyfactor-doc`	Next.js 16 Multi-Tenant SaaS with Supabase RLS & SEO	`npx @tidyfactor/cli add pack:saas`
`pack:engineering`	`tidyfactor-php` `tidyfactor-htmx` `tidyfactor-js` `tidyfactor-html` `tidyfactor-doc`	Full-Stack PHP 8.x Monoliths, HTMX & Reactive SPAs	`npx @tidyfactor/cli add pack:engineering`
`pack:governance`	`tidyfactor-skill-architect` `tidyfactor-doc` `tidyfactor-github`	Skill Architecture Rules, Docsify Engines & GitHub CI/CD	`npx @tidyfactor/cli add pack:governance`
`pack:growth`	`tidyfactor-marketing` `tidyfactor-cinematic` `tidyfactor-styler`	Direct-Response Copywriting, Pillar SEO & Conversions	`npx @tidyfactor/cli add pack:growth`

🍺 macOS & Linux Homebrew Tap¶

For developers on macOS (Apple Silicon / Intel) and Linux with Homebrew:

# 1. Tap the official TidyFactor repository
brew tap TidyFactor/tidyfactor

# 2. Install TidyFactor CLI globally
brew install tidyfactor

# Or in a single one-liner:
brew install TidyFactor/tidyfactor/tidyfactor

Once installed, use tidyfactor (or shorthand tf) directly from any terminal:

tidyfactor list
tf add pack:design
tf doctor

💻 Standalone Shell Installers (Zero Node.js Dependency)¶

For minimal server environments, CI/CD runners, and developers without Node.js installed:

Linux & macOS (POSIX Bash + cURL)¶

# Interactive mode (reads from /dev/tty even when piped)
curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash

# Install a specific curated pack
curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash -s -- pack:design

# Install all 12 skills
curl -fsSL https://tidyfactor.com/api/v1/install.sh | bash -s -- all

Windows (PowerShell 5.1 & 7+)¶

# Interactive mode
irm https://tidyfactor.com/api/v1/install.ps1 | iex

# Install a specific pack
$Skill = 'pack:design'; irm https://tidyfactor.com/api/v1/install.ps1 | iex

# Install all 12 skills
$Skill = 'all'; irm https://tidyfactor.com/api/v1/install.ps1 | iex

🩺 Diagnostic & Health Audit Command¶

Audit your current workspace, detect project tech stack, and check mounted agent skill folders:

npx @tidyfactor/cli doctor

🩺 Workspace Diagnostics & 18+ Agent Readiness:
  • Workspace Path:     /var/www/my-project
  • Detected Stack:     Next.js (React Framework)
  • Recommended Skills: tidyfactor-next, tidyfactor-design, tidyfactor-styler
  • Active Agents:      Cursor (.cursor/skills), Trae (.trae/skills), Antigravity (.agents/skills)
  • Registry Host:      tidyfactor.com (/api/v1/skills)

🤖 Post-Install Command Triggers¶

Once installed, simply type /tidy or specific slash commands in your AI coding agent chat:

/hero        → Build luxury Canvas hero sequence (Cinematic)
/component   → Surgical UI refactor & RTL polish (Styler)
/tokens      → Design system tokens & palette (Design)
/tenant      → Multi-tenant Supabase RLS isolation (Next)
/admin       → Locked admin module scaffolding (PHP)
/strategy    → Direct-response marketing & SEO (Marketing)
/site        → Generate Docsify/MkDocs documentation (Doc)
/ruleset     → GitHub branch protection rulesets (GitHub)