CLI 用法¶

ChatEnv 的 CLI 入口是 chatenv。所有命令默认只读取一个根变量：

export CHATARCH_HOME=~/.chatarch

实际 env/profile 根目录为：

$CHATARCH_HOME/envs/

也可以对单次命令使用 --home：

chatenv --home /tmp/chatarch cat -t example

交互策略¶

缺少必要命令参数时，ChatEnv 默认会在可交互终端中自动补问。例如缺少 profile name、key，或命令需要唯一 config type 但未传 -t/--type 时，会进入补参流程。

CHATARCH_AUTO_PROMPT 是内置、非敏感的 ChatArch typed 字段，默认字符串值为 true；其 active profile 的固定位置是 $CHATARCH_HOME/envs/ChatArch/.env，类型别名为 chatarch。可以通过已有命令查看和保存它：

chatenv status -t chatarch --detail
chatenv set CHATARCH_AUTO_PROMPT=false
chatenv save -t chatarch automation-off
chatenv use -t chatarch automation-off

自动补问的优先级为：显式 -i/-I、进程 CHATARCH_AUTO_PROMPT、所选 home 下 active ChatArch/.env、默认 true。

-i：显式强制交互补问，但仍要求可交互 TTY。
-I：显式禁用交互补问，缺必要参数时报错。
CHATARCH_AUTO_PROMPT=false：关闭默认自动补问；不影响显式 -i，也不影响必要参数已经足够的命令。

可识别的 false 值为 false、0、no、off；其他字符串保持启用语义：

export CHATARCH_AUTO_PROMPT=false
chatenv get          # 直接报错，不自动询问 key
chatenv get -i       # 仍然强制询问 key

持久化 active-profile 策略目前仅由 ChatEnv CLI 消费；其他 ChatArch CLI 仍需自行接入。进程环境变量仍是已支持该变量的 CLI 可共享的覆盖方式。

Schema 注册¶

chatenv 命令基于已注册 schema 工作。ChatEnv 内置少量 ChatArch 共享 schema（当前为 ChatArch / OpenAI / Feishu）；业务项目的私有变量仍应定义并注册自己的 BaseEnvConfig 子类。

from chatenv import BaseEnvConfig, EnvField

class ExampleConfig(BaseEnvConfig):
    _title = "Example Configuration"
    _aliases = ["example"]
    _storage_dir = "Example"

    EXAMPLE_API_KEY = EnvField("EXAMPLE_API_KEY", is_sensitive=True)

初始化¶

chatenv init                  # 写入全部已注册类型的 active .env
chatenv init -t example       # 只写入 Example 类型
chatenv init -t example -i    # 初始化前逐项补问

查看¶

chatenv --version             # 查看当前 chatenv 版本
chatenv --tree                # 从已注册 Click 命令生成完整命令树
chatenv --tree-brief          # 从同一注册表生成省略参数签名的简略命令树
chatenv list                  # 按类型列出 active .env [default] 和 named profiles
chatenv list -t example
chatenv status                # 列出当前 Python 环境已注册的平台/schema
chatenv status --detail       # 展开每个平台的变量、敏感性、默认值和 provider 来源
chatenv status -t example --detail
chatenv cat                   # 输出所有 active values，敏感值默认打码
chatenv cat -t example
chatenv cat -t example work   # 输出 Example/work.env
chatenv cat -t example --no-mask

Profile¶

chatenv new -t example work       # 从当前 active values 创建 work.env
chatenv save -t example work      # 保存当前 active values 到 work.env
chatenv use -t example work       # 将 work.env 激活为 .env
chatenv delete -t example work    # 删除 work.env

new/save/delete 遇到覆盖或删除会确认；自动化场景使用 -y/--yes。

测试配置¶

chatenv test -t example             # 测试当前 active 配置
chatenv test -t example work        # 仅测试 Example/work.env，不切换 active
chatenv test -t example --profile work
chatenv --home /tmp/chatarch test -t example work

不传 profile 时，加载所选 home 下目标类型的 active .env，缺少的字段按原有规则回退到进程环境变量和 schema 默认值。指定 profile 时，只加载该类型的命名 profile 和 schema 默认值；缺少的字段不会借用 active 配置、进程环境变量或上一次命令留下的值。profile 不存在时明确报错，不执行 provider 的 test()，也不修改配置文件。

--profile NAME 等价于位置参数 PROFILE。同时传入时，规范化后相同的名称（如 work 和 work.env）可以接受，不同名称明确报错。命名 profile 的值按字面值读取，不进行 dotenv ${VAR} 的进程环境插值。provider 继续使用无参 test()，由 ChatEnv 在调用前统一加载 profile。

测试的具体内容由服务包实现，可能包含真实网络请求。例如安装 ChatGH 后，chatenv test -t gh work 测试 GitHub 的 work profile。

Key 操作¶

chatenv set EXAMPLE_API_KEY=sk-xxx
chatenv get EXAMPLE_API_KEY

set 会根据 key 所属 schema 写回对应类型的 active .env。

Paste¶

paste 用于跨机器复制 typed env。输入不要求是严格 dotenv 文件，会从终端日志、shell prompt、复制文本里提取已注册 key；同一行里用空格分隔的多个 KEY='VALUE' 片段也会被逐个识别。

chatenv cat -t example --no-mask | chatenv paste --stdin --profile work --yes
chatenv paste --value "EXAMPLE_API_KEY='sk-xxx'" --yes
chatenv paste --value "EXAMPLE_MODEL='gpt example' EXAMPLE_API_KEY='sk-xxx'" --yes
chatenv paste

写入前会输出识别概要：识别到哪些类型、哪些 key、未知 key 被忽略。

Runtime tokens¶

Token-store 是运行态，不是另一个手工维护 env 文件。日常刷新应由服务包注册 refresh provider 后执行：

chatenv token refresh PyPI RexWzh
chatenv token status PyPI RexWzh
chatenv token list PyPI
chatenv token clear PyPI RexWzh        # dry-run
chatenv token clear PyPI RexWzh --execute

服务包通过 pyproject.toml 注册：

[project.entry-points."chatenv.token_refreshers"]
PyPI = "chatpypi.session_ops:refresh_chatenv_token"

刷新函数返回 chatenv.TokenRefreshResult 或同形 mapping；ChatEnv 负责写入 tokens/<Service>/<profile>.json 并只输出 safe metadata。若确实需要迁移或接入外部刷新器，可显式导入：

external-refresh-command | chatenv token import PyPI RexWzh --stdin --token-type web_session

token import 是显式交接入口，不代表 ChatEnv 推荐用户手工维护 token JSON。

命令树 / Readback¶

chatenv --tree 从当前安装包的 Click 注册表实时生成带参数签名的命令树；chatenv --tree-brief 从同一注册表生成省略参数签名的版本。两者都适合发布验收、文档校对和自动化 readback。

chatenv
├── --help  # Show this message and exit.
├── --version  # Show the version and exit.
├── --tree  # Print the registered command tree.
├── --tree-brief  # Print the registered command tree without parameter signatures.
├── --home HOME  # Override CHATARCH_HOME for this command.
├── init [--type CONFIG-TYPES] [--interactive]  # Create or update active typed env files.
├── new [NAME] [--type CONFIG-TYPES] [--yes] [--interactive]  # Create a named typed profile without activating it.
├── paste [--value VALUE] [--stdin] [--profile PROFILE] [--yes] [--interactive]  # Paste loose env text and import recognized keys.
├── use [NAME] [--type CONFIG-TYPES] [--interactive]  # Activate a named profile for one config type.
├── list [--type CONFIG-TYPES]  # List active default and named profiles grouped by config type.
├── status [--type CONFIG-TYPES] [--detail]  # Show registered config platforms and provider ownership.
├── token  # Manage generic runtime token profiles.
│   ├── status <SERVICE> [PROFILE] [--format OUTPUT-FORMAT]  # Show safe runtime token metadata for SERVICE/PROFILE.
│   ├── refresh <SERVICE> [PROFILE] [--format OUTPUT-FORMAT]  # Refresh SERVICE/PROFILE through a registered service refresh provider.
│   ├── import <SERVICE> [PROFILE] [--stdin] [--file VALUE-FILE] [--token-type TOKEN-TYPE] [--summary SUMMARY] [--expires-at EXPIRES-AT] [--format OUTPUT-FORMAT]  # Explicitly import externally refreshed runtime token JSON.
│   ├── list [SERVICE] [--format OUTPUT-FORMAT]  # List runtime token profiles grouped by service.
│   └── clear <SERVICE> [PROFILE] [--execute] [--format OUTPUT-FORMAT]  # Clear a generic runtime token file for SERVICE/PROFILE.
├── cat [NAME] [--no-mask] [--type CONFIG-TYPES]  # Print active values, or a named typed profile with -t TYPE NAME.
├── get [KEY] [--interactive]  # Get a configuration value from active typed env files.
├── set [KEY-VALUE] [--interactive]  # Set a configuration value in the matching active typed env file.
├── save [NAME] [--type CONFIG-TYPES] [--yes] [--interactive]  # Save current active values as a named profile.
├── delete [NAME] [--type CONFIG-TYPES] [--yes] [--interactive]  # Delete a named profile for one config type.
└── test [PROFILE] [--target TARGET] [--profile NAME] [--interactive]  # Test active configuration or a named PROFILE for one target.