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 Quick Reference

Core Commands

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>] [--tail | --foreground]

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 the configured LibreFang home directory so other CLI commands can discover the running daemon.
• Launches the daemon in the background by default and returns after the health endpoint responds.
• Writes daemon startup output to ~/.librefang/logs/daemon.log.
• If --tail is passed, follows ~/.librefang/logs/daemon.log after launch. Ctrl+C stops tailing only; the daemon keeps running.
• If --foreground is passed, keeps the daemon attached to the current terminal and streams logs to stdout/stderr. Use this for Docker, systemd, or other process supervisors.

Options:

Output:

  [ok] Daemon started in background

  PID:        42431
  API:        http://127.0.0.1:4545
  Dashboard:  http://127.0.0.1:4545/
  Log:        /Users/alice/.librefang/logs/daemon.log

  hint: Use `librefang stop` to stop the daemon

Example:

# Start with default config
librefang start

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

# Start and follow daemon logs
librefang start --tail

# Start in the foreground for Docker/systemd
librefang start --foreground

librefang stop

Stop the running daemon.

librefang stop

Behavior:

• Sends a shutdown request to the running daemon.
• Exits with an error if no daemon is running.

Example:

librefang stop

librefang restart

Restart the LibreFang daemon.

librefang restart [--config <PATH>] [--tail | --foreground]

Behavior:

• If a daemon is running, sends a shutdown request and waits for it to stop.
• Starts the daemon again using the same startup flow as librefang start.
• If no daemon is running, behaves like librefang start and prints a hint.

Options:

Example:

librefang restart

librefang restart --tail

librefang restart --foreground

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 health

Quick daemon health check.

librefang health [--json]

Options:

Behavior:

• Checks if the daemon is running and responsive.
• Returns health status information.

Example:

librefang health

librefang health --json

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/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: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 tui

Launch the interactive terminal dashboard.

librefang tui

Behavior:

• Opens the same ratatui-based TUI as running librefang with no subcommand.
• Provides a full-screen terminal interface with panels for agents, chat, workflows, channels, skills, and settings.

Example:

librefang tui

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

librefang message

Send a one-shot message to an agent and print the response.

librefang message <AGENT> <TEXT> [--json]

Arguments:

Options:

Example:

librefang message coder "Explain this error: cannot borrow as mutable"

librefang message assistant "Summarize today's news" --json

librefang logs

Tail the LibreFang daemon log file.

librefang logs [--lines <N>] [--follow]

Options:

Example:

# Show last 50 lines
librefang logs

# Show last 200 lines and follow
librefang logs --lines 200 --follow

librefang sessions

List conversation sessions.

librefang sessions [<AGENT>] [--json]

Arguments:

Options:

Example:

librefang sessions

librefang sessions coder --json

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

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"]
    }
  }
}

Agent Management

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> [--name <NAME>] [--dry-run]

Arguments:

Options:

Example:

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

librefang agent spawn ./my-agent/agent.toml --name my-custom-agent --dry-run

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

librefang agent set

Set an agent property (e.g., model).

librefang agent set <AGENT_ID> <FIELD> <VALUE>

Arguments:

Example:

librefang agent set a1b2c3d4 model gpt-4o

Top-level agent aliases

These are convenience aliases for common agent commands:

# Spawn an agent (alias for `agent new`)
librefang spawn [<TARGET>] [--template <PATH>] [--name <NAME>] [--dry-run]

# List running agents (alias for `agent list`)
librefang agents [--json]

# Kill an agent (alias for `agent kill`)
librefang kill <AGENT_ID>

Workflow & Automation

librefang workflow list

List all registered workflows. Requires a running daemon.

librefang workflow list

Output columns: ID, NAME, STEPS, CREATED.

librefang workflow create

Create a workflow from a JSON definition file. Requires a running daemon.

librefang workflow create <FILE>

Arguments:

Example:

librefang workflow create ./my-workflow.json

librefang workflow run

Execute a workflow by ID. Requires a running daemon.

librefang workflow run <WORKFLOW_ID> <INPUT>

Arguments:

Example:

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

librefang trigger list

List all event triggers. Requires a running daemon.

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. Requires a running daemon.

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. Requires a running daemon.

librefang trigger delete <TRIGGER_ID>

Arguments:

librefang cron list

List scheduled jobs.

librefang cron list [--json]

Options:

librefang cron create

Create a new scheduled job.

librefang cron create <AGENT> <SPEC> <PROMPT> [--name <NAME>]

Arguments:

Options:

Example:

librefang cron create researcher "0 9 * * *" "Summarize today's AI news" --name daily-news

librefang cron delete

Delete a scheduled job.

librefang cron delete <ID>

Arguments:

librefang cron enable

Enable a disabled job.

librefang cron enable <ID>

librefang cron disable

Disable a job without deleting it.

librefang cron disable <ID>

librefang approvals list

List pending execution approvals.

librefang approvals list [--json]

Options:

librefang approvals approve

Approve a pending execution request.

librefang approvals approve <ID>

Arguments:

librefang approvals reject

Reject a pending execution request.

librefang approvals reject <ID>

Arguments:

Skills & Tools

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 test

Validate a local skill and optionally execute one tool.

librefang skill test [<PATH>] [--tool <NAME>] [--input <JSON>]

Arguments:

Options:

Behavior:

• Validates the manifest and runtime entrypoint.
• Runs security and prompt-injection scans.
• Executes the selected tool for Python, Node.js, and prompt-only skills when possible.

Example:

librefang skill test ./my-skill --tool summarize_url --input '{"url":"https://example.com"}'

librefang skill publish

Package a local skill and publish it to a FangHub GitHub release.

librefang skill publish [<PATH>] [--repo <OWNER/NAME>] [--tag <TAG>] [--output <DIR>] [--dry-run]

Arguments:

Options:

Behavior:

• Validates the skill locally before packaging.
• Builds a zip bundle suitable for FangHub distribution.
• Uploads the bundle to the selected GitHub release when GITHUB_TOKEN or GH_TOKEN is configured.

Example:

librefang skill publish ./my-skill --dry-run
librefang skill publish ./my-skill --repo librefang-skills/my-skill

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

librefang hand list

List all available hands.

librefang hand list

librefang hand active

Show currently active hand instances.

librefang hand active

librefang hand status

Show active status for a hand or hand instance.

librefang hand status [<ID>]

Arguments:

librefang hand install

Install a hand from a local directory containing HAND.toml.

librefang hand install <PATH>

Arguments:

librefang hand activate

Activate a hand by ID.

librefang hand activate <ID>

Arguments:

librefang hand deactivate

Deactivate an active hand by hand ID.

librefang hand deactivate <ID>

librefang hand info

Show detailed info about a hand.

librefang hand info <ID>

librefang hand check-deps

Check dependency status for a hand.

librefang hand check-deps <ID>

librefang hand install-deps

Install missing dependencies for a hand.

librefang hand install-deps <ID>

librefang hand pause

Pause a running hand by hand ID or instance ID.

librefang hand pause <ID>

librefang hand resume

Resume a paused hand by hand ID or instance ID.

librefang hand resume <ID>

Models

librefang models list

List available models, optionally filtered by provider.

librefang models list [--provider <NAME>] [--json]

Options:

Example:

librefang models list

librefang models list --provider groq

librefang models list --json

librefang models aliases

Show model aliases (shorthand names).

librefang models aliases [--json]

Options:

Example:

librefang models aliases

librefang models providers

List known LLM providers and their auth status.

librefang models providers [--json]

Options:

Example:

librefang models providers

librefang models set

Set the default model for the daemon.

librefang models set [<MODEL>]

Arguments:

Example:

librefang models set gpt-4o

# Interactive picker
librefang models set

Channels

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. Requires a running daemon.

librefang channel test <CHANNEL>

Arguments:

Example:

librefang channel test telegram

librefang channel enable

Enable a channel integration.

librefang channel enable <CHANNEL>

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>

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

Integrations

librefang integrations

List or search available integrations.

librefang integrations [<QUERY>]

Arguments:

Example:

librefang integrations

librefang integrations github

librefang add

Add an integration (one-click MCP server setup).

librefang add <NAME> [--key <TOKEN>]

Arguments:

Options:

Example:

librefang add github

librefang add slack --key xoxb-...

librefang remove

Remove an installed integration.

librefang remove <NAME>

Arguments:

Example:

librefang remove github

Configuration

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:4545

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:4545"

librefang config unset

Remove a config key from the configuration file.

librefang config unset <KEY>

Arguments:

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

Example:

librefang config unset api.cors_origin

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

Security

librefang security status

Show security status summary.

librefang security status [--json]

Options:

librefang security audit

Show recent audit trail entries.

librefang security audit [--limit <N>] [--json]

Options:

librefang security verify

Verify audit trail integrity (Merkle chain).

librefang security verify

librefang vault init

Initialize the credential vault.

librefang vault init

librefang vault set

Store a credential in the vault.

librefang vault set <KEY>

Arguments:

librefang vault list

List all keys in the vault (values are hidden).

librefang vault list

librefang vault remove

Remove a credential from the vault.

librefang vault remove <KEY>

Arguments:

librefang auth chatgpt

Authenticate with ChatGPT (browser-based session token flow).

librefang auth chatgpt

Memory & Devices

librefang memory list

List KV pairs for an agent.

librefang memory list <AGENT> [--json]

Arguments:

Options:

librefang memory get

Get a specific KV value.

librefang memory get <AGENT> <KEY> [--json]

Arguments:

Options:

librefang memory set

Set a KV value.

librefang memory set <AGENT> <KEY> <VALUE>

Arguments:

librefang memory delete

Delete a KV pair.

librefang memory delete <AGENT> <KEY>

Arguments:

librefang devices list

List paired devices.

librefang devices list [--json]

Options:

librefang devices pair

Start a new device pairing flow.

librefang devices pair

librefang devices remove

Remove a paired device.

librefang devices remove <ID>

Arguments:

librefang qr

Generate a QR code for device pairing.

librefang qr

librefang webhooks list

List configured webhooks.

librefang webhooks list [--json]

Options:

librefang webhooks create

Create a new webhook trigger.

librefang webhooks create <AGENT> <URL>

Arguments:

librefang webhooks delete

Delete a webhook.

librefang webhooks delete <ID>

Arguments:

librefang webhooks test

Send a test payload to a webhook.

librefang webhooks test <ID>

Arguments:

Advanced

librefang update

Update the CLI to the latest published release.

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

Options:

Example:

# Update to latest
librefang update

# Check for updates
librefang update --check

# Install specific version
librefang update --version v0.5.0

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

librefang onboard

Interactive onboarding wizard.

librefang onboard [--quick]

Options:

librefang setup

Quick non-interactive initialization.

librefang setup [--quick]

Options:

librefang configure

Interactive setup wizard for credentials and channels.

librefang configure

librefang new

Scaffold a new skill or integration template.

librefang new <KIND>

Arguments:

Example:

librefang new skill

librefang new integration

librefang system info

Show detailed system info.

librefang system info [--json]

Options:

librefang system version

Show version information.

librefang system version [--json]

Options:

librefang gateway

Daemon control (alias for start/stop/restart/status).

librefang gateway start [--tail] [--foreground]
librefang gateway restart [--tail] [--foreground]
librefang gateway stop
librefang gateway status [--json]

The gateway subcommand provides an alternate interface for daemon lifecycle management, equivalent to the top-level start, stop, restart, and status commands.

librefang reset

Reset local config and state.

librefang reset [--confirm]

Options:

librefang uninstall

Completely remove LibreFang from your system.

librefang uninstall [--confirm] [--keep-config]

Options:

Example:

librefang uninstall

librefang uninstall --confirm --keep-config

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

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

# Send a one-shot message
librefang message assistant "Summarize this paragraph"

# Check what's running
librefang status

# Open the web dashboard
librefang dashboard

# Launch the TUI
librefang tui

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>

# Change an agent's model
librefang agent set <UUID> model gpt-4o

# Kill an agent
librefang agent kill <UUID>

Model management

# List all available models
librefang models list

# List models from a specific provider
librefang models list --provider anthropic

# Show model aliases
librefang models aliases

# Check provider status
librefang models providers

# Set default model
librefang models set claude-sonnet

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"

Cron jobs

# Schedule a daily news summary
librefang cron create researcher "0 9 * * *" "Summarize AI news" --name daily-news

# List jobs
librefang cron list

# Disable a job
librefang cron disable <JOB_ID>

# Re-enable a job
librefang cron enable <JOB_ID>

# Delete a job
librefang cron delete <JOB_ID>

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

# Publish a skill
librefang skill publish ./my-skill --dry-run

# Remove a skill
librefang skill remove code-reviewer

Hand management

# List available hands
librefang hand list

# Show active hands
librefang hand active

# Activate a hand
librefang hand activate researcher

# Check hand dependencies
librefang hand check-deps researcher

# Install missing deps
librefang hand install-deps researcher

# Pause/resume a hand
librefang hand pause researcher
librefang hand resume researcher

# Deactivate a hand
librefang hand deactivate researcher

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

Integrations

# Browse integrations
librefang integrations

# Search for an integration
librefang integrations github

# Install an integration
librefang add github --key ghp_...

# Remove an integration
librefang remove github

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

# Remove a config key
librefang config unset api.cors_origin

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

# Open in editor
librefang config edit

Security & vault

# Security overview
librefang security status

# View audit trail
librefang security audit --limit 50

# Verify audit integrity
librefang security verify

# Initialize vault
librefang vault init

# Store a credential
librefang vault set GITHUB_TOKEN

# List vault keys
librefang vault list

# Remove a credential
librefang vault remove GITHUB_TOKEN

Memory

# List agent memory
librefang memory list coder

# Get a specific value
librefang memory get coder preferred_language

# Set a value
librefang memory set coder preferred_language rust

# Delete a value
librefang memory delete coder preferred_language

Devices & webhooks

# List paired devices
librefang devices list

# Pair a new device
librefang devices pair

# Generate QR code for pairing
librefang qr

# Create a webhook
librefang webhooks create coder https://example.com/hook

# Test a webhook
librefang webhooks test <WEBHOOK_ID>

# Delete a webhook
librefang webhooks delete <WEBHOOK_ID>

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

Self-update & system

# Check for updates
librefang update --check

# Update to latest
librefang update

# System info
librefang system info

# Version
librefang system version

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.