# 32r4-cli-demo

`32r4-cli-demo` 是一个用 `Typer` 构建的 OpenAI AI CLI 示例项目。当前版本支持通过固定位置的本地 `.env` 配置文件管理 `api_key`、`base_url`、`model`，并通过 OpenAI Responses API 发起一次性文本问答调用。

## 安装

推荐使用 `uv tool` 安装：

```powershell
uv tool install 32r4-cli-demo
```

在正式发布到 PyPI 之前，也可以直接从 GitHub 安装：

```powershell
uv tool install git+https://github.com/32r4/cli-demo.git
```

## 配置

推荐直接用 CLI 管理配置文件。

查看当前配置：

```powershell
cli-demo config show
cli-demo config path
```

当前配置文件固定路径：

```text
C:\Users\26707\.cli-demo\.env
```

这个路径不能通过命令或环境变量修改。

设置配置：

```powershell
cli-demo config set --api-key "your-api-key"
cli-demo config set --base-url "https://api.openai.com/v1"
cli-demo config set --model "gpt-5.4"
```

也可以一次设置多个值：

```powershell
cli-demo config set --api-key "your-api-key" --base-url "https://api.openai.com/v1" --model "gpt-5.4"
```

清除某个配置项：

```powershell
cli-demo config unset api-key
cli-demo config unset base-url
cli-demo config unset model
```

说明：

- `api_key`、`base_url`、`model` 都保存在本地配置文件中。
- 配置文件固定保存在 `C:\Users\26707\.cli-demo\.env`。
- 直接运行 `cli-demo config set` 会进入交互式设置。
- 如果配置文件里没有 `api_key`，程序仍会回退到 `OPENAI_API_KEY` 环境变量。
- 如果配置文件里没有 `base_url`，程序仍会回退到 `OPENAI_BASE_URL` 环境变量。
- 如果配置文件里没有 `model`，默认使用 `gpt-5.4`。

## 使用

```powershell
cli-demo --help
cli-demo ask "Say hello in one sentence."
cli-demo ask "Explain Typer briefly." --system "You are a concise CLI tutor."
cli-demo ask "Hello" --model gpt-5.4-mini
cli-demo version
cli-demo update
```

### `cli-demo ask PROMPT`

向 OpenAI 发起一次文本问答请求。

```powershell
cli-demo ask "Say hello in one sentence."
cli-demo ask "Explain Typer briefly." --system "You are a concise CLI tutor."
cli-demo ask "Hello" --model gpt-5.4-mini
```

可用参数：

- `PROMPT`：必填位置参数
- `--model`：可选模型覆盖，优先级高于配置文件
- `--system` / `-s`：可选系统提示词

### `cli-demo version`

显示当前 CLI 版本和生效中的模型。

```powershell
cli-demo version
```

### `cli-demo update`

使用 `uv tool` 升级当前 CLI。

```powershell
cli-demo update
cli-demo update --dry-run
```

说明：

- `cli-demo update` 会执行 `uv tool upgrade 32r4-cli-demo`
- `cli-demo update --dry-run` 只展示命令，不执行

## 发布到 PyPI

仓库已经包含 GitHub Actions 发布工作流 [`release.yml`](https://github.com/32r4/cli-demo/blob/main/.github/workflows/release.yml)，使用 PyPI Trusted Publishing。

首次发布前，你还需要在 PyPI 做一次配置：

1. 在 PyPI 创建 `32r4-cli-demo` 项目或添加 Trusted Publisher。
2. Publisher 类型选择 GitHub。
3. 仓库填写 `32r4/cli-demo`。
4. Workflow 文件名填写 `release.yml`。
5. Environment 填写 `pypi`。

配置完成后，发布方式有两种：

```powershell
git tag v0.4.1
git push origin v0.4.1
```

然后在 GitHub 上创建并发布对应 Release；或者直接手动触发 `release` 工作流。

## 本地验证

```powershell
uv sync
uv build
uv run cli-demo --help
uv run cli-demo config show
uv run cli-demo config set --model gpt-5.4-mini
uv run cli-demo version
uv run cli-demo ask "   "
uv run cli-demo update --dry-run
uv run python -m cli_demo --help
```
