numcat-cli 0.1.0

Official command-line client for the NumCat financial data API

NumCat CLI

NumCat 官方命令行客户端。它通过统一入口调用 NumCat 金融数据 API，既支持全部 apiname 的通用查询，也提供常用行情的快捷命令。

安装

uv tool install numcat-cli

也可以使用 pipx install numcat-cli。升级命令：

uv tool upgrade numcat-cli

配置

从 NumCat 网页控制台复制 API Key，然后隐藏输入：

numcat auth set-key
numcat auth status

自动化环境使用 NUMCAT_API_KEY。该环境变量的优先级高于操作系统凭据库。 普通配置文件只保存服务地址，不保存 API Key。

查询

numcat calendar latest
numcat stock daily --date 20260710 --symbols 000001,600000
numcat query daily --param tradedate=20260710 --fields symbol,name,close
numcat query screening --params @request.json --format csv --output result.csv

--format 支持 auto、table、json、jsonl 和 csv。交互终端默认显示表格， 管道及重定向默认输出完整 JSON。

可用命令包括：

numcat auth set-key|status|clear
numcat config show|set-base-url
numcat api list|show
numcat query <apiname>
numcat calendar latest|range|recent|by-date
numcat stock basic|daily|minute|tick|screening|limit-pool
numcat market emotion
numcat news latest
numcat doctor
numcat version

通用查询的 --param key=value 始终按字符串发送，适合日期、股票代码等值；数组、 对象和布尔值请通过 --params JSON 传入。两者同时使用时，重复的 --param 覆盖 JSON 顶层同名字段。

稳定退出码：0 成功、2 参数或输出格式错误、3 鉴权/权限/额度错误、4 API 业务或服务端错误、5 网络或超时。

安全

• API Key 使用操作系统凭据库保存，不写入普通配置文件。
• HTTP 地址默认拒绝携带 API Key；确有需要时必须显式传入 --allow-insecure。
• CLI 不采集使用遥测，也不会在输出和错误信息中打印完整密钥。

可用环境变量：

• NUMCAT_API_KEY：覆盖系统凭据库中的密钥，适合 CI 和服务器。
• NUMCAT_BASE_URL：覆盖配置文件中的服务地址。
• NUMCAT_DISABLE_VERSION_CHECK=1：关闭每天一次的 PyPI 版本检查。

开发

cd Product/cli
python -m pip install -e ".[test]"
pytest
python -m build