ChatDNS CLI 树

这是一份以当前 chatdns --help、各级子命令 help、源码和测试为准的命令地图。它回答两个问题：命令如何调用，以及调用后是否会产生外部副作用。

需要先完成 provider profile 配置时，从快速开始进入；证书文件布局和远端部署边界见证书目录与创建规则。

顶层命令

以下命令树来自当前 Click 注册面，可用 chatdns --tree 直接回读：

chatdns
├── --help  # Show this message and exit.
├── --version  # Show the installed ChatDNS version.
├── --tree  # Print this registered command tree and exit.
├── --tree-brief  # Print this registered command tree without parameter signatures and exit.
├── --env ENV-PROFILE  # ChatEnv profile name for provider credentials (use before the command).
├── --chatarch-home CHATARCH-HOME  # Override CHATARCH_HOME when reading ChatEnv profiles.
├── cert  # Manage Let's Encrypt certificates through DNS-01 validation.
│   ├── apply [--domain DOMAINS] [--email EMAIL] [--provider PROVIDER] [--env ENV-PROFILE] [--cert-dir CERT-DIR] [--cert-path CERT-PATH] [--staging] [--force] [--log-file LOG-FILE] [--log-level LOG-LEVEL] [--interactive]  # Apply or renew certificates using ACME DNS-01 validation.
│   ├── check [DOMAINS...] [--cert-dir CERT-DIR] [--cert-path CERT-PATH] [--provider PROVIDER]  # Check local certificate expiry for one or more domains.
│   ├── manifest  # Show, create, or validate Infra certificate manifests.
│   │   ├── init [MANIFEST-PATH] [--cert-dir CERT-DIR] [--cert-path CERT-PATH] [--from-store] [--scripts-dir SCRIPTS-DIR] [--force] [--format OUTPUT-FORMAT]  # Create an Infra manifest and scripts/README scaffold from the local store.
│   │   ├── show [MANIFEST-PATH]  # Render an Infra certificate manifest as a table without modifying it.
│   │   └── validate [MANIFEST-PATH]  # Validate manifest shape and referenced local certificate files.
│   └── status [DOMAINS...] [--cert-dir CERT-DIR] [--cert-path CERT-PATH] [--expiring-within EXPIRING-WITHIN] [--format OUTPUT-FORMAT] [--strict]  # Scan the internal certificate store and report current leaf status.
├── ddns [FULL-DOMAIN] [--domain DOMAIN] [--rr RR] [--ttl TTL] [--interval INTERVAL] [--max-retries MAX-RETRIES] [--retry-delay RETRY-DELAY] [--monitor] [--log-file LOG-FILE] [--log-level LOG-LEVEL] [--ip-type IP-TYPE] [--local-ip-cidr LOCAL-IP-CIDR] [--provider PROVIDER] [--env ENV-PROFILE] [--interactive]  # Run dynamic DNS updates once or in continuous monitoring mode.
├── delete [FULL-DOMAIN] [--domain DOMAIN] [--rr RR] [--type RECORD-TYPE] [--value VALUE] [--yes] [--provider PROVIDER] [--env ENV-PROFILE] [--interactive]  # Delete DNS records by domain, host record, type, and optional value.
├── ip [--type IP-TYPE] [--local-ip-cidr LOCAL-IP-CIDR]  # Show the current public or local IP without touching DNS records.
├── list [--provider PROVIDER] [--page PAGE-NUMBER] [--page-size PAGE-SIZE] [--env ENV-PROFILE]  # List DNS domains in the provider account.
├── records [TARGET] [--domain DOMAIN] [--rr RR] [--type RECORD-TYPE] [--provider PROVIDER] [--env ENV-PROFILE] [--interactive]  # Show DNS record details.
└── set [FULL-DOMAIN] [--domain DOMAIN] [--rr RR] [--type RECORD-TYPE] [--value VALUE] [--ttl TTL] [--provider PROVIDER] [--env ENV-PROFILE] [--interactive]  # Create or update a DNS record.

顶层公共选项：

选项	作用
`--tree`	输出已注册 CLI 命令树并退出
`--tree-brief`	输出省略参数签名的已注册 CLI 命令树并退出
`--version`	输出 ChatDNS 版本
`-e, --env PROFILE`	在命令前选择 provider 的 named ChatEnv profile
`--chatarch-home DIR`	为本次命令覆盖读取 ChatEnv profile 时使用的 `CHATARCH_HOME`
`--help`	输出顶层帮助

副作用分级

分级	命令	边界
只读	`list`、`records`	调用 provider 查询 API，不写 DNS
只读	`ip`	公网模式访问 IP 探测服务；本地模式只扫描本机网卡
只读	`cert check`、`cert status`	读取本地证书并计算续期/库存状态，不执行 ACME
只读	`cert manifest show`、`cert manifest validate`	读取指定 JSON manifest 并展示或校验，不修改原文件
本地文件写入	`cert manifest init`	扫描证书根并写 Infra 工作区 `manifest.json` 与 `scripts/README.md`，不写 live cert root
写 DNS	`set`、`delete`、`ddns`	创建、更新或删除 provider 记录
写 DNS 与证书	`cert apply`	写 `_acme-challenge` TXT，执行 ACME，并安装本地 PEM

“只读”只表示不修改 DNS/证书状态，不表示完全离线：list、records 和公网 ip 仍会访问网络。

域名与记录查询

chatdns list
├── --provider aliyun|tencent    # 显式 provider；否则读 CHATDNS_PROVIDER
├── --page INTEGER               # 默认 1
├── --page-size INTEGER          # 默认 20
└── --env PROFILE                # 命令级 named provider profile

chatdns records [TARGET]
├── --domain DOMAIN              # 与 --rr 组合的替代输入
├── --rr RR                      # 可选主机记录过滤
├── --type TYPE                  # 可选记录类型过滤
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I                      # 强制交互或禁用交互

chatdns ip
├── --type public|local          # 默认 public
└── --local-ip-cidr CIDR         # 只在 local 模式过滤候选网卡地址

records 的 TARGET 可以是托管域 example.com，也可以是完整主机名 www.example.com。如果同时给出位置参数和 --domain/--rr，位置参数优先，CLI 会输出忽略提示。

list 默认只请求第一页（--page 1 --page-size 20）。做完整 zone 盘点时，显式提高 --page-size（Aliyun/Tencent 常用 100）并按 --page 继续分页，直到返回不足一页或 provider 计数核对完成。

常用只读命令：

chatdns --env work list --provider tencent
chatdns --env work records example.com --provider tencent -I
chatdns --env work records www.example.com --type A --provider tencent -I
chatdns ip --type local --local-ip-cidr 192.168.0.0/16

DNS 写入与 DDNS

chatdns set [FULL_DOMAIN]
├── --domain DOMAIN + --rr RR    # FULL_DOMAIN 的替代输入
├── --type TYPE                  # 默认 A
├── --value VALUE                # 必填，可由交互补齐
├── --ttl INTEGER                # 默认 600
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I

chatdns delete [FULL_DOMAIN]
├── --domain DOMAIN + --rr RR
├── --type TYPE                  # 必填，可由交互补齐
├── --value VALUE                # 可选，进一步收窄匹配记录
├── --yes                        # 非交互删除必须显式确认
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I

chatdns ddns [FULL_DOMAIN]
├── --domain DOMAIN + --rr RR
├── --ttl INTEGER                # 默认 600
├── --ip-type public|local       # 默认 public
├── --local-ip-cidr CIDR
├── --monitor                    # 不传时只执行一次
├── --interval SECONDS           # 监控间隔，默认 120
├── --max-retries INTEGER        # 默认 3
├── --retry-delay SECONDS        # 默认 5
├── --log-file PATH
├── --log-level LEVEL            # 默认 INFO
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I

set 调用 provider 的幂等设置路径；执行后仍应使用 records 回读。delete 会先列出匹配记录；非交互环境必须传 --yes，否则失败关闭。ddns 默认只运行一次，只有显式 --monitor 才持续轮询。

chatdns --env work set host.example.com -p tencent -t A -v 192.0.2.10 -I
chatdns --env work records host.example.com -p tencent -t A -I
chatdns --env work delete host.example.com -p tencent -t A -v 192.0.2.10 --yes -I

chatdns --env work ddns host.example.com -p tencent -I
chatdns --env work ddns host.example.com -p tencent --monitor --interval 120 -I

证书命令

chatdns cert apply
├── --domain DOMAIN              # 可重复；支持 SAN / wildcard
├── --email EMAIL                # Let's Encrypt 账号邮箱；短选项为 -e
├── --provider aliyun|tencent
├── --env PROFILE                # 此处只提供长选项，避免与 -e 邮箱冲突
├── --cert-dir DIR               # 显式证书根目录
├── --cert-path NAME             # 注册域名下的安全单段目录名
├── --staging                    # 使用 Let's Encrypt staging
├── --force                      # 忽略本地仍有效状态，强制申请/续期
├── --log-file PATH
├── --log-level LEVEL            # 默认 INFO
└── -i | -I

chatdns cert check [DOMAINS]...
├── --cert-dir DIR
├── --cert-path NAME
└── --provider aliyun|tencent

chatdns cert status [DOMAINS]...
├── --cert-dir DIR
├── --cert-path NAME
├── --expiring-within DAYS       # 默认 30
├── --format table|json          # 默认 table
└── --strict                     # selected leaf 非 valid 时非零退出

chatdns cert manifest [MANIFEST_PATH]    # 兼容入口，等同 show
chatdns cert manifest show [MANIFEST_PATH]
└── MANIFEST_PATH                # 默认 ./manifest.json，只读

chatdns cert manifest init [MANIFEST_PATH]
├── --cert-dir DIR               # 扫描证书根；默认 CHATDNS_CERT_DIR 或 $CHATARCH_HOME/certs
├── --cert-path NAME             # 可选限定 leaf 名称/后缀族
├── --from-store                 # 显式说明来源为本地证书根
├── --scripts-dir DIR            # 默认 manifest 同级 scripts/；只创建 README.md
├── --force                      # 覆盖已有 manifest
└── --format table|json          # 默认 table，输出创建回执

chatdns cert manifest validate [MANIFEST_PATH]
└── MANIFEST_PATH                # 校验 manifest 形状与本地证书文件引用

证书根目录优先级为：显式 --cert-dir，其次是 ChatEnv CHATDNS_CERT_DIR，最后是 $CHATARCH_HOME/certs。正式 leaf 位于：

<certificate-root>/<registered-domain>/<cert-path>/

省略 --cert-path 时从 default 开始；冲突时选择 default-2、default-3，完整规范化 SAN 集相同则复用已有 leaf。每个 leaf 只允许 cert.pem、chain.pem、fullchain.pem 和 privkey.pem。

cert apply 是高副作用命令。先用单独的 staging 输出目录验证 provider、DNS-01 和 ACME，再执行生产申请；不要让 Nginx 或其他服务引用 staging 证书。

chatdns --env work cert apply \
  -d '*.example.com' \
  -e admin@example.com \
  -p tencent \
  --staging \
  --cert-dir "$HOME/.cache/chatdns/staging-certs" \
  --cert-path default \
  -I

chatdns --env work cert apply \
  -d '*.example.com' \
  -e admin@example.com \
  -p tencent \
  --cert-path default \
  -I

chatdns cert check '*.example.com' --cert-path default

cert status 是回答“当前内部证书是什么情况”的主入口。cert manifest init 从证书根生成 Infra 工作区里的 manifest.json，并创建同级 scripts/README.md 说明手写脚本边界；它不把 manifest 写进 live cert root，也不会生成或执行服务器同步脚本。

Manifest 与脚本边界

Infra workspace
├── manifest.json          # chatdns cert manifest init 生成/覆盖
└── scripts/
    └── README.md          # ChatDNS 创建说明；具体同步脚本由模型/人按实际服务器手写

ChatDNS 不提供 chatdns cert script ... 命令。SSH 同步、Nginx 路径更新、nginx -t、reload 和 rollback 属于 Infra 现场操作，不固化进 ChatDNS。模型或操作者应读取 manifest.json 后，根据目标服务器的 SSH 入口、目录、supervisor/process manager、回滚策略和验证命令手写脚本。

Profile 与交互规则

Provider 选择顺序：

命令显式 --provider；
ChatEnv CHATDNS_PROVIDER；
默认 aliyun。

Provider 凭据来自对应的 Aliyun 或 Tencent named/active ChatEnv profile。可在顶层选择 profile：

chatdns --env work list -p tencent

list、ddns、set、records 和 delete 也接受命令级 --env/-e，且命令级值覆盖顶层值。cert apply 的 -e 是邮箱，因此 named profile 必须写成长选项 --env，或放在 cert 前面的顶层位置。

带 -i/-I 的命令遵循 ChatStyle 交互契约：-i 强制在可用终端补问缺失参数，-I 禁止交互并快速失败。自动化建议显式传全参数和 -I。

Python API 与 MCP 边界

CLI 不是唯一接口。包根导出的主要 Python API 包括：

chatdns
├── DNSClient
├── AliyunDNSClient
├── TencentDNSClient
├── DynamicIPUpdater
├── SSLCertUpdater
├── DNSClientType
├── create_dns_client
└── split_full_domain

安装 ChatDNS[mcp] 后，chatdns.mcp.register(mcp) 注册以下工具：

MCP 工具	类型
`dns_list_domains`	读
`dns_get_records`	读
`dns_add_record`	写
`dns_delete_record`	写
`dns_ddns_update`	写

MCP 工具不属于 chatdns CLI 子树。CLI 中刻意隐藏的 Certbot hook 也是内部兼容面，不作为稳定用户命令记录在本树中。

文档更新契约

只有已出现在实际 Click help 中的公共命令才能进入本树。
新命令必须同步更新中英文页面、顶层副作用表和相关快速开始。
隐藏命令、规划能力和远端 Infra 流程不能伪装为稳定 CLI。
命令选项以 chatdns <path> --help 和测试为最终依据。