实操指南：使用 CLI 操作 FastGPT

通过官方命令行工具（fastgpt）与 AI Agent 快速在终端管理 FastGPT 资源。

FastGPT CLI（fastgpt）是 FastGPT 官方推出的终端命令行工具，旨在为开发者、DevOps 工程师以及 AI 编程助手（如 Codex、Claude Code、Cursor、Windsurf 等）提供稳定、安全、可编程的终端管理能力。

无论是通过人类终端直接操作，还是让 AI Agent 协助自动化执行，你都可以无需打开浏览器，直接在终端中完成身份认证、团队切换、知识库管理、效果测试及 App 对话管理。

AI Agent 一键接入引导

如果你正在使用 AI 编程助手（如 Codex 或 Claude Code），无需手动执行安装命令，直接将以下引导指令发送给你的 Agent。Agent 将自动获取官方 Skill 规范，并全自动完成 CLI 安装、登录引导、环境诊断与能力发现：

在 Codex / Claude Code 对话框中直接发送以下提示词：

帮我根据 https://doc.fastgpt.cn/cli/skill.md 安装 FastGPT CLI 并完成引导。

⚡ 开发者快速上手（3 步初始化）

如果你习惯在终端手动操作，只需 3 步即可完成就绪：

1. 安装 CLI

需要 Node.js >= 20.12.0 环境，执行全局安装：

npm install -g @fastgpt/cli@beta
# 或使用 pnpm: pnpm add -g @fastgpt/cli@beta

# 确认安装就绪
fastgpt --version

2. 身份认证与登录

运行登录命令完成身份鉴权：

# 方案 A：在交互终端中执行交互式登录（公有云或私有化部署）
fastgpt login
# 若为自建实例：fastgpt login --base-url https://your-domain.com/api

# 方案 B：使用 API Key 登录（适合 CI / 容器 / Agent 脚本环境）
fastgpt login --api-key <FASTGPT_API_KEY>

# 方案 C：通过标准输入传入密码
echo "<PASSWORD>" | fastgpt login --username <USERNAME> --password-stdin

登录成功后，可随时查看当前认证上下文与所属团队：

fastgpt whoami

凭据存储与会话有效期：凭据优先存储在系统安全密钥环（macOS Keychain / Linux Secret Service）中。Session 自创建起 7 天后到期，到期后请执行 fastgpt login 重新登录。

3. 环境体检（Doctor）

执行一键自检，诊断本地环境、配置文件权限及服务端连通性：

fastgpt doctor

核心操作能力概览

FastGPT CLI 采用领域驱动（DDD）设计，命令结构精炼清晰：

功能分类	常用命令示例	说明
身份与团队	`fastgpt whoami` `fastgpt auth switch-team --team-id <id>`	查看当前用户身份及团队空间，或快速切换工作团队
知识库检索	`fastgpt dataset list` `fastgpt dataset search <id1,id2> "关键词"`	分页查询知识库列表，或统一搜索一个或多个知识库，默认返回前 20 条
知识库管理	`fastgpt dataset create --name "文档库"` `fastgpt dataset update <id> --parent-id null` `fastgpt dataset delete <id> --dry-run`	知识库全生命周期 CRUD，支持移至根目录及 `--dry-run` 安全预览
系统配置	`fastgpt config list` `fastgpt commands --format json`	查看客户端本地配置，或探测获取完整的可编程命令元数据
App 对话	`fastgpt chat run --appId <id> --text "你好"` `fastgpt chat init --appId <id> --chatId <chatId>` `fastgpt chat stop --appId <id> --chatId <chatId>`	调用 App 并返回 JSON，读取配置与状态，或发送停止信号
App 对话记录	`fastgpt chat history list --appId <id>` `fastgpt chat record list --appId <id> --chatId <chatId>`	查询、更新和软删除 App 对话，批量查状态、标记已读，并读取消息及响应详情

App 对话命令仅对接 OpenAPI。应用 API Key 可省略 --appId；个人 API Key 和登录态需指定 App。chat run 支持 --file <path> 或 --stdin 读取 JSON 请求，写操作均支持 --dry-run。

chat record list 默认读取最新一页，消息按时间正序返回，每次只查询一页。将 meta.prevCursor 传给 --prevId 读取更早的轮次，或将 meta.nextCursor 传给 --nextId 读取更新的轮次；--initialId 定位指定 dataId 的 AI 回复附近。三个 ID 参数互斥，角色由服务端按方向确定。--pageSize 是参考消息条数，为补齐轮次边界，实际返回条数可能略超。

接口直接返回 prevCursor、nextCursor，CLI 原样放入 meta；无对应方向的下一页时为 null。

消息详情等业务操作使用 dataId；消息中的 id 是已弃用的兼容别名。

chat run 默认 HTTP 超时为 300000 毫秒，可通过 --timeoutMs 调整；超时不会自动停止 App，生成失败也不会自动重试。chat stop 写入停止信号后立即返回，不等待后台收尾。完整参数通过各命令的 --help 查看。

自动化与脚本规范建议

机器与 Agent 调用：附加 --format json 参数，命令将输出确定性的结构化 JSON 信封，日志严格走 stderr，确保 stdout 纯净便于管道解析。
高危操作保护：删除操作（如 dataset delete）支持 --dry-run 预览；在非交互式脚本或 CI 中执行破坏性操作必须显式附加 --yes 确认。