# LibreFang CLI Reference

> **Sub-pages:** [Command Reference](/integrations/cli/commands) | [Examples & Guides](/integrations/cli/examples)

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)

```bash
cargo install --path crates/librefang-cli
```

### Build from workspace

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

### Docker

```bash
docker run -it librefang/librefang:latest
```

### Homebrew (macOS)

```bash
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

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

## Global Options

These options apply to all commands.

| Option | Description |
|---|---|
| `--config <PATH>` | Path to a custom config file. Overrides the default `~/.librefang/config.toml`. |
| `--help` | Print help information for any command or subcommand. |
| `--version` | Print the version of the `librefang` binary. |

**Environment variables:**

| Variable | Description |
|---|---|
| `RUST_LOG` | Controls log verbosity (e.g. `info`, `debug`, `librefang_kernel=trace`). |
| `LIBREFANG_AGENTS_DIR` | Override the agent templates directory. |
| `EDITOR` / `VISUAL` | Editor used by `librefang config edit`. Falls back to `notepad` (Windows) or `vi` (Unix). |

---

## 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:**

| Option | Description |
|---|---|
| `--quick` | Skip interactive prompts. Auto-detects the best available LLM provider and writes config immediately. Suitable for CI/scripts. |

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

```bash
# 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:**

```bash
# 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:**

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

```bash
librefang status

librefang status --json | jq '.agent_count'
```

---

### librefang doctor

Run diagnostic checks on the LibreFang installation.

```
librefang 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:**

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

```bash
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:**

| Option | Description |
|---|---|
| `--check` | Check whether a newer release exists without installing it. |
| `--version <TAG>` | Install a specific GitHub release tag (e.g. `v2026.3.2407`). |
| `--channel <CHANNEL>` | Override the update channel for this invocation (`stable`, `beta`, or `rc`). |

**Update channels:**

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

```toml
update_channel = "stable"   # stable | beta | rc
```

| Channel | Receives |
|---|---|
| `stable` | Stable releases only (default) |
| `beta` | Stable + beta releases |
| `rc` | All releases including release candidates |

**Examples:**

```bash
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:**

```bash
librefang dashboard
```

---

### librefang completion

Generate shell completion scripts.

```
librefang completion <SHELL>
```

**Arguments:**

| Argument | Description |
|---|---|
| `<SHELL>` | Target shell. One of: `bash`, `zsh`, `fish`, `elvish`, `powershell`. |

**Example:**

```bash
# 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](/integrations/cli/commands)**.

---

## Quick Chat

### librefang chat

Quick alias for starting a chat session.

```
librefang chat [<AGENT>]
```

**Arguments:**

| Argument | Description |
|---|---|
| `<AGENT>` | Optional agent name or UUID. |

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

```bash
# 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:

```bash
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

| Code | Meaning |
|---|---|
| `0` | Success. |
| `1` | General error (invalid arguments, failed operations, missing daemon, parse errors, spawn failures). |
| `130` | Interrupted by second `Ctrl+C` (force exit). |

---

For usage examples, migration guides, and MCP integration instructions, see **[CLI Examples & Guides](/integrations/cli/examples)**.

---

## Supported LLM Providers

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

| Provider | Environment Variable | Default Model |
|---|---|---|
| Groq | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
| Gemini | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | `gemini-2.5-flash` |
| DeepSeek | `DEEPSEEK_API_KEY` | `deepseek-chat` |
| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
| OpenAI | `OPENAI_API_KEY` | `gpt-4o` |
| OpenRouter | `OPENROUTER_API_KEY` | `openrouter/google/gemini-2.5-flash` |
| 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 provider keys: `BRAVE_API_KEY`, `TAVILY_API_KEY`.
