LibreFang CLI Reference

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

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/, 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>]

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:4200).
• 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.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 `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 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 ~/.librefang/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 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:4200/) 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

Agent Commands

librefang agent new

Spawn an agent from a built-in template.

librefang agent new [<TEMPLATE>]

Arguments:

Behavior:

• Templates are discovered from: the repo agents/ directory (dev builds), ~/.librefang/agents/ (installed), and LIBREFANG_AGENTS_DIR (env override).
• Each template is a directory containing an agent.toml manifest.
• In daemon mode: sends POST /api/agents with the manifest. Agent is persistent.
• In standalone mode: boots an in-process kernel. Agent is ephemeral.

Example:

# Interactive picker
librefang agent new

# Spawn by name
librefang agent new coder

# Spawn the assistant template
librefang agent new assistant

librefang agent spawn

Spawn an agent from a custom manifest file.

librefang agent spawn <MANIFEST>

Arguments:

Behavior:

• Reads and parses the TOML manifest file.
• In daemon mode: sends the raw TOML to POST /api/agents.
• In standalone mode: boots an in-process kernel and spawns the agent locally.

Example:

librefang agent spawn ./my-agent/agent.toml

librefang agent list

List all running agents.

librefang agent list [--json]

Options:

Output columns: ID, NAME, STATE, PROVIDER, MODEL (daemon mode) or ID, NAME, STATE, CREATED (in-process mode).

Example:

librefang agent list

librefang agent list --json | jq '.[].name'

librefang agent chat

Start an interactive chat session with a specific agent.

librefang agent chat <AGENT_ID>

Arguments:

Behavior:

• Opens a REPL-style chat loop.
• Type messages at the you> prompt.
• Agent responses display at the agent> prompt, followed by token usage and iteration count.
• Type exit, quit, or press Ctrl+C to end the session.

Example:

librefang agent chat a1b2c3d4-e5f6-7890-abcd-ef1234567890

librefang agent kill

Terminate a running agent.

librefang agent kill <AGENT_ID>

Arguments:

Example:

librefang agent kill a1b2c3d4-e5f6-7890-abcd-ef1234567890

Workflow Commands

All workflow commands require a running daemon.

librefang workflow list

List all registered workflows.

librefang workflow list

Output columns: ID, NAME, STEPS, CREATED.

librefang workflow create

Create a workflow from a JSON definition file.

librefang workflow create <FILE>

Arguments:

Example:

librefang workflow create ./my-workflow.json

librefang workflow run

Execute a workflow by ID.

librefang workflow run <WORKFLOW_ID> <INPUT>

Arguments:

Example:

librefang workflow run abc123 "Analyze this code for security issues"

Trigger Commands

All trigger commands require a running daemon.

librefang trigger list

List all event triggers.

librefang trigger list [--agent-id <ID>]

Options:

Output columns: TRIGGER ID, AGENT ID, ENABLED, FIRES, PATTERN.

librefang trigger create

Create an event trigger for an agent.

librefang trigger create <AGENT_ID> <PATTERN_JSON> [--prompt <TEMPLATE>] [--max-fires <N>]

Arguments:

Options:

Pattern examples:

# Fire on any lifecycle event
librefang trigger create <AGENT_ID> '{"lifecycle":{}}'

# Fire when a specific agent is spawned
librefang trigger create <AGENT_ID> '{"agent_spawned":{"name_pattern":"*"}}'

# Fire on agent termination
librefang trigger create <AGENT_ID> '{"agent_terminated":{}}'

# Fire on all events (limited to 10 fires)
librefang trigger create <AGENT_ID> '{"all":{}}' --max-fires 10

librefang trigger delete

Delete a trigger by ID.

librefang trigger delete <TRIGGER_ID>

Arguments:

Skill Commands

librefang skill list

List all installed skills.

librefang skill list

Output columns: NAME, VERSION, TOOLS, DESCRIPTION.

Loads skills from ~/.librefang/skills/ plus bundled skills compiled into the binary.

librefang skill install

Install a skill from a local directory, git URL, or FangHub marketplace.

librefang skill install <SOURCE>

Arguments:

Behavior:

• Local directory: Looks for skill.toml in the directory. If not found, checks for OpenClaw-format skills (SKILL.md with YAML frontmatter) and auto-converts them.
• Remote (FangHub): Fetches and installs from the FangHub marketplace. Skills pass through SHA256 verification and prompt injection scanning.

Example:

# Install from local directory
librefang skill install ./my-skill/

# Install from FangHub
librefang skill install web-search

# Install an OpenClaw-format skill
librefang skill install ./openclaw-skill/

librefang skill remove

Remove an installed skill.

librefang skill remove <NAME>

Arguments:

Example:

librefang skill remove web-search

librefang skill search

Search the FangHub marketplace for skills.

librefang skill search <QUERY>

Arguments:

Example:

librefang skill search "docker kubernetes"

librefang skill create

Interactively scaffold a new skill project.

librefang skill create

Behavior:

Prompts for:

• Skill name
• Description
• Runtime (python, node, or wasm; defaults to python)

Creates a directory under ~/.librefang/skills/<name>/ with:

• skill.toml -- manifest file
• src/main.py (or src/index.js) -- entry point with boilerplate

Example:

librefang skill create
# Skill name: my-tool
# Description: A custom analysis tool
# Runtime (python/node/wasm) [python]: python

Channel Commands

librefang channel list

List configured channels and their status.

librefang channel list

Output columns: CHANNEL, ENV VAR, STATUS.

Checks config.toml for channel configuration sections and environment variables for required tokens. Status is one of: Ready, Missing env, Not configured.

Channels checked: webchat, telegram, discord, slack, whatsapp, signal, matrix, email.

librefang channel setup

Interactive setup wizard for a channel integration.

librefang channel setup [<CHANNEL>]

Arguments:

Supported channels: telegram, discord, slack, whatsapp, email, signal, matrix.

Each wizard:

1. Displays step-by-step instructions for obtaining credentials.
2. Prompts for tokens/credentials.
3. Saves tokens to ~/.librefang/.env with owner-only permissions.
4. Appends the channel configuration block to config.toml (prompts for confirmation).
5. Warns to restart the daemon if one is running.

Example:

# Interactive picker
librefang channel setup

# Direct setup
librefang channel setup telegram
librefang channel setup discord
librefang channel setup slack

librefang channel test

Send a test message through a configured channel.

librefang channel test <CHANNEL>

Arguments:

Requires a running daemon. Sends POST /api/channels/<channel>/test.

Example:

librefang channel test telegram

librefang channel enable

Enable a channel integration.

librefang channel enable <CHANNEL>

Arguments:

In daemon mode: sends POST /api/channels/<channel>/enable. Without a daemon: prints a note that the change will take effect on next start.

librefang channel disable

Disable a channel without removing its configuration.

librefang channel disable <CHANNEL>

Arguments:

In daemon mode: sends POST /api/channels/<channel>/disable. Without a daemon: prints a note to edit config.toml.

Config Commands

librefang config show

Display the current configuration file.

librefang config show

Prints the contents of ~/.librefang/config.toml with the file path as a header comment.

librefang config edit

Open the configuration file in your editor.

librefang config edit

Uses $EDITOR, then $VISUAL, then falls back to notepad (Windows) or vi (Unix).

librefang config get

Get a single configuration value by dotted key path.

librefang config get <KEY>

Arguments:

Example:

librefang config get default_model.provider
# groq

librefang config get api_listen
# 127.0.0.1:4200

librefang config get memory.decay_rate
# 0.05

librefang config set

Set a configuration value by dotted key path.

librefang config set <KEY> <VALUE>

Arguments:

Warning: This command re-serializes the TOML file, which strips all comments.

Example:

librefang config set default_model.provider anthropic
librefang config set default_model.model claude-sonnet-4-20250514
librefang config set api_listen "0.0.0.0:4200"

librefang config set-key

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

librefang config set-key <PROVIDER>

Arguments:

Behavior:

• Prompts interactively for the API key.
• Saves to ~/.librefang/.env as <PROVIDER_NAME>_API_KEY=<value>.
• Runs a live validation test against the provider's API.
• File permissions are restricted to owner-only on Unix.

Example:

librefang config set-key groq
# Paste your groq API key: gsk_...
# [ok] Saved GROQ_API_KEY to ~/.librefang/.env
# Testing key... OK

librefang config delete-key

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

librefang config delete-key <PROVIDER>

Arguments:

Example:

librefang config delete-key openai

librefang config test-key

Test provider connectivity with the stored API key.

librefang config test-key <PROVIDER>

Arguments:

Behavior:

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

Example:

librefang config test-key groq
# Testing groq (GROQ_API_KEY)... OK

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.

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

Migration

librefang migrate

Migrate configuration and agents from another agent framework.

librefang migrate --from <FRAMEWORK> [--source-dir <PATH>] [--dry-run]

Options:

Behavior:

• Converts agent configurations, YAML manifests, and settings from the source framework into LibreFang format.
• Saves imported data to ~/.librefang/.
• Writes a migration_report.md summarizing what was imported.

Example:

# Dry run migration from OpenClaw
librefang migrate --from openclaw --dry-run

# Migrate from OpenClaw (auto-detect source)
librefang migrate --from openclaw

# Migrate from LangChain with explicit source
librefang migrate --from langchain --source-dir /home/user/.langchain

# Migrate from AutoGPT
librefang migrate --from autogpt

MCP Server

librefang mcp

Start an MCP (Model Context Protocol) server over stdio.

librefang mcp

Behavior:

• Exposes running LibreFang agents as MCP tools via JSON-RPC 2.0 over stdin/stdout with Content-Length framing.
• Each agent becomes a callable tool named librefang_agent_<name> (hyphens replaced with underscores).
• Connects to a running daemon via HTTP if available; otherwise boots an in-process kernel.
• Protocol version: 2024-11-05.
• Maximum message size: 10MB (security limit).

Supported MCP methods:

Tool input schema:

Each agent tool accepts a single message (string) argument.

Integration with Claude Desktop / other MCP clients:

Add to your MCP client configuration:

{
  "mcpServers": {
    "librefang": {
      "command": "librefang",
      "args": ["mcp"]
    }
  }
}

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:4200). 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

Examples

First-time setup

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

# 2. Initialize LibreFang
librefang init --quick

# 3. Start the daemon
librefang start

Daily usage

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

# Chat with a specific agent
librefang chat coder

# Check what's running
librefang status

# Open the web dashboard
librefang dashboard

Agent management

# Spawn from a template
librefang agent new assistant

# Spawn from a custom manifest
librefang agent spawn ./agents/custom-agent/agent.toml

# List running agents
librefang agent list

# Chat with an agent by UUID
librefang agent chat <UUID>

# Kill an agent
librefang agent kill <UUID>

Workflow automation

# Create a workflow
librefang workflow create ./review-pipeline.json

# List workflows
librefang workflow list

# Run a workflow
librefang workflow run <WORKFLOW_ID> "Review the latest PR"

Event triggers

# Create a trigger that fires on agent spawn
librefang trigger create <AGENT_ID> '{"agent_spawned":{"name_pattern":"*"}}' \
  --prompt "New agent spawned: {{event}}" \
  --max-fires 100

# List all triggers
librefang trigger list

# List triggers for a specific agent
librefang trigger list --agent-id <AGENT_ID>

# Delete a trigger
librefang trigger delete <TRIGGER_ID>

Skill management

# Search FangHub
librefang skill search "code review"

# Install a skill
librefang skill install code-reviewer

# List installed skills
librefang skill list

# Create a new skill
librefang skill create

# Remove a skill
librefang skill remove code-reviewer

Channel setup

# Interactive channel picker
librefang channel setup

# Direct channel setup
librefang channel setup telegram

# Check channel status
librefang channel list

# Test a channel
librefang channel test telegram

# Enable/disable channels
librefang channel enable discord
librefang channel disable slack

Configuration

# View config
librefang config show

# Get a specific value
librefang config get default_model.provider

# Change provider
librefang config set default_model.provider anthropic
librefang config set default_model.model claude-sonnet-4-20250514
librefang config set default_model.api_key_env ANTHROPIC_API_KEY

# Manage API keys
librefang config set-key anthropic
librefang config test-key anthropic
librefang config delete-key openai

# Open in editor
librefang config edit

Migration from other frameworks

# Preview migration
librefang migrate --from openclaw --dry-run

# Run migration
librefang migrate --from openclaw

# Migrate from LangChain
librefang migrate --from langchain --source-dir ~/.langchain

MCP integration

# Start MCP server for Claude Desktop or other MCP clients
librefang mcp

Diagnostics

# Run all diagnostic checks
librefang doctor

# Auto-repair issues
librefang doctor --repair

# Machine-readable diagnostics
librefang doctor --json

Shell completions

# Generate and install completions for your shell
librefang completion bash >> ~/.bashrc
librefang completion zsh > "${fpath[1]}/_librefang"
librefang completion fish > ~/.config/fish/completions/librefang.fish

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.