Config Commands

Manage the OpenFang configuration file (config.toml), API keys (.env), and system diagnostics.

openfang init

Initialize the OpenFang workspace. Creates ~/.openfang/ with subdirectories 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

Interactive Mode (Default)
Quick Mode

Launches a 5-step onboarding wizard (ratatui TUI) that walks through:

Provider selection
API key configuration
Model selection
Daemon start
Launch choice (Desktop App, Dashboard, or Chat)

openfang init

Auto-detects providers by checking environment variables in priority order:

Groq → Gemini → DeepSeek → Anthropic → OpenAI → OpenRouter
Falls back to Groq if none are found
Writes config immediately without prompts

export GROQ_API_KEY="gsk_..."
openfang init --quick

Created Structure

~/.openfang/
  config.toml    # Main configuration
  .env           # API keys and secrets (0600 permissions)
  data/          # SQLite database
  agents/        # Agent manifests
  skills/        # User-installed skills

File Permissions

On Unix systems, OpenFang restricts permissions:

Files: 0600 (owner read/write only)
Directories: 0700 (owner read/write/execute only)

Examples

openfang init

openfang config show

Display the current configuration file.

openfang config show

Output

# Config: /home/user/.openfang/config.toml

api_listen = "127.0.0.1:4200"

[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key_env = "GROQ_API_KEY"

[memory]
decay_rate = 0.05

[[channels]]
type = "telegram"
enabled = true
bot_token_env = "TELEGRAM_BOT_TOKEN"

Example

openfang config show

openfang config edit

Open the configuration file in your editor.

openfang config edit

Behavior

Uses the first available editor:

$EDITOR environment variable
$VISUAL environment variable
notepad (Windows)
vi (Unix)

Examples

# Edit with default editor
openfang config edit

# Edit with specific editor
EDITOR=nano openfang config edit
EDITOR=code openfang config edit

openfang config get

Get a single configuration value by dotted key path.

openfang config get <KEY>

Arguments

Argument	Description
`<KEY>`	Dotted key path into the TOML structure (e.g., `default_model.provider`).

Examples

openfang config get default_model.provider
# Output: groq

openfang config set

Set a configuration value by dotted key path.

openfang config set <KEY> <VALUE>

Arguments

Argument	Description
`<KEY>`	Dotted key path (e.g., `default_model.provider`).
`<VALUE>`	New value. Type is inferred from the existing value (integer, float, boolean, or string).

This command re-serializes the TOML file, which strips all comments. Consider using openfang config edit to preserve comments.

Examples

openfang config set default_model.provider anthropic
openfang config set default_model.model claude-sonnet-4-20250514
openfang config set default_model.api_key_env ANTHROPIC_API_KEY

openfang config set-key

Save an LLM provider API key to ~/.openfang/.env.

openfang config set-key <PROVIDER>

Arguments

Argument	Description
`<PROVIDER>`	Provider name (e.g., `groq`, `anthropic`, `openai`, `gemini`, `deepseek`).

Behavior

Prompts interactively for the API key (input is hidden)
Saves to ~/.openfang/.env as <PROVIDER_NAME>_API_KEY=<value>
Runs a live validation test against the provider’s API
Sets file permissions to 0600 (owner-only) on Unix

Supported Providers

Provider	Environment Variable
`groq`	`GROQ_API_KEY`
`gemini`	`GEMINI_API_KEY`
`deepseek`	`DEEPSEEK_API_KEY`
`anthropic`	`ANTHROPIC_API_KEY`
`openai`	`OPENAI_API_KEY`
`openrouter`	`OPENROUTER_API_KEY`
`together`	`TOGETHER_API_KEY`
`mistral`	`MISTRAL_API_KEY`
`fireworks`	`FIREWORKS_API_KEY`
`perplexity`	`PERPLEXITY_API_KEY`
`cohere`	`COHERE_API_KEY`
`xai`	`XAI_API_KEY`

Additional search/fetch providers:

brave → BRAVE_API_KEY
tavily → TAVILY_API_KEY

Example Session

openfang config set-key groq

Output:

Enter your groq API key (input hidden): 

✓ Saved GROQ_API_KEY to ~/.openfang/.env
  Testing key... OK

API key is valid and working.

Examples

openfang config set-key groq

openfang config delete-key

Remove an API key from ~/.openfang/.env.

openfang config delete-key <PROVIDER>

Arguments

Argument	Description
`<PROVIDER>`	Provider name (e.g., `groq`, `anthropic`, `openai`).

Examples

# Remove OpenAI key
openfang config delete-key openai

# Remove Anthropic key
openfang config delete-key anthropic

Output

✓ Removed OPENAI_API_KEY from ~/.openfang/.env

openfang config test-key

Test provider connectivity with the stored API key.

openfang config test-key <PROVIDER>

Arguments

Argument	Description
`<PROVIDER>`	Provider name to test.

Behavior

Reads the API key from the environment (loaded from ~/.openfang/.env)
Hits the provider’s models/health endpoint
Reports OK (key accepted) or FAILED (401/403) (key rejected)
Exits with code 1 on failure

Examples

openfang config test-key groq
# Output: Testing groq (GROQ_API_KEY)... OK

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

System Checks (6)

OpenFang directory — ~/.openfang/ exists
.env file — exists and has correct permissions (0600 on Unix)
Config TOML syntax — config.toml parses without errors
Daemon status — whether a daemon is running
Port 4200 availability — if daemon is not running, checks if the port is free
Stale daemon.json — leftover daemon.json from a crashed daemon

Storage Checks (2)

Database file — SQLite magic bytes validation
Disk space — warns if less than 100MB available (Unix only)

Agent & Config Checks (2)

Agent manifests — validates all .toml files in ~/.openfang/agents/
Config consistency — checks that api_key_env references in config match actual environment variables

Provider Checks (1)

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)

Channel Checks (1)

Channel tokens — format validation for Telegram, Discord, Slack tokens

Toolchain Checks (1)

Rust toolchain — rustc --version

Examples

openfang doctor

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  OpenFang System Diagnostics
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

System Checks
  ✓ OpenFang directory exists (~/.openfang/)
  ✓ .env file exists with correct permissions (0600)
  ✓ config.toml syntax is valid
  ✓ Daemon is running (http://127.0.0.1:4200)
  ✓ No stale daemon.json

Storage
  ✓ Database file is valid SQLite
  ✓ Disk space: 42.3 GB available

Agent & Config
  ✓ Found 3 valid agent manifests
  ✓ Config references match environment

LLM Providers
  ✓ GROQ_API_KEY is set and valid
  ✓ ANTHROPIC_API_KEY is set and valid
  ⚠ OPENAI_API_KEY is not set
  ⚠ GEMINI_API_KEY is not set

Channels
  ✓ TELEGRAM_BOT_TOKEN is valid
  ⚠ DISCORD_BOT_TOKEN is not set

Toolchain
  ✓ Rust 1.76.0 installed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Status: OK (2 warnings)

Hints:
  • Set additional provider keys with: openfang config set-key <provider>
  • Setup Discord channel with: openfang channel setup discord

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 Output (Daemon Running)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  OpenFang Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Daemon:      Running (http://127.0.0.1:4200)
Uptime:      2h 34m 12s
Provider:    groq
Model:       llama-3.3-70b-versatile
Agents:      3 active
Data Dir:    ~/.openfang/data/

Active Agents:
  • coder (a1b2c3d4-e5f6-...)
  • assistant (b2c3d4e5-f6a7-...)
  • researcher (c3d4e5f6-a7b8-...)

Example Output (No Daemon)

⚠  Daemon is not running

Persisted State:
  Agents:      3 saved
  Provider:    groq
  Model:       llama-3.3-70b-versatile
  Data Dir:    ~/.openfang/data/

Start the daemon with: openfang start

Examples

openfang status

Environment File Format

OpenFang loads ~/.openfang/.env into the process environment on every CLI invocation. System environment variables take priority over .env values.

.env

GROQ_API_KEY=gsk_...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

Manage keys with the config set-key / config delete-key commands rather than editing the file directly. These commands enforce correct permissions (0600 on Unix).

Next Steps

Agent Commands

Spawn and manage agents

Channel Commands

Setup messaging integrations

Skill Commands

Install agent capabilities

CLI Overview

Back to CLI overview

Commands

​Config Commands

​openfang init

​Options

​Behavior

​Created Structure

​File Permissions

​Examples

​openfang config show

​Output

​Example

​openfang config edit

​Behavior

​Examples

​openfang config get

​Arguments

​Examples

​openfang config set

​Arguments

​Examples

​openfang config set-key

​Arguments

​Behavior

​Supported Providers

​Example Session

​Examples

​openfang config delete-key

​Arguments

​Examples

​Output

​openfang config test-key

​Arguments

​Behavior

​Examples

​openfang doctor

​Options

​Checks Performed

​Examples

​Example Output

​openfang status

​Options

​Behavior

​Example Output (Daemon Running)

​Example Output (No Daemon)

​Examples

​Environment File Format

​Next Steps

Agent Commands

Channel Commands

Skill Commands

CLI Overview

Build docs developers (and LLMs) love

Config Commands

openfang init

Options

Behavior

Created Structure

File Permissions

Examples

openfang config show

Output

Example

openfang config edit

Behavior

Examples

openfang config get

Arguments

Examples

openfang config set

Arguments

Examples

openfang config set-key

Arguments

Behavior

Supported Providers

Example Session

Examples

openfang config delete-key

Arguments

Examples

Output

openfang config test-key

Arguments

Behavior

Examples

openfang doctor

Options

Checks Performed

Examples

Example Output

openfang status

Options

Behavior

Example Output (Daemon Running)

Example Output (No Daemon)

Examples

Environment File Format

Next Steps