32r4-cli-demo

32r4-cli-demo

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

安装

推荐使用 uv tool 安装：

uv tool install 32r4-cli-demo

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

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

配置

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

查看当前配置：

cli-demo config show
cli-demo config path

当前配置文件固定路径：

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

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

设置配置：

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"

也可以一次设置多个值：

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

清除某个配置项：

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。

使用

cli-demo
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 发起一次文本问答请求。

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.

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.

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
• /history
• /retry
• /model
• /exit
• /quit

In an interactive terminal, cli-demo chat opens with a colorful welcome card and renders prompts and replies as styled message blocks. The chat prompt is a lightweight inline REPL, not a fixed input box.

When input or output is piped, chat falls back to plain text instead of launching the richer interactive UI.

cli-demo --version

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

cli-demo --version
cli-demo -v

cli-demo update

使用 uv tool 升级当前 CLI。

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，使用 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。

配置完成后，发布方式会自动完成：

git tag v0.4.4
git push origin v0.4.4

推送 tag 后，GitHub Actions 会自动：

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

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

本地验证

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