Metadata-Version: 2.4
Name: 32r4-cli-demo
Version: 0.4.3
Summary: An OpenAI-powered AI CLI demo with local config management.
Keywords: cli,typer,demo
Author: ezra
Author-email: ezra <ezra.ora.c@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Software Development :: User Interfaces
Requires-Dist: openai>=2.30.0
Requires-Dist: typer>=0.24.1
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/32r4/cli-demo
Project-URL: Repository, https://github.com/32r4/cli-demo
Project-URL: Issues, https://github.com/32r4/cli-demo/issues
Description-Content-Type: text/markdown

# 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 --version
cli-demo -v
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 doctor
cli-demo doctor --no-ping
cli-demo chat
cli-demo chat --system "You are a concise CLI tutor."
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 doctor`

Check local config, dependencies, and optional API connectivity.
```powershell
cli-demo doctor
cli-demo doctor --no-ping
cli-demo doctor --model gpt-5.4-mini
```

Notes:
- By default it performs one minimal API connectivity check.
- `--no-ping` skips the network request and only validates local setup.
- Output includes the effective `api_key`, `base_url`, `model`, `uv`, and `openai` package status.

### `cli-demo chat`

Start an interactive multi-turn chat session.
```powershell
cli-demo chat
cli-demo chat --model gpt-5.4-mini
cli-demo chat --system "You are a concise CLI tutor."
```

Session commands:
- `/help`
- `/clear`
- `/exit`
- `/quit`

### `cli-demo --version`

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

```powershell
cli-demo --version
cli-demo -v
```

### `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.3
git push origin v0.4.3
```

推送 tag 后，GitHub Actions 会自动：

- 创建对应的 GitHub Release
- 自动生成 Release Notes
- 发布到 PyPI

也可以在 GitHub Actions 页面手动触发 `release` 工作流。

## 本地验证

```powershell
uv sync
uv build
uv run cli-demo --help
uv run cli-demo --version
uv run cli-demo -v
uv run cli-demo config show
uv run cli-demo config set --model gpt-5.4-mini
uv run cli-demo ask "   "
uv run cli-demo doctor --no-ping
Write-Output '/exit' | uv run cli-demo chat
uv run cli-demo update --dry-run
uv run python -m cli_demo --help
```
