# LibreFang CLI 参考

> **子页面：** [命令参考](/zh/integrations/cli/commands) | [示例与指南](/zh/integrations/cli/examples)

`librefang` 命令行工具的完整参考，用于管理 LibreFang Agent OS。

## 概述

`librefang` 二进制是管理 LibreFang Agent OS 的主要接口。支持两种操作模式：

- **守护进程模式** -- 当守护进程运行时（`librefang start`），CLI 命令通过 HTTP 与其通信。推荐在生产环境中使用此模式。
- **进程内模式** -- 未检测到守护进程时，支持此模式的命令将启动临时进程内核。在此模式下生成的 Agent 不会持久化，进程退出后即丢失。

不带子命令运行 `librefang` 将启动基于 ratatui 构建的交互式 TUI（终端用户界面），在终端中提供完整的仪表板体验。

## 安装

### 从源码 (cargo)

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

### 从工作空间构建

```bash
cargo build --release -p librefang-cli
# 二进制文件: target/release/librefang (Windows 上为 librefang.exe)
```

### 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 频道:
# brew install librefang-beta       # or librefang-rc
# brew install --cask librefang-rc  # or librefang-beta
```

### Shell 安装脚本

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

## 全局选项

以下选项适用于所有命令。

| 选项 | 说明 |
|---|---|
| `--config <PATH>` | 自定义配置文件路径。覆盖默认的 `~/.librefang/config.toml`。 |
| `--help` | 打印任意命令或子命令的帮助信息。 |
| `--version` | 打印 `librefang` 二进制文件的版本号。 |

**环境变量：**

| 变量 | 说明 |
|---|---|
| `RUST_LOG` | 控制日志级别（如 `info`、`debug`、`librefang_kernel=trace`）。 |
| `LIBREFANG_AGENTS_DIR` | 覆盖 Agent 模板目录。 |
| `EDITOR` / `VISUAL` | `librefang config edit` 使用的编辑器。回退到 `notepad`（Windows）或 `vi`（Unix）。 |

---

## 命令参考

### librefang（无子命令）

启动交互式 TUI 仪表板。

```
librefang [--config <PATH>]
```

TUI 提供全屏终端界面，包含 Agent、聊天、工作流、通道、技能、设置等面板。追踪输出重定向到 `~/.librefang/tui.log`，以避免破坏终端显示。

按 `Ctrl+C` 退出。再次按 `Ctrl+C` 强制退出进程。

---

### librefang init

初始化 LibreFang 工作空间。创建 `~/.librefang/` 目录，包含子目录（`data/`、`workspaces/agents/`）和默认的 `config.toml`。

```
librefang init [--quick]
```

**选项：**

| 选项 | 说明 |
|---|---|
| `--quick` | 跳过交互式提示。自动检测最佳可用 LLM 提供商并立即写入配置。适用于 CI/脚本环境。 |

**行为：**

- 不带 `--quick`：启动交互式五步引导向导（ratatui TUI），引导完成提供商选择、API 密钥配置，并可选择启动守护进程。
- 带 `--quick`：按优先级检查环境变量自动检测提供商：Groq、Gemini、DeepSeek、Anthropic、OpenAI、OpenRouter。如果未找到任何提供商，回退到 Groq。
- 在 Unix 系统上，文件权限限制为仅所有者访问（文件 `0600`，目录 `0700`）。

**示例：**

```bash
# 交互式设置
librefang init

# 非交互式（CI/脚本）
export GROQ_API_KEY="gsk_..."
librefang init --quick
```

---

### librefang start

启动 LibreFang 守护进程（内核 + API 服务器）。

```
librefang start [--config <PATH>]
```

**行为：**

- 如果 `~/.librefang/` 中不存在 `config.toml`，首次运行 `start` 命令时会自动执行快速初始化向导。
- 检查是否已有守护进程在运行；如果有，则报错退出。
- 启动 LibreFang 内核（加载配置、初始化 SQLite 数据库、加载 Agent、连接 MCP 服务器、启动后台任务）。
- 在 `config.toml` 指定的地址启动 HTTP API 服务器（默认：`127.0.0.1:4545`）。
- 将 `daemon.json` 写入 `~/.librefang/`，以便其他 CLI 命令发现正在运行的守护进程。
- 阻塞运行，直到通过 `Ctrl+C` 中断。

**输出：**

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

**示例：**

```bash
# 使用默认配置启动
librefang start

# 使用自定义配置启动
librefang start --config /path/to/config.toml
```

---

### librefang status

显示当前内核/守护进程状态。

```
librefang status [--json]
```

**选项：**

| 选项 | 说明 |
|---|---|
| `--json` | 输出机器可读的 JSON 格式，便于脚本处理。 |

**行为：**

- 如果守护进程正在运行：查询 `GET /api/status`，显示 Agent 数量、提供商、模型、运行时间、API 地址、数据目录以及活跃 Agent 列表。
- 如果没有守护进程运行：启动进程内核并显示持久化状态。显示守护进程未运行的警告。

**示例：**

```bash
librefang status

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

---

### librefang doctor

对 LibreFang 安装进行诊断检查。

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

**选项：**

| 选项 | 说明 |
|---|---|
| `--json` | 以 JSON 格式输出结果，便于脚本处理。 |
| `--repair` | 尝试自动修复问题（创建缺失目录、配置文件，删除过期文件）。每次修复前会提示确认。 |

**执行的检查项：**

1. **LibreFang 目录** -- `~/.librefang/` 是否存在
2. **.env 文件** -- 是否存在且权限正确（Unix 上为 0600）
3. **配置 TOML 语法** -- `config.toml` 能否正确解析
4. **守护进程状态** -- 守护进程是否正在运行
5. **端口 4545 可用性** -- 如果守护进程未运行，检查端口是否空闲
6. **过期的 daemon.json** -- 崩溃后残留的 `daemon.json`
7. **数据库文件** -- SQLite 魔术字节验证
8. **磁盘空间** -- 可用空间不足 100MB 时发出警告（仅 Unix）
9. **Agent 清单文件** -- 验证 `~/.librefang/workspaces/agents/` 中所有 `.toml` 文件
10. **LLM 提供商密钥** -- 检查 10 个提供商的环境变量（Groq、OpenRouter、Anthropic、OpenAI、DeepSeek、Gemini、Google、Together、Mistral、Fireworks），执行在线验证（401/403 检测）
11. **通道令牌** -- Telegram、Discord、Slack 令牌的格式验证
12. **配置一致性** -- 检查配置中 `api_key_env` 引用是否与实际环境变量匹配
13. **Rust 工具链** -- `rustc --version`

**示例：**

```bash
librefang doctor

librefang doctor --repair

librefang doctor --json
```

---

### librefang update

将 CLI 二进制文件更新到所配置更新频道的最新版本。

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

**选项：**

| 选项 | 说明 |
|---|---|
| `--check` | 仅检查是否有更新版本，不安装。 |
| `--version <TAG>` | 安装指定的 GitHub Release 标签（如 `v2026.3.2407`）。 |
| `--channel <CHANNEL>` | 临时覆盖本次调用的更新频道（`stable`、`beta` 或 `rc`）。 |

**更新频道：**

LibreFang 支持 Apple 风格的更新频道。在 `config.toml` 中设置默认频道：

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

| 频道 | 接收的版本 |
|---|---|
| `stable` | 仅稳定版（默认） |
| `beta` | 稳定版 + beta 版 |
| `rc` | 所有版本，包括 release candidate |

**示例：**

```bash
librefang update                    # 安装当前频道的最新版本
librefang update --check            # 仅检查更新
librefang update --channel rc       # 本次使用 rc 频道
librefang update --version v0.7.0   # 安装指定版本
```

---

### librefang dashboard

在默认浏览器中打开 Web 仪表板。

```
librefang dashboard
```

**行为：**

- 需要守护进程正在运行。
- 在系统浏览器中打开守护进程 URL（如 `http://127.0.0.1:4545/`）。
- 将 URL 复制到系统剪贴板（Windows 使用 PowerShell，macOS 使用 `pbcopy`，Linux 使用 `xclip`/`xsel`）。

**示例：**

```bash
librefang dashboard
```

---

### librefang completion

生成 Shell 补全脚本。

```
librefang completion <SHELL>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<SHELL>` | 目标 Shell。可选值：`bash`、`zsh`、`fish`、`elvish`、`powershell`。 |

**示例：**

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

---

有关 Agent、Hand、工作流、触发器、技能、通道和配置的详细命令参考，请参阅 **[CLI 命令参考](/zh/integrations/cli/commands)**。

---

## 快速聊天

### librefang chat

快速启动聊天会话的别名。

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

**参数：**

| 参数 | 说明 |
|---|---|
| `<AGENT>` | 可选的 Agent 名称或 UUID。 |

**行为：**

- 如果 `~/.librefang/` 中不存在 `config.toml`，首次运行 `chat` 命令时会自动执行快速初始化向导。
- **守护进程模式：** 在运行中的 Agent 中按名称或 ID 查找。如果未指定 Agent 名称，使用第一个可用的 Agent。如果没有 Agent 存在，建议运行 `librefang agent new`。
- **独立模式（无守护进程）：** 启动进程内核并从模板自动生成 Agent。搜索与给定名称匹配的 Agent，然后回退到 `assistant`，再回退到第一个可用模板。

这是开始聊天最简单的方式 -- 无论是否有守护进程都可使用。

**示例：**

```bash
# 与默认 Agent 聊天
librefang chat

# 按名称与指定 Agent 聊天
librefang chat coder

# 按 UUID 与指定 Agent 聊天
librefang chat a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

---

## 守护进程自动检测

CLI 使用两步机制检测运行中的守护进程：

1. **读取 `daemon.json`：** 守护进程启动时将 `~/.librefang/daemon.json` 写入，其中包含监听地址（如 `127.0.0.1:4545`）。CLI 读取此文件以获取守护进程位置。

2. **健康检查：** CLI 以 2 秒超时向 `GET http://<listen_addr>/api/health` 发送请求。如果健康检查成功，则认为守护进程正在运行，CLI 通过 HTTP 与其通信。

如果任一步骤失败（无 `daemon.json`、过期文件、健康检查超时），CLI 对支持此模式的命令回退到进程内模式。需要守护进程的命令（工作流、触发器、通道测试/启用/禁用、仪表板）将报错退出并提供帮助信息。

**守护进程生命周期：**

```
librefang start          # 启动守护进程，写入 daemon.json
                        # 其他 CLI 实例检测到 daemon.json
librefang status         # 通过 HTTP 连接到守护进程
Ctrl+C                  # 守护进程关闭，daemon.json 被删除

librefang doctor --repair  # 清理崩溃后残留的 daemon.json
```

---

## 环境文件

LibreFang 在每次 CLI 调用时将 `~/.librefang/.env` 加载到进程环境中。系统环境变量优先于 `.env` 中的值。

`.env` 文件存储 API 密钥和秘钥：

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

建议使用 `config set-key` / `config delete-key` 命令管理密钥，而不是直接编辑文件，因为这些命令会确保正确的文件权限。

---

## 退出码

| 退出码 | 含义 |
|---|---|
| `0` | 成功。 |
| `1` | 一般错误（无效参数、操作失败、守护进程缺失、解析错误、生成失败）。 |
| `130` | 第二次 `Ctrl+C` 中断（强制退出）。 |

---

有关使用示例、迁移指南和 MCP 集成说明，请参阅 **[CLI 示例与指南](/zh/integrations/cli/examples)**。

---

## 支持的 LLM 提供商

以下提供商可通过 `librefang config set-key` 和 `librefang doctor` 识别：

| 提供商 | 环境变量 | 默认模型 |
|---|---|---|
| Groq | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
| Gemini | `GEMINI_API_KEY` 或 `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` | -- |

其他搜索/获取类提供商密钥：`BRAVE_API_KEY`、`TAVILY_API_KEY`。
