LibreFang CLI Reference

Sub-pages: Command Reference | Examples & Guides

Complete command-line reference for librefang, the CLI tool for the LibreFang Agent OS.

Overview

The librefang binary is the primary interface for managing the LibreFang Agent OS. It supports two modes of operation:

• Daemon mode -- When a daemon is running (librefang 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 librefang 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)

cargo install --path crates/librefang-cli

Build from workspace

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

Docker

docker run -it librefang/librefang:latest

Homebrew (macOS)

brew tap librefang/tap
brew install librefang              # CLI (stable)
brew install --cask librefang       # Desktop (stable)
# Beta/RC channels:
# brew install librefang-beta       # or librefang-rc
# brew install --cask librefang-rc  # or librefang-beta

Shell installer

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

Global Options

These options apply to all commands.

Environment variables:

Command Reference

librefang (no subcommand)

Launch the interactive TUI dashboard.

librefang [--config <PATH>]

The TUI provides a full-screen terminal interface with panels for agents, chat, workflows, channels, skills, settings, and more. Tracing output is redirected to ~/.librefang/tui.log to avoid corrupting the terminal display.

Press Ctrl+C to exit. A second Ctrl+C force-exits the process.

librefang init

Initialize the LibreFang workspace. Creates ~/.librefang/ with subdirectories (data/, workspaces/agents/) and a default config.toml.

librefang init [--quick]

Options:

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:

# Interactive setup
librefang init

# Non-interactive (CI/scripts)
export GROQ_API_KEY="gsk_..."
librefang init --quick

librefang start

Start the LibreFang daemon (kernel + API server).

librefang start [--config <PATH>]

Auto-initialization: If no config.toml exists in ~/.librefang/, a quick setup wizard runs automatically on the first start command. The wizard walks through provider selection and API key configuration before booting the daemon.

Behavior:

• Checks if a daemon is already running; exits with an error if so.
• Boots the LibreFang 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:4545).
• Writes daemon.json to ~/.librefang/ so other CLI commands can discover the running daemon.
• Blocks until interrupted with Ctrl+C.

Output:

  LibreFang Agent OS v0.7.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:4545
  Dashboard:  http://127.0.0.1:4545/
  Provider:   groq
  Model:      llama-3.3-70b-versatile

  hint: Open the dashboard in your browser, or run `librefang chat`
  hint: Press Ctrl+C to stop the daemon

Example:

# Start with default config
librefang start

# Start with custom config
librefang start --config /path/to/config.toml

librefang status

Show the current kernel/daemon status.

librefang status [--json]

Options:

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:

librefang status

librefang status --json | jq '.agent_count'

librefang doctor

Run diagnostic checks on the LibreFang installation.

librefang doctor [--json] [--repair]

Options:

Checks performed:

1. LibreFang directory -- ~/.librefang/ 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 4545 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 ~/.librefang/workspaces/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:

librefang doctor

librefang doctor --repair

librefang doctor --json

librefang update

Update the CLI binary to the latest release for your configured update channel.

librefang update [--check] [--version <TAG>] [--channel <CHANNEL>]

Options:

Update channels:

LibreFang supports Apple-style update channels. Set a persistent default in config.toml:

update_channel = "stable"   # stable | beta | rc

Examples:

librefang update                    # Install latest for your channel
librefang update --check            # Check for updates only
librefang update --channel rc       # Use rc channel for this update
librefang update --version v0.7.0   # Install a specific version

librefang dashboard

Open the web dashboard in the default browser.

librefang dashboard

Behavior:

• Requires a running daemon.
• Opens the daemon URL (e.g. http://127.0.0.1:4545/) in the system browser.
• Copies the URL to the system clipboard (uses PowerShell on Windows, pbcopy on macOS, xclip/xsel on Linux).

Example:

librefang dashboard

librefang completion

Generate shell completion scripts.

librefang completion <SHELL>

Arguments:

Example:

# Bash
librefang completion bash > ~/.bash_completion.d/librefang

# Zsh
librefang completion zsh > ~/.zfunc/_librefang

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

# PowerShell
librefang completion powershell > librefang.ps1

For detailed command references for agents, hands, workflows, triggers, skills, channels, and config, see CLI Command Reference.

Quick Chat

librefang chat

Quick alias for starting a chat session.

librefang chat [<AGENT>]

Arguments:

Behavior:

• Daemon mode: Finds the agent by name or ID among running agents. If no agent name is given, uses the first available agent. If no agents exist, suggests librefang agent new.
• Standalone mode (no daemon): Boots an in-process kernel and auto-spawns an agent from templates. Searches for an agent matching the given name, then falls back to assistant, then to the first available template.
• Auto-initialization: If no config.toml exists in ~/.librefang/, a quick setup wizard runs automatically before starting the chat session.

This is the simplest way to start chatting -- it works with or without a daemon.

Example:

# Chat with the default agent
librefang chat

# Chat with a specific agent by name
librefang chat coder

# Chat with a specific agent by UUID
librefang chat a1b2c3d4-e5f6-7890-abcd-ef1234567890

Daemon Auto-Detect

The CLI uses a two-step mechanism to detect a running daemon:

1. Read daemon.json: On startup, the daemon writes ~/.librefang/daemon.json containing the listen address (e.g. 127.0.0.1:4545). The CLI reads this file to learn where the daemon is.

2. Health check: The CLI sends GET http://<listen_addr>/api/health with a 2-second timeout. If the health check succeeds, the daemon is considered running and the CLI uses HTTP to communicate with it.

If either step fails (no daemon.json, stale file, health check timeout), the CLI falls back to in-process mode for commands that support it. Commands that require a daemon (workflows, triggers, channel test/enable/disable, dashboard) will exit with an error and a helpful message.

Daemon lifecycle:

librefang start          # Starts daemon, writes daemon.json
                        # Other CLI instances detect daemon.json
librefang status         # Connects to daemon via HTTP
Ctrl+C                  # Daemon shuts down, daemon.json removed

librefang doctor --repair  # Cleans up stale daemon.json from crashes

Environment File

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

The .env file stores API keys and secrets:

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, as these commands enforce correct permissions.

Exit Codes

For usage examples, migration guides, and MCP integration instructions, see CLI Examples & Guides.

Supported LLM Providers

The following providers are recognized by librefang config set-key and librefang doctor:

Additional search/fetch provider keys: BRAVE_API_KEY, TAVILY_API_KEY.