Command reference

Full reference for the dnsid command surface. Every command supports the global flags: --output json|pretty to choose the output format, --server <url> to choose the registry (default: the DNSid Local registry at http://127.0.0.1:7755, or DNSID_SERVER), --config-dir <directory> for the directory holding agent configuration and private keys (default: ~/.dnsid, or DNSID_CONFIG_DIR), --debug to print HTTP requests and responses, and --version/-v.

Commands fall into two planes: protocol commands (record inspect, record verify, local *) work against any DNSid domain, while registry commands (agent, status, verify, challenge, revoke, record publish) drive the registry that --server points at. Against DNSid Local they need no credentials. Nothing here requires an account.

dnsid agent list

Lists the agents registered with the current registry.

dnsid status

dnsid status [--domain <fqdn>|--agent-id <id>] — reads registration status, identity-record expiry, challenge state, and remediation details. Registration workflow status is distinct from the live protocol status served at the record’s su= URL; Status & freshness explains how the two relate and how quickly they update.

dnsid verify

dnsid verify [--domain <fqdn>|--agent-id <id>] — triggers the registry’s verification workflow (TLS, JWKS format, proof-of-possession) and prints the status command to poll next. Expect the agent to move to VERIFIED / READY once checks pass and any challenge is answered.

dnsid challenge

dnsid challenge [--domain <fqdn>|--agent-id <id>] [--key <path>] — signs and submits the current proof-of-possession challenge for a domain, using the local private key. --key points at the Ed25519 private key PEM; the default is private.pem in the agent’s config directory.

dnsid log issue

dnsid log issue [--domain <fqdn>|--agent-id <id>] [--key <path>] — asks the registry to prepare the agent’s ISSUANCE event, countersigns it with the agent’s operational key, and submits it to the transparency log. This is the step that binds the agent’s key to its identity in the lifecycle log and, on DNSid Local, publishes the agent’s _dnsid record in the local zone and moves it to READY; dnsid status prints it as the next action when it is still pending. --key points at the operational private JWK; the default is private.jwk in the agent’s config directory.

dnsid export

dnsid export --output <path> (or -o) — bundles the selected agent’s configuration and key material into a gzipped tar archive: a root config.json pointing to <domain>/config.json, the agent’s private.pem, public.jwk, private.jwk, and its accountable-entity key when configured.

The archive is written with 0600 permissions and holds unencrypted private keys, so treat it as a secret in transit and at rest. Restore it on the target machine with tar xzf <archive> -C <config-dir>; the CLI reads credentials only from its config directory, which export prints when it finishes.

dnsid revoke

dnsid revoke --reason owner_request|key_compromise [--domain <fqdn>|--agent-id <id>] [--yes] — permanently revokes the selected identity, with an interactive confirmation unless --yes.

What to expect when you revoke:

• The agent’s state becomes REVOKED immediately — the status URL starts serving it right away, and counterparty verification fails from that point on. How fast relying parties observe it depends on their caches; see Status & freshness for propagation behavior and cache guidance.
• A signed revocation event is recorded in the agent’s lifecycle log, so the revocation is independently verifiable — see Transparency log.
• REVOKED is terminal. There is no un-revoke in the CLI or SDKs.
• The domain is reusable. You can register a new agent identity on the same domain afterwards — new keys, new agent ID, new lifecycle. The revoked identity itself stays revoked.

Identity-record commands

• dnsid record publish --domain <fqdn> [--entity-key <path>] — fetches canonical record content, signs it locally, and prints the DNS records for you to publish (see Publish self-managed records). --entity-key points at the accountable-entity private JWK; the default is the entity_key_path in the agent’s config.json.
• dnsid record inspect --domain <fqdn> [--dns-server <host[:port]>] — resolves and prints the _dnsid TXT record for any FQDN over real DNS. --dns-server (or DNSID_DNS_SERVER) queries a specific resolver instead of the system one; dnsid local env sets it for the local network.
• dnsid record verify [--domain <fqdn>] [--dns-server <host[:port]>] [--ca-bundle <path>] [--log-policy <path>] [--log-trust-profile <path>] — runs full SDK verification (DNS, JWKS, record signature, status, policy checks) exactly as a counterparty would. --domain defaults to the locally selected agent. --ca-bundle (or DNSID_CA_BUNDLE) adds a PEM CA bundle for private or test CAs, such as the DNSid Local CA. --log-policy and --log-trust-profile point at a trusted C2SP tlog-policy document or trust profile for the transparency log checks. Result semantics are documented in Verification results.

DNSid Local commands

The dnsid local family (up, run, agent list|add|ensure|remove, env, down, reset) runs a complete local DNSid network in Docker — no account, no real DNS. Each local agent has a config.json with its identity and publication settings, including log_ref, status_url, and ku_url, alongside its key files. dnsid local env <name> exports the settings the SDKs need for local DNS, CA, and log verification. The DNSid Local quickstart covers the workflow and commonly used commands.

dnsid version

dnsid version prints the version this binary was built from and the commit it was built at. The global --version/-v flag prints the same value; both honor --output json.