Skip to main content

​
OpenFang CLI Overview

The openfang binary is the primary interface for managing the OpenFang Agent OS. It provides comprehensive control over agents, workflows, skills, channels, and system configuration.

​
Two Operation Modes

OpenFang CLI supports two modes of operation: When a daemon is running (openfang start), CLI commands communicate with it over HTTP. This is the recommended mode for production use. 
openfang start
# In another terminal
openfang agent list
openfang chat
Daemon mode provides persistent agents, background task execution, and the web dashboard.

​
In-Process Mode

When no daemon is detected, commands boot an ephemeral in-process kernel. Agents spawned in this mode are not persisted and will be lost when the process exits. 
# No daemon running
openfang chat  # Boots temporary kernel, spawns agent
Agents created in in-process mode are ephemeral and will be lost when the CLI exits.

​
Installation

​
From Source (Cargo)

cargo install --path crates/openfang-cli

​
Build from Workspace

cargo build --release -p openfang-cli
# Binary: target/release/openfang (or openfang.exe on Windows)

​
Docker

docker run -it openfang/openfang:latest

​
Shell Installer

curl -fsSL https://get.openfang.ai | sh

​
Global Options

These options apply to all commands:
OptionDescription
--config <PATH>Path to a custom config file (overrides ~/.openfang/config.toml)
--helpPrint help information for any command or subcommand
--versionPrint the version of the openfang binary

​
Environment Variables

VariableDescription
RUST_LOGControls log verbosity (e.g. info, debug, openfang_kernel=trace)
OPENFANG_HOMEOverride the default ~/.openfang/ directory
OPENFANG_AGENTS_DIROverride the agent templates directory
EDITOR / VISUALEditor used by openfang config edit (falls back to notepad on Windows or vi on Unix)

​
Interactive TUI Dashboard

Running openfang with no subcommand launches the interactive TUI (terminal user interface): 
openfang
The TUI provides a full-screen terminal interface with panels for:
  • Agents management
  • Interactive chat
  • Workflows
  • Channels
  • Skills
  • Settings
  • System status
Press Ctrl+C to exit. A second Ctrl+C force-exits the process. Tracing output is redirected to ~/.openfang/tui.log.

​
Quick Start Guide

​
First-Time Setup

# 1. Set your API key
export GROQ_API_KEY="gsk_your_key_here"

# 2. Initialize OpenFang
openfang init --quick

# 3. Start the daemon
openfang start

​
Daily Usage

# Quick chat (auto-spawns agent if needed)
openfang chat

# Chat with a specific agent
openfang chat coder

# Check what's running
openfang status

# Open the web dashboard
openfang dashboard

​
Core Commands

​
Initialization & Daemon

  • openfang init - Initialize workspace and configuration
  • openfang start - Start the daemon
  • openfang stop - Stop the running daemon
  • openfang status - Show daemon status
  • openfang doctor - Run diagnostic health checks

​
Quick Actions

  • openfang chat [agent] - Start a chat session
  • openfang dashboard - Open web dashboard
  • openfang tui - Launch terminal UI

​
Management Commands

  • openfang agent - Manage agents (new, list, chat, kill)
  • openfang workflow - Manage workflows
  • openfang skill - Manage skills
  • openfang channel - Manage channel integrations
  • openfang config - Configuration management

​
Daemon Auto-Detection

The CLI uses a two-step mechanism to detect a running daemon:
  1. Read daemon.json - The daemon writes ~/.openfang/daemon.json containing the listen address
  2. Health check - The CLI sends GET http://<listen_addr>/api/health with a 2-second timeout
If either step fails, the CLI falls back to in-process mode for commands that support it. 
openfang start          # Starts daemon, writes daemon.json
openfang status         # Connects to daemon via HTTP
# Ctrl+C                # Daemon shuts down, daemon.json removed
openfang doctor --repair  # Cleans up stale daemon.json from crashes

​
Environment File

OpenFang loads ~/.openfang/.env into the process environment on every CLI invocation. System environment variables take priority over .env values. 
GROQ_API_KEY=gsk_...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
Manage keys with openfang config set-key / openfang config delete-key commands rather than editing the file directly to enforce correct permissions.

​
Exit Codes

CodeMeaning
0Success
1General error (invalid arguments, failed operations, missing daemon, parse errors, spawn failures)
130Interrupted by second Ctrl+C (force exit)

​
Shell Completions

Generate shell completion scripts for your shell: 
# Bash
openfang completion bash >> ~/.bashrc

# Zsh
openfang completion zsh > "${fpath[1]}/_openfang"

# Fish
openfang completion fish > ~/.config/fish/completions/openfang.fish

# PowerShell
openfang completion powershell > openfang.ps1

​
Supported LLM Providers

The following providers are recognized by openfang config set-key and openfang doctor:
ProviderEnvironment VariableDefault Model
GroqGROQ_API_KEYllama-3.3-70b-versatile
GeminiGEMINI_API_KEY or GOOGLE_API_KEYgemini-2.5-flash
DeepSeekDEEPSEEK_API_KEYdeepseek-chat
AnthropicANTHROPIC_API_KEYclaude-sonnet-4-20250514
OpenAIOPENAI_API_KEYgpt-4o
OpenRouterOPENROUTER_API_KEYopenrouter/auto
TogetherTOGETHER_API_KEY—
MistralMISTRAL_API_KEY—
FireworksFIREWORKS_API_KEY—
PerplexityPERPLEXITY_API_KEY—
CohereCOHERE_API_KEY—
xAIXAI_API_KEY—
Additional search/fetch provider keys: BRAVE_API_KEY, TAVILY_API_KEY.

​
Next Steps

Daemon Management

Learn about starting, stopping, and managing the OpenFang daemon

Agent Commands

Create and manage AI agents from the command line

Workflow Commands

Orchestrate multi-step agent workflows

Skills & Channels

Install skills and configure integrations