ChatDNS CLI Tree

This page maps the current public CLI from chatdns --help, command-level help, source, and tests. It answers two questions: how to invoke a command, and whether the invocation has external side effects.

Start with the Quick Start if provider profiles are not configured yet. See Certificate Storage and Creation Rules for certificate files and the remote infrastructure boundary.

Top-Level Commands

This tree comes from the currently registered Click surface and can be read back with 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.

Public top-level options:

Option	Purpose
`--tree`	Print the registered CLI command tree and exit
`--tree-brief`	Print the registered CLI command tree without parameter signatures and exit
`--version`	Print the ChatDNS version
`-e, --env PROFILE`	Select a named provider ChatEnv profile before the command
`--chatarch-home DIR`	Override `CHATARCH_HOME` for profile loading in this invocation
`--help`	Print top-level help

Side-Effect Levels

Level	Commands	Boundary
Read	`list`, `records`	Query provider APIs without changing DNS
Read	`ip`	Public mode calls IP detection services; local mode scans local interfaces
Read	`cert check`, `cert status`	Reads local certificates and computes renewal/inventory state; no ACME request
Read	`cert manifest show`, `cert manifest validate`	Reads and displays or validates a JSON manifest without modifying it
Local file write	`cert manifest init`	Scans the certificate root and writes an Infra `manifest.json` plus `scripts/README.md`; does not write the live cert root
DNS write	`set`, `delete`, `ddns`	Create, update, or delete provider records
DNS and certificate write	`cert apply`	Write `_acme-challenge` TXT records, run ACME, and install local PEM files

“Read” means no DNS or certificate mutation. It does not mean offline: list, records, and public ip still access the network.

Domain and Record Discovery

chatdns list
├── --provider aliyun|tencent    # Explicit provider; otherwise use CHATDNS_PROVIDER
├── --page INTEGER               # Default: 1
├── --page-size INTEGER          # Default: 20
└── --env PROFILE                # Command-level named provider profile

chatdns records [TARGET]
├── --domain DOMAIN              # Alternative input paired with --rr
├── --rr RR                      # Optional host-record filter
├── --type TYPE                  # Optional record-type filter
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I                      # Force or disable interaction

chatdns ip
├── --type public|local          # Default: public
└── --local-ip-cidr CIDR         # Filter interface addresses in local mode

records accepts either a managed zone such as example.com or a full hostname such as www.example.com. If a positional target and --domain/--rr are both present, the positional target wins and the CLI prints a warning.

list requests only the first page by default (--page 1 --page-size 20). For a complete zone inventory, raise --page-size explicitly (100 is the usual safe value for Aliyun/Tencent) and continue with --page until a short page is returned or the provider record count has been reconciled.

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 Writes and DDNS

chatdns set [FULL_DOMAIN]
├── --domain DOMAIN + --rr RR    # Alternative to FULL_DOMAIN
├── --type TYPE                  # Default: A
├── --value VALUE                # Required; interaction may supply it
├── --ttl INTEGER                # Default: 600
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I

chatdns delete [FULL_DOMAIN]
├── --domain DOMAIN + --rr RR
├── --type TYPE                  # Required; interaction may supply it
├── --value VALUE                # Optional exact-value filter
├── --yes                        # Required for non-interactive deletion
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I

chatdns ddns [FULL_DOMAIN]
├── --domain DOMAIN + --rr RR
├── --ttl INTEGER                # Default: 600
├── --ip-type public|local       # Default: public
├── --local-ip-cidr CIDR
├── --monitor                    # Omit for a one-shot update
├── --interval SECONDS           # Default: 120
├── --max-retries INTEGER        # Default: 3
├── --retry-delay SECONDS        # Default: 5
├── --log-file PATH
├── --log-level LEVEL            # Default: INFO
├── --provider aliyun|tencent
├── --env PROFILE
└── -i | -I

set uses the provider's idempotent update path; read the record back with records. delete displays matching records first and fails closed in non-interactive mode unless --yes is present. ddns runs once by default and loops only with explicit --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

Certificate Commands

chatdns cert apply
├── --domain DOMAIN              # Repeat for SANs and wildcards
├── --email EMAIL                # Let's Encrypt account email; short form is -e
├── --provider aliyun|tencent
├── --env PROFILE                # Long form only because -e is email here
├── --cert-dir DIR               # Explicit certificate root
├── --cert-path NAME             # Safe single-segment name under the registered domain
├── --staging                    # Use Let's Encrypt staging
├── --force                      # Force issuance/renewal despite a valid local certificate
├── --log-file PATH
├── --log-level LEVEL            # Default: 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       # Default: 30
├── --format table|json          # Default: table
└── --strict                     # Non-zero when a selected leaf is not valid

chatdns cert manifest [MANIFEST_PATH]    # Compatibility shorthand for show
chatdns cert manifest show [MANIFEST_PATH]
└── MANIFEST_PATH                # Default: ./manifest.json; read-only

chatdns cert manifest init [MANIFEST_PATH]
├── --cert-dir DIR               # Certificate root; defaults to CHATDNS_CERT_DIR or $CHATARCH_HOME/certs
├── --cert-path NAME             # Optional leaf-name / suffix-family filter
├── --from-store                 # Explicitly use the local certificate root as source
├── --scripts-dir DIR            # Default: sibling scripts/; creates README.md only
├── --force                      # Overwrite existing manifest
└── --format table|json          # Default: table creation receipt

chatdns cert manifest validate [MANIFEST_PATH]
└── MANIFEST_PATH                # Validate manifest shape and local certificate-file references

Certificate-root precedence is explicit --cert-dir, then ChatEnv CHATDNS_CERT_DIR, then $CHATARCH_HOME/certs. Production leaves live at:

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

Without --cert-path, allocation starts at default; collisions use default-2, default-3, and so on. An existing leaf is reused only for the same fully normalized SAN set. A leaf contains only cert.pem, chain.pem, fullchain.pem, and privkey.pem.

cert apply has high-impact side effects. Validate provider credentials, DNS-01, and ACME with a separate staging output root before production issuance. Never point Nginx or another consumer at staging certificates.

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 is the primary answer to “what is in the internal certificate store right now?”. cert manifest init generates an Infra-workspace manifest.json from the certificate root and creates a sibling scripts/README.md that explains the manual-script boundary. It does not write the manifest into the live certificate root and does not generate or execute server sync scripts.

Manifest And Script Boundary

Infra workspace
├── manifest.json          # generated/overwritten by chatdns cert manifest init
└── scripts/
    └── README.md          # ChatDNS-created note; models/operators hand-write real sync scripts per server

ChatDNS does not provide chatdns cert script ... commands. SSH synchronization, Nginx path updates, nginx -t, reload, and rollback are Infra-site operations, not hard-coded ChatDNS behavior. A model or operator should read manifest.json and then hand-write scripts from the target server's SSH entrypoint, paths, supervisor/process manager, rollback policy, and verification commands.

Profiles and Interaction

Provider selection order:

explicit command --provider;
ChatEnv CHATDNS_PROVIDER;
default aliyun.

Provider credentials come from the matching Aliyun or Tencent active/named ChatEnv profile. A profile can be selected globally:

chatdns --env work list -p tencent

list, ddns, set, records, and delete also accept command-level --env/-e, and the command-level value overrides the global value. On cert apply, -e means email, so use long-form --env or place the global profile before cert.

Commands with -i/-I follow the ChatStyle interaction contract: -i forces prompts when a terminal is available; -I disables prompts and fails fast when required values are missing. Automation should pass complete inputs and -I.

Python API and MCP Boundary

The CLI is not the only interface. Main package-root Python exports include:

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

With ChatDNS[mcp] installed, chatdns.mcp.register(mcp) registers:

MCP tool	Type
`dns_list_domains`	read
`dns_get_records`	read
`dns_add_record`	write
`dns_delete_record`	write
`dns_ddns_update`	write

MCP tools are not chatdns subcommands. Intentionally hidden Certbot hooks are internal compatibility surfaces and are not documented as stable user commands in this tree.

Documentation Update Contract

Add a command here only after it appears in actual public Click help.
Keep the English and Chinese pages, side-effect table, and related quick-start flows synchronized.
Do not present hidden commands, planned capabilities, or remote Infra operations as stable CLI.
Treat chatdns <path> --help and tests as the final authority for options.