Commands

Install

deno run -A jsr:@fathym/fai/install

Installs fai globally. Deno is required. After install, fai is available on your PATH.

`fai`

Start your AI workbench. Opens a session where your AI remembers everything from past sessions and helps you build.

fai

Flags:

Flag	Description
`--dry-run`	Preview what your workbench will do without making changes
`--auto`	No prompts and no session picker. Continues the most recently started session on this machine (it can belong to another project), or creates one if there are none. Use `--sessionId` to pick one
`--mcp-session=stdio`	Run the session MCP server over stdio, for MCP clients that start fai themselves. Pair with `--auto`
`--preview`	Launch MCP Inspector to explore all active tools
`--share`	Open a public relay tunnel - share your workbench remotely
`--sessionId <id>`	Skip the session picker and open a specific session

`fai detect`

Scan for AI tools, local models, and synthesis providers installed on your system.

fai detect
fai detect --models
fai detect --agents
fai detect --verify

Flag	Description
`--models`	Filter results to models only
`--agents`	Filter results to agents only
`--verify`	Verify each detected item is reachable

`fai orient`

Orient an AI agent with your project context. Generates the agent's context file from your current workbench state.

fai orient
fai orient [content]

Flag	Description
`--source`	Source type for orientation content
`--file`	File input for orientation
`--mode`	Orientation mode
`--fileSuffix`	File suffix to use for generated context file

`fai synthesize`

Configure your synthesis provider - the AI model that distills session captures into project knowledge.

fai synthesize
fai synthesize --non-interactive

Flag	Description
`--non-interactive`	Auto-configure without prompts
`--context-window <tokens>`	Token budget per synthesis step. Overrides the provider default; match it to your model's context

Supported providers: ollama, lmstudio, localai, azure-openai, openrouter, groq, openai, a custom OpenAI-compatible endpoint, or capture-only

Note: ANTHROPIC_API_KEY is not supported — the Anthropic API is not OpenAI-compatible. To use Claude models, set OPENROUTER_API_KEY instead.

See Local Models → for setup with Ollama, LM Studio, and cloud API keys.

`fai mcp`

Manage other MCP servers: install them into every detected agent, generate skill files, and inspect them. These commands don't control fai's own two servers - those start with fai and fai serve (see MCP Server).

Command	What it does
`fai mcp install`	Add a third-party MCP server to every detected agent's config
`fai mcp uninstall`	Remove one again
`fai mcp preview`	Open MCP Inspector against an installed or ad-hoc server
`fai mcp generate`	Write `.md` skill files from fai's prompts

`fai mcp generate`

Generate .md skill files from the fai MCP server's prompts.

fai mcp generate
fai mcp generate --output <dir>

Flag	Description
`--output`	Directory to write skill files into (default: `.claude/commands`)
`--server`	MCP server binary to connect to (default: current fai binary)

Connects to the general server (fai serve --mcp=stdio), lists all prompts, and writes one .md file per prompt. Prompt / separators map to subdirectories: holonic/explain → <output>/holonic/explain.md. Claude Code reads .claude/commands/ as slash commands.

This runs automatically in the background on each fai session start for Claude Code.

`fai mcp install`

Install a third-party MCP server into all detected coding agent config files.

fai mcp install <url> [--name <name>] [--auth <token>] [--task <cmd>]

Flag	Description
`--name`	Server name/key in configs (default: URL hostname)
`--auth`	Bearer auth token
`--auth-header`	Custom auth header name to send `--auth` in (e.g. `LANGSMITH-API-KEY`)
`--task`	Deno task name or command for auto-start on `fai` boot
`--global`	Install to the global registry (`~/.fai`) instead of the project
`--session`	Install only for the active fai session; removed when the session ends

Writes the server's URL and auth into each agent's native MCP config. When --task is provided, the server auto-starts on every fai session.

fai mcp install https://mcp.example.com/api --name my-server --auth sk-abc123
fai mcp install http://localhost:3000/mcp --name github --task "npx @mcp/server-github"

`fai mcp uninstall`

Remove a third-party MCP server from every detected agent's config and from fai's registry.

fai mcp uninstall <name>
fai mcp uninstall            # pick from installed servers

Flag	Description
`--global`	Target the global registry (`~/.fai`)
`--session`	Target the active fai session
`--remove-task`	Also remove the `fai:mcp:<name>` deno task (default: on)

`fai mcp preview`

Launch MCP Inspector to preview an installed or ad-hoc MCP server.

fai mcp preview                                     # interactive selector
fai mcp preview <mcpName>                            # named server
fai mcp preview --host https://host.mcp/server       # ad-hoc

Flag	Description
`--host`	MCP server URL for ad-hoc preview (no registry lookup)
`--auth`	Bearer auth token for ad-hoc preview

When no flags or name are provided, shows an interactive selector of installed servers. If the selected server has an auto-start task, it is spawned automatically. Inspector runs until Ctrl+C.

`fai petname`

Manage memorable names for sessions.

fai petname
fai petname [name] [meaning]

Flag	Description
`--scope`	Scope for the petname
`--list`	List all petnames
`--remove`	Remove a petname

`fai sessions`

Work with session history.

fai sessions list
fai sessions list --status <status>
fai sessions list --json

fai sessions [id] capture [content]
fai sessions [id] watch

sessions list flags:

Flag	Description
`--status`	Filter by session status (active, sealed, archived)
`--json`	Output as JSON

sessions [id] capture flags:

Flag	Description
`--file`	File to capture
`--mode`	Capture mode
`--fileSuffix`	File suffix for capture
`--source`	Source type
`--agentType`	Agent type context

sessions [id] watch:

Captures a session's agent logs on a loop, the same way fai does while it runs, until you press Ctrl+C. Use it to keep a session capturing without the full fai start-up. With no [id], it uses FAI_SESSION_ID or asks you to pick a session.

Flag	Description
`--interval`	Seconds between reads (default: 30)

`fai serve`

Start fai's general MCP server on its own, with no session. It serves fai's workflow prompts, docs, and skills, and appears in agent configs as fai-g.

fai serve              # HTTP on port 4966
fai serve --mcp=stdio  # stdio, for MCP clients that start it themselves
fai serve --share      # HTTP plus a public tunnel

fai already starts this server alongside your session, so you only need fai serve when you want the prompts without a session. See Running the loop with fai's MCP.

`fai telemetry`

Turn anonymous usage analytics on or off, or check the current setting.

fai telemetry on
fai telemetry off
fai telemetry status

Subcommand	Description
`on`	Enable usage analytics
`off`	Disable usage analytics
`status`	Show whether analytics are on and your device ID prefix

Analytics are on by default. See Privacy and Telemetry for what's sent and every way to turn it off.

`fai uninstall`

Remove fai from your system.

fai uninstall

`fai workstreams compact`

Compact workstream history.

fai workstreams compact
fai workstreams compact --source <path>

Flag	Description
`--source`	Source path for compaction

Coming soon

As fai evolves, new commands appear - not from a release schedule, but from how you and the community work. When patterns become common enough, they become commands.

Even the CLI grows with you.

On this page

Commands
- ╰─▶Install
- ╰─▶Coming soon