Metadata-Version: 2.4
Name: numcat-cli
Version: 0.1.0
Summary: Official command-line client for the NumCat financial data API
Project-URL: Homepage, https://numcat.net
Project-URL: Documentation, https://numcat.net/docs
Author: NumCat
Keywords: cli,finance,market-data,numcat
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: packaging<26,>=24
Requires-Dist: platformdirs<5,>=4
Requires-Dist: rich<15,>=13
Requires-Dist: typer<1,>=0.12
Provides-Extra: test
Requires-Dist: build<2,>=1.2; extra == 'test'
Requires-Dist: pytest<9,>=8; extra == 'test'
Description-Content-Type: text/markdown

# NumCat CLI

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

## 安装

```bash
uv tool install numcat-cli
```

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

```bash
uv tool upgrade numcat-cli
```

## 配置

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

```bash
numcat auth set-key
numcat auth status
```

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

## 查询

```bash
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。

可用命令包括：

```text
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 版本检查。

## 开发

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