CLI 快速上手与概览
欢迎使用 基估宝命令行工具 (@jigubao/cli)。这是一个专为基估宝 Pro 会员用户设计的高效命令行接口。能够帮助你在无需打开浏览器的情况下，实时查询全网基金净值、大盘指数、个人持仓估值以及交易流水，轻松将其集成到 Shell 脚本、自动化工作流或 AI 大模型驱动的投资分析系统中。
一、安装登录与配置
1.1 安装方式
推荐使用 Node.js 官方包管理器进行全局安装（需 Node.js >= 20.9.0）：
# 使用 npm 安装
npm install -g @jigubao/cli
# 使用 pnpm 安装
pnpm add -g @jigubao/cli
# 使用 yarn 安装
yarn global add @jigubao/cli
安装完成后，可通过以下命令验证是否安装成功：
jgb -v
# 输出示例: 1.0.0
若终端正确打印出版本号，说明 CLI 已全局安装成功，可以开始使用。如果提示找不到命令，请检查 Node.js 环境变量与全局 bin 路径是否已正确配置。
1.2 登录认证与会话管理
@jigubao/cli 采用基于 Supabase Auth 的云端身份认证体系。安装完成后，你需要先完成登录以绑定基估宝 Pro 会员账号，从而解锁持仓查询、交易流水、定投记录等个人账户相关功能。公开的基金行情查询指令（如 search、info、market）无需登录即可直接使用。
CLI 提供以下认证管理指令：
| 指令 | 说明 |
|---|---|
jgb login | 启动交互式邮箱验证码登录流程，通过邮箱接收 6 位 OTP 验证码完成 Supabase 身份认证，认证成功后将 Token 持久化保存至本地 ~/.jgb/ 目录 |
jgb login password | 账号密码登录，通过邮箱和密码直接登录 Supabase 账号，无需验证码。支持 --email 和 --password 参数实现非交互式直接登录 |
jgb logout | 清除本地保存的登录凭证与会话 Token，退出当前账号登录状态 |
jgb status | 查看当前登录状态，显示已登录账号的邮箱、会员等级及到期时间；若未登录则提示需要先执行 jgb login |
使用示例
# 方式一：邮箱验证码登录（交互式）
jgb login
# 方式二：账号密码登录（交互式，逐步提示输入邮箱和密码）
jgb login password
# 方式三：账号密码直接登录（非交互式，适合脚本自动化）
jgb login password --email user@example.com --password mypassword123
# 方式四：仅传入邮箱，交互式输入密码
jgb login password --email user@example.com
# 查看当前登录状态与会员信息
jgb status
# 退出登录，清除本地凭证
jgb logout
login 与 login password 及 logout 指令为交互式操作，不支持 --json / --text 结构化输出模式。status 指令支持结构化输出，可通过 jgb status --json 获取机器可读的会话信息，便于在自动化脚本或 AI Agent 流程中进行登录态前置检查。
:::tip 账号密码登录参数
jgb login password 支持以下选项参数，实现非交互式直接登录，便于在 CI/CD 流水线或 Shell 脚本中自动化使用：
| 选项 | 参数类型 | 说明 |
|---|---|---|
--email <email> | string | 指定登录邮箱地址，跳过交互式邮箱输入提示 |
--password <password> | string | 指定登录密码，跳过交互式密码输入提示 |
当两个参数同时提供时，完全不触发交互式提示，直接调用 Supabase Auth 完成登录；仅提供一个参数时，另一个仍通过交互式提示输入。 :::
1.3 环境配置与数据存储
CLI 运行时会在用户主目录下创建 ~/.jgb/ 目录，用于持久化本地配置缓存与用户偏好（替代 Web 端的 LocalStorage/IndexedDB 机制）：
~/.jgb/config.json: 全局用户偏好配置（数据源选项、超时设置等）。
二、全局语法与通用选项
@jigubao/cli 命令结构采用标准的双层或多层命名空间体系：
jgb <command> [subcommand] [arguments] [options]
全局通用选项 (Global Flags)
无论调用哪个具体功能命令，以下通用参数选项均可在任意指令中挂载支持（注：login、login password 与 logout 指令不支持结构化输出模式）：
| 选项 (Flag) | 参数类型 | 默认值 | 说明 |
|---|---|---|---|
--json | boolean | false | 以结构化 JSON 格式输出结果，同时禁用所有交互式 UI 动画与引导文字，适用于 jq、管道操作及程序化自动化处理 |
--text | boolean | false | 以纯文本格式输出结果，去除控制台颜色和特殊 UI 符号，生成结构清晰的文字摘要，专为 LLM / AI Agent 优化消费 |
-h, --help | boolean | false | 显示当前 CLI 工具或指定具体子命令的详细帮助手册与参数用法 |
-v, --version | boolean | false | 显示当前 jgb 命令行工具的版本号（直接打印纯数字版本，不包含额外装饰字符） |
三、功能边界与路线图 (Roadmap)
为了让开发者、运维人员以及 AI Agent 在调用时获得绝对稳定、无破坏性的体验，@jigubao/cli v1 版本的核心定位为 “高频只读查询能力与自动化集成基座”。当前全量开放的所有命令均保证零副作用（Side-effect Free），绝不会对用户的账户数据、自选列表或云端存储造成不可逆修改。
针对部分进阶的“修改账户数据（写操作）”与“双向交互能力”，团队已经完成了底层核心算法的封装，并统一规划于后继版本中陆续开放。以下为 CLI 路线图 (Roadmap)：
| 命令命名空间 | 规划中命令 (Planned Command) | 目标版本 | 功能预期与使用描述 |
|---|---|---|---|
| 持仓管理 | jgb holding update <code> <value> [cost] | v2.0 | 向个人账户录入或更新基金持仓份额与成本净值 |
| 持仓管理 | jgb holding clear <code> | v2.0 | 清除指定基金持仓及相关交易记录 |
| 交易流水 | jgb trade buy <code> --amount <amt> | v2.0 | 快捷记录即时买入流水，自动重新加权计算平均成本 |
| 交易流水 | jgb trade sell <code> --share <num> | v2.0 | 快捷记录卖出流水，实现收益结转与剩余份额更新 |
| 交易流水 | jgb trade remove <txn-id> | v2.0 | 撤销或删除指定的历史申赎交易记录 |
| 定投管理 | jgb dca plan create/toggle | v2.1 | 从终端创建智能定投计划，或一键暂停/启用指定定投任务 |
| 自选与分组 | jgb watchlist add/remove <code> | v2.1 | 将基金快捷关注至自选池或移出一键观察 |
| 自选与分组 | jgb group create/edit/delete <name> | v2.1 | 自定义创建持仓与自选的分组体系，调整排布逻辑 |
| 数据同步 | jgb sync push / jgb sync pull | v2.2 | 手动触发本地数据库与 Supabase 云端的全量双向同步覆盖 |
四、微信交流群与社区反馈
@jigubao/cli 的持续演进离不开每一位开发者的真实反馈与实战经验分享。为此，我们建立了「基估宝 CLI 用户支持群」，这是一个专为 Pro 会员、CLI 开发者及自动化投资爱好者打造的专属技术社群。在这里，你可以：
- 📣 第一时间获取版本动态：CLI 版本更新公告、新功能预告与破坏性变更说明均会在群内同步首发。
- 🤝 交流实战经验：与同行探讨 Shell 脚本自动化流水线搭建、AI Agent 集成模式、定投策略回测等进阶玩法。
- 🐛 加速问题反馈：在使用中遇到的 Bug、数据源异常或功能建议，可直接在群内 @官方成员，获得更快的响应与跟进。
- 💡 参与产品共建：优质的功能建议与场景需求有机会被纳入正式 Roadmap，你的声音将直接影响 CLI 的演进方向。
扫描下方二维码，即可直接加入「基估宝 CLI 用户支持群」：
