Rabetbase CLI2.0 快速上手指引
本文档介绍如何在新项目和已有项目中快速接入 Rabetbase CLI 2.0。
当前内容已按
rabetbase-cli v2.2.2、@lovrabet/cli-framework v1.0.3校对。最新版已内置jq二进制，--jq默认按JQ_PATH→ CLI 内置 jq →PATH上的 jq 解析；写入类命令继续保留预览和确认机制，适合 Agent 先看清楚再执行。
推荐方式：通过 AI Agent 自动安装
如果你已经在使用 Claude Code、Codex、Cursor、Trae、Windsurf 等 AI Coding 工具，可以直接把下面的提示词复制给 AI 助手，它会根据指南完成 CLI 安装、Skill 安装和认证登录，你只需要在需要浏览器授权或项目确认时配合完成。
提示词（直接复制给 AI 助手）：
帮我安装 Rabetbase CLI：https://www.lovrabet.com/agent-install-guides/rabetbase-cli.md
AI Agent 安装过程中最容易卡住的是授权确认：当 Agent 粘贴实际
Login URL时，请先打开链接完成浏览器授权，再回到对话告诉 Agent“已完成授权”。如果 Agent 询问是否初始化项目，请只在当前目录确实是目标项目时确认；只是安装 CLI 时不需要执行
rabetbase project init。
支持的 AI Agent 工具：Claude Code、Codex、Cursor、Trae、Windsurf、GitHub Copilot、OpenCode、Hermes Agent、OpenClaw
💡 如果你不使用 AI Agent 工具，或者想手动控制每一步，请继续看下面的手动安装步骤。
手动安装
适用于：首次使用 Rabetbase CLI，本机从未安装过任何版本。
1.1 安装 CLI
# 全局安装（推荐）
npm install -g @lovrabet/rabetbase-cli@latest
# 验证安装
rabetbase --version
最新版本号：
1.2 安装 Rabetbase Skill
推荐直接使用 CLI 自带入口：
rabetbase skill install
如果你需要用原始 skills 命令，也可以执行：
npx skills add lovrabet/rabetbase -g -y
建议全局安装，这样 AI 助手在任意项目目录下都能使用
rabetbase。
1.3 认证
rabetbase auth login
浏览器打开后完成 OAuth 登录，CLI 自动保存会话。认证一次后所有项目通用。
1.4 初始化项目
已有项目目录下初始化配置：
cd your-project/
rabetbase project init
从零创建一个新项目：
rabetbase project create
1.5 快速验证
rabetbase doctor
rabetbase schema --format compress
rabetbase app list --format compress
如果你要确认 --jq 已经可用，可以再跑一条：
rabetbase schema --format compress --jq '.data.cli.version'
二、从老 CLI 1.x 升级
适用于：本机已安装 Lovrabet CLI 1.x，且有使用旧 CLI 的老项目。
2.1 安装新 CLI
# 全局安装（推荐）
npm install -g @lovrabet/rabetbase-cli@latest
# 验证安装
rabetbase --version
2.2 删除旧的 Lovrabet CLI 1.x
npm uninstall -g @lovrabet/cli
2.3 自动升级老项目
在每个老项目目录下运行：
rabetbase project upgrade
该命令会自动完成以下迁移步骤：
| 步骤 | 操作 |
|---|---|
| 1 | .lovrabet.json → .rabetbase.json |
| 2 | 删除 .lovrabet/ 目录 |
| 3 | 删除旧 IDE Skill 文件 |
| 4 | 清理旧 MCP 配置（lovrabet-dataset） |
| 5 | 移除旧 Skill lovrabet/lovrabet-skill |
| 6 | 安装新 Skill lovrabet/rabetbase |
2.4 手动升级兜底
如果自动升级失败，按下面顺序处理：
# 1. 删除旧 Skill
npx skills remove lovrabet
# 2. 安装新 Skill
rabetbase skill install
如果你在 Claude Code 或其他 IDE 里配置过旧 MCP server，还需要停用旧入口：
claude mcp remove lovrabet-dataset
三、当前版本最值得知道的变化
--jq更稳了：最新版已内置 jq sidecar，不再依赖node-jq在安装期去 GitHub 下载二进制，国内网络与 CI 环境更稳定。- 数据集列表默认更完整了：
rabetbase dataset list默认返回 DO V2 数据集，包括DB_TABLE和METADATA；只看数据库表时加--source DB_TABLE，只看元数据时加--source METADATA。 - AppCode 环境变量必须显式使用：CI 里可以继续保存
RABETBASE_APPCODE，但执行命令时要写成--appcode "$RABETBASE_APPCODE"，CLI 不会再静默拿环境变量覆盖项目配置。 - 写入默认更安全了：
rabetbase page generate-start默认只返回 dry-run 预览，真正发起生成必须显式加--apply；项目写配置时也会避免把全局应用配置污染进项目文件。 - 数据集写操作必须明确目标：
dataset rename、field-update、extend-update、delete等命令不再依赖模糊上下文，必须通过--code、--id或--dbid选择目标，并建议先跑--dry-run。 - 菜单资源更新更保守了：
rabetbase menu update更新 CDN 资源时会保留页面原有extend配置，降低覆盖线上配置的风险。 - 研发态也能直接查真实数据了：
rabetbase data filter和rabetbase data getOne已进入正式命令面，适合在开发阶段快速确认真实数据长什么样。 - Skill 安装入口更统一：现在直接执行
rabetbase skill install即可，不必记忆底层npx skills add ...写法。
四、Checklist
全新安装
- 安装 CLI：
npm install -g @lovrabet/rabetbase-cli@latest - 安装 Skill：
rabetbase skill install - 认证：
rabetbase auth login - 初始化项目：
rabetbase project init或rabetbase project create - 验证：
rabetbase doctor
从 1.x 升级
机器（每台做一次）
- 安装新 CLI：
npm install -g @lovrabet/rabetbase-cli@latest - 删除旧 CLI：
npm uninstall -g @lovrabet/cli - 删除旧 Skill：
npx skills remove lovrabet - 停用旧 MCP：
claude mcp remove lovrabet-dataset - 安装新 Skill：
rabetbase skill install - 重新认证：
rabetbase auth login
项目（每个项目做一次）
- 自动升级：
rabetbase project upgrade