# OpenFang CLI Reference Complete command-line reference for `openfang`, the CLI tool for the OpenFang Agent OS. ## Overview The `openfang` binary is the primary interface for managing the OpenFang Agent OS. It supports two modes of operation: - **Daemon mode** -- When a daemon is running (`openfang start`), CLI commands communicate with it over HTTP. This is the recommended mode for production use. - **In-process mode** -- When no daemon is detected, commands that support it will boot an ephemeral in-process kernel. Agents spawned in this mode are not persisted and will be lost when the process exits. Running `openfang` with no subcommand launches the interactive TUI (terminal user interface) built with ratatui, which provides a full dashboard experience in the terminal. ## Installation ### From source (cargo) ```bash cargo install --path crates/openfang-cli ``` ### Build from workspace ```bash cargo build --release -p openfang-cli # Binary: target/release/openfang (or openfang.exe on Windows) ``` ### Docker ```bash docker run -it openfang/openfang:latest ``` ### Shell installer ```bash curl -fsSL https://get.openfang.ai | sh ``` ## Global Options These options apply to all commands. | Option | Description | |---|---| | `--config ` | Path to a custom config file. Overrides the default `~/.openfang/config.toml`. | | `--help` | Print help information for any command or subcommand. | | `--version` | Print the version of the `openfang` binary. | **Environment variables:** | Variable | Description | |---|---| | `RUST_LOG` | Controls log verbosity (e.g. `info`, `debug`, `openfang_kernel=trace`). | | `OPENFANG_AGENTS_DIR` | Override the agent templates directory. | | `EDITOR` / `VISUAL` | Editor used by `openfang config edit`. Falls back to `notepad` (Windows) or `vi` (Unix). | --- ## Command Reference ### openfang (no subcommand) Launch the interactive TUI dashboard. ``` openfang [--config ] ``` The TUI provides a full-screen terminal interface with panels for agents, chat, workflows, channels, skills, settings, and more. Tracing output is redirected to `~/.openfang/tui.log` to avoid corrupting the terminal display. Press `Ctrl+C` to exit. A second `Ctrl+C` force-exits the process. --- ### openfang init Initialize the OpenFang workspace. Creates `~/.openfang/` with subdirectories (`data/`, `agents/`) and a default `config.toml`. ``` openfang init [--quick] ``` **Options:** | Option | Description | |---|---| | `--quick` | Skip interactive prompts. Auto-detects the best available LLM provider and writes config immediately. Suitable for CI/scripts. | **Behavior:** - Without `--quick`: Launches an interactive 5-step onboarding wizard (ratatui TUI) that walks through provider selection, API key configuration, and optionally starts the daemon. - With `--quick`: Auto-detects providers by checking environment variables in priority order: Groq, Gemini, DeepSeek, Anthropic, OpenAI, OpenRouter. Falls back to Groq if none are found. - File permissions are restricted to owner-only (`0600` for files, `0700` for directories) on Unix. **Example:** ```bash # Interactive setup openfang init # Non-interactive (CI/scripts) export GROQ_API_KEY="gsk_..." openfang init --quick ``` --- ### openfang start Start the OpenFang daemon (kernel + API server). ``` openfang start [--config ] ``` **Behavior:** - Checks if a daemon is already running; exits with an error if so. - Boots the OpenFang kernel (loads config, initializes SQLite database, loads agents, connects MCP servers, starts background tasks). - Starts the HTTP API server on the address specified in `config.toml` (default: `127.0.0.1:4200`). - Writes `daemon.json` to `~/.openfang/` so other CLI commands can discover the running daemon. - Blocks until interrupted with `Ctrl+C`. **Output:** ``` OpenFang Agent OS v0.1.0 Starting daemon... [ok] Kernel booted (groq/llama-3.3-70b-versatile) [ok] 50 models available [ok] 3 agent(s) loaded API: http://127.0.0.1:4200 Dashboard: http://127.0.0.1:4200/ Provider: groq Model: llama-3.3-70b-versatile hint: Open the dashboard in your browser, or run `openfang chat` hint: Press Ctrl+C to stop the daemon ``` **Example:** ```bash # Start with default config openfang start # Start with custom config openfang start --config /path/to/config.toml ``` --- ### openfang status Show the current kernel/daemon status. ``` openfang status [--json] ``` **Options:** | Option | Description | |---|---| | `--json` | Output machine-readable JSON for scripting. | **Behavior:** - If a daemon is running: queries `GET /api/status` and displays agent count, provider, model, uptime, API URL, data directory, and lists active agents. - If no daemon is running: boots an in-process kernel and shows persisted state. Displays a warning that the daemon is not running. **Example:** ```bash openfang status openfang status --json | jq '.agent_count' ``` --- ### openfang doctor Run diagnostic checks on the OpenFang installation. ``` openfang doctor [--json] [--repair] ``` **Options:** | Option | Description | |---|---| | `--json` | Output results as JSON for scripting. | | `--repair` | Attempt to auto-fix issues (create missing directories, config, remove stale files). Prompts for confirmation before each repair. | **Checks performed:** 1. **OpenFang directory** -- `~/.openfang/` exists 2. **.env file** -- exists and has correct permissions (0600 on Unix) 3. **Config TOML syntax** -- `config.toml` parses without errors 4. **Daemon status** -- whether a daemon is running 5. **Port 4200 availability** -- if daemon is not running, checks if the port is free 6. **Stale daemon.json** -- leftover `daemon.json` from a crashed daemon 7. **Database file** -- SQLite magic bytes validation 8. **Disk space** -- warns if less than 100MB available (Unix only) 9. **Agent manifests** -- validates all `.toml` files in `~/.openfang/agents/` 10. **LLM provider keys** -- checks env vars for 10 providers (Groq, OpenRouter, Anthropic, OpenAI, DeepSeek, Gemini, Google, Together, Mistral, Fireworks), performs live validation (401/403 detection) 11. **Channel tokens** -- format validation for Telegram, Discord, Slack tokens 12. **Config consistency** -- checks that `api_key_env` references in config match actual environment variables 13. **Rust toolchain** -- `rustc --version` **Example:** ```bash openfang doctor openfang doctor --repair openfang doctor --json ``` --- ### openfang dashboard Open the web dashboard in the default browser. ``` openfang dashboard ``` **Behavior:** - Requires a running daemon. - Opens the daemon URL (e.g. `http://127.0.0.1:4200/`) in the system browser. - Copies the URL to the system clipboard (uses PowerShell on Windows, `pbcopy` on macOS, `xclip`/`xsel` on Linux). **Example:** ```bash openfang dashboard ``` --- ### openfang completion Generate shell completion scripts. ``` openfang completion ``` **Arguments:** | Argument | Description | |---|---| | `` | Target shell. One of: `bash`, `zsh`, `fish`, `elvish`, `powershell`. | **Example:** ```bash # Bash openfang completion bash > ~/.bash_completion.d/openfang # Zsh openfang completion zsh > ~/.zfunc/_openfang # Fish openfang completion fish > ~/.config/fish/completions/openfang.fish # PowerShell openfang completion powershell > openfang.ps1 ``` --- ## Agent Commands ### openfang agent new Spawn an agent from a built-in template. ``` openfang agent new [