CashCat CLI

AI Agent 优先的命令行工具，提供知识库管理、自选股查询、热榜和实时资讯获取能力。

快速开始

# 安装 CLI
npm install -g @finstep/cashcat-cli

# 安装 Skills（让 AI Agent 能发现 CLI 能力）
npx skills add . -g -y

# 配置认证 token
export CASHCAT_CLI_TOKEN=cc_xxxxxxxxxxxx
# 或使用 config 命令持久化配置
cashcat-cli config set --token <your-token>

# 试用
cashcat-cli watchlist list
cashcat-cli event hot
cashcat-cli knowledge list --parent-id root --output json

支持的平台

| 系统 | 架构 | |------|------| | macOS (darwin) | amd64, arm64 | | Linux | amd64, arm64 | | Windows (win32) | amd64 |

配置

读取优先级：CLI flag > 环境变量 > 配置文件 > 默认值。

| 环境变量 | 说明 | 默认值 | |----------|------|--------| | CASHCAT_CLI_TOKEN | 认证 token | - | | CASHCAT_API_ENDPOINT | API 地址 | https://xcs.cashcat.cn |

Token 可通过 CashCat OpenAPI 获取。

命令参考

命令结构：cashcat-cli <领域> <动作> [参数]

知识库

| 命令 | 说明 | 必填参数 | 可选参数 | |------|------|----------|----------| | knowledge list | 列出节点 | — | --parent-id, --node-type dir\|file\|all | | knowledge get | 获取节点详情 | --id | — | | knowledge search | 搜索节点 | --query | --parent-id, --page-size | | knowledge create-dir | 创建目录 | --parent-id, --name | — | | knowledge create-note | 创建笔记 | --parent-id, --name | --content（Markdown） | | knowledge update-note | 更新笔记 | --id | --name, --content（Markdown） | | knowledge upload | 上传文件 | --parent-id, --file | — | | knowledge download | 下载文件 | --id | --output（保存路径） | | knowledge delete | 删除节点 | --id | --force（跳过确认） | | knowledge move | 移动节点 | --id, --target | — | | knowledge rename | 重命名节点 | --id, --name | — | | knowledge import-link | 导入外部链接 | --parent-id, --url | — | | knowledge quota | 查询配额 | — | — |

自选股

| 命令 | 说明 | |------|------| | watchlist list | 获取自选股列表 |

资讯

| 命令 | 说明 | 必填参数 | 可选参数 | |------|------|----------|----------| | event hot | 热榜 | — | — | | event list | 资讯列表 | — | --page-size, --page-token | | event detail | 资讯详情 | --event-id | — | | event search | 搜索资讯 | --key | --page-size |

更新

| 命令 | 说明 | 可选参数 | |------|------|----------| | update | 更新 CLI 到最新版本 | --check（仅检查）、--json（JSON 输出） |

配置

| 命令 | 说明 | 可选参数 | |------|------|----------| | config get | 查看当前配置 | — | | config set | 设置配置项 | --token、--endpoint |

配置文件

配置保存在 ~/.cashcat-cli/config.json，可用 config set 命令修改：

cashcat-cli config set --token <token> --endpoint <endpoint>

读取优先级：CLI flag > 环境变量 > 配置文件 > 默认值。

文件上传

knowledge upload 在 CLI 内部封装了完整的分片上传流程，Agent 只需执行一条命令：

cashcat-cli knowledge upload --parent-id <id> --file /path/to/file.pdf

上传策略：

• 文件 ≤ 5 MB：单次直传
• 文件 > 5 MB：自动分片上传（Init → UploadPart × N → Complete），并发 3-5 片，失败指数退避重试
• 上传中断后再次执行相同命令，自动从断点恢复（状态存于 ~/.cashcat/upload_state/）

进度示例：

$ cashcat-cli knowledge upload --file large-report.pdf --parent-id 12345
Initializing upload... done (part_size=5MB, total_parts=18)
Uploading: [████████░░░░░░░░░░] 8/18 (44%)  ETA: 12s
Upload complete ✓  node_id=67890

全局选项

| 选项 | 环境变量 | 说明 | |------|---------|------| | --token <str> | CASHCAT_CLI_TOKEN | 认证 token | | --endpoint <url> | CASHCAT_API_ENDPOINT | API 地址 | | -o, --output json\|table | — | 输出格式，默认 table，Agent 调用建议 json |

Agent 集成

export CASHCAT_CLI_TOKEN=cc_xxx
export CASHCAT_API_ENDPOINT=https://api.cashcat.app

# 推荐使用 JSON 输出供 Agent 解析
cashcat-cli knowledge list --parent-id root --output json
cashcat-cli event hot --output json
cashcat-cli watchlist list --output json

安装流程

CLI 通过 npm postinstall 钩子自动下载二进制：

npm install -g @finstep/cashcat-cli
  → postinstall 触发 install-wizard.js
  → 从 GitLab Releases 下载 CLI 二进制
  → 解压到 ~/.local/bin/
  → 如果需要，自动将 ~/.local/bin 加入 shell PATH 配置

macOS 默认 PATH 通常不包含 ~/.local/bin。安装脚本会自动写入带 CashCat 标记的 shell 配置块；安装完成后运行提示中的 source ... 命令，或重启终端后即可使用。

Skills 通过 npx skills add 安装到 AI Agent：

npx skills add cashcat/cashcat-cli -g -y
  → 安装 skills 到 ~/.claude/skills/ 等 agent 目录
  → AI Agent 启动时加载 SKILL.md 发现 CLI 能力

环境变量：

| 变量 | 说明 | 默认值 | |------|------|--------| | CASHCAT_GITLAB_PROJECT | GitLab 项目路径 | cashcat/cashcat-cli |

发布流程

# 1. 确保所有更改已提交

# 2. 运行发布脚本（版本号从 git tag 获取）
./scripts/release.sh [version]

# 或手动指定版本
./scripts/release.sh 1.2.3

# 3. 脚本自动完成：
#    - 构建多平台二进制（darwin/linux/windows × amd64/arm64）
#    - 打包为 .tar.gz（仅 CLI 二进制）
#    - 创建 git tag（若不存在）
#    - 上传到 GitLab Releases（需安装 glab CLI）

发布产物（dist/）：

dist/
├── cashcat-cli-{version}-darwin-amd64.tar.gz
├── cashcat-cli-{version}-darwin-arm64.tar.gz
├── cashcat-cli-{version}-linux-amd64.tar.gz
├── cashcat-cli-{version}-linux-arm64.tar.gz
└── cashcat-cli-{version}-windows-amd64.tar.gz

手动发布步骤（无 glab CLI 时）：

# 1. 构建并打包
./scripts/release.sh --build-only 1.2.3

# 2. 手动上传 dist/ 下的 tar.gz 文件到 GitLab Releases
#    https://gitlab.finstep.cn/cashcat/cashcat-cli/-/releases/new

# 3. 创建 git tag 并推送
git tag v1.2.3
git push origin v1.2.3