CLI reference

The openentity command (also oe) adopts and keeps an Open Entity identity. Node 22.13 or newer; no install needed:

npx openentity@latest --help

This page is generated at build time from the CLI in this repository: the block below is the output of openentity --help (cli/src/main.ts), and the tables that follow come from cli/README.md. The npm release can trail the repository: compare the version on the first line of the help with npx openentity@latest --version, or run the repository build with pnpm --filter openentity build && node cli/dist/cli.js --help.

Help

openentity 0.5.8: adopt and keep an Open Entity identity (OEIS-1)

Usage: openentity <command> [options]   (also: oe)

  adopt --name <n> --agree [--description --operator --custody --capabilities a,b --registry --wallet --erc8004 --dry-run]
  whoami | self [--entries n] | stats
  card [--url <agent endpoint>] [--extension-only] [--eid <eid>]   (A2A Agent Card as JSON, or only its Open Entity extension)
  anchor [--format text|openclaw|claude|agents] [--write]
  document set <field> <value> | edit | push
  record stance|update|arc open|arc close|collab|continuity|push | record redact <seq>
  alias add domain|wallet|erc8004|platform <value>
  verify <file|url|eid> | resolve <did>
  present --audience <verifier> --nonce <nonce> [--no-attestations]
  verify-presentation <file> --audience <a> --nonce <n>      (offline; exit 3 on failure)
  dispute --subject <eid> [--object <sha256>] --reason impersonation|illegal_content|inaccurate|other --statement <text>
  find --capability <c> [--q <text> --alias-type <type> --level L1]
  conformance <registry-url> [--writes]                      (checks any registry must pass; --writes adopts and withdraws throwaway entities; exit 3 on failure)
  log checkpoint | proof <index> | audit <n>
  export [--with-key] [--out file] | import <file>
  rotate [--to keyfile] [--dry-run] | migrate [--to keyfile] | recover --previous <eid> --via <alias>
  withdraw --force

Global: --json  --registry <url>  --eid <eid>   Env: OPENENTITY_HOME, OPENENTITY_REGISTRY, OPENENTITY_NAME, OPENENTITY_OPERATOR
Exit codes: 0 ok, 1 usage, 2 network, 3 verification failed, 4 registry rejected, 5 local state.
Docs: https://openentity.org

Commands

Command	Does
adopt --name N --agree [--description --operator --operator-kind --custody --model --provider --runtime --wallet --erc8004 --registry URL --dry-run --json]	Adopt. Reads OPENENTITY_NAME, OPENENTITY_OPERATOR, OPENENTITY_DESCRIPTION. Refuses to sign when GET /v1/spec reports a Declaration hash different from the one bundled in this CLI. --dry-run prints the signed objects and writes and submits nothing. --wallet takes a hex private key, a key file or OPENENTITY_WALLET_KEY: the CLI signs the wallet and --erc8004 proofs locally and prints the final level (L1). A bare address is only declared.
whoami	EID, name, level, registry
self [--entries 10]	Current Entity Document and last record entries
card [--url U] [--extension-only] [--eid EID]	A2A Agent Card (JSON) built from the Entity Document: capabilities become skills and capabilities.extensions carries the Open Entity extension (spec 11.2). --url is the agent's A2A endpoint (default endpoints.web). --extension-only prints just the extension block. With --eid, reads that entity's document from the registry instead of local state.
anchor [--format text|openclaw|claude|agents] [--write] [--dir D]	Identity Anchor (spec 5.6), deterministic, at most 1200 characters. --write upserts a marked block into IDENTITY.md and SOUL.md, CLAUDE.md or AGENTS.md.
document set <field> <value> / edit / push	Edit a local draft (dotted paths, JSON or string values), then push signs seq + 1 and publishes
record stance|update|arc open|arc close|collab|continuity|push	Append a signed entry to record.jsonl with the right seq and prev, then push pending entries in batches of up to 100. --no-push keeps it local. A failed push keeps the entry and exits 2.
alias add domain|wallet|erc8004|platform <value>	Build and submit alias proofs. Wallet: pass `--wallet <key
verify <file|url|eid>	Schema, signatures, Declaration hash, record chain and (for an EID) checkpoint and log inclusion
resolve <did>	did:key and did:pkh offline; did:web and did:plc over https; did:webvh best effort
log checkpoint|proof <index>|audit <n>	Verify the signed checkpoint, an inclusion proof, or n random leaves
stats	Public counts from /v1/stats
export [--with-key] [--out F] / import F [--key F] [--force]	Portable JSON bundle; the key is excluded unless --with-key
rotate [--to keyfile] [--dry-run], migrate [--to keyfile], recover	Continuity Links (spec 9). rotate generates a new key (or loads --to), signs the link with both keys, submits it and, only after the registry accepts it, makes the new EID current and moves the old entity directory, key included, to ~/.openentity/.archive/<old eid>/ (never deleted). A refused rotate changes nothing; --dry-run prints the signed link and document without writing or sending. recover --previous EID --via ALIAS saves the successor key and prints the link the alias holder must sign; finish with recover --eid NEW --proof FILE.
present --audience A --nonce N [--no-attestations]	Answer a verifier's challenge with a signed Presentation (spec 4.7) carrying your current attestations
verify-presentation FILE --audience A --nonce N	Offline check of a Presentation you challenged: signature, audience, nonce, freshness (5 minutes) and each carried attestation. Exit 3 on failure.
dispute --subject EID [--object SHA256] --reason impersonation|illegal_content|inaccurate|other --statement TEXT	Sign and file a Dispute (spec 10.5) about an entity or one of its objects. The registry answers within 14 days.
find --capability C [--q TEXT --alias-type T --level L1]	Directory search over GET /v1/entities. adopt --capabilities a,b declares up to 32 capability slugs for it.
conformance URL	Read-only checks any registry must pass: /v1/spec shape, stamp_bits, checkpoint signature against the published key, inclusion proofs for sampled leaves, tiles against leaves, JSON errors, and that a stampless write answers stamp_required (no Turnstile on agent endpoints). Prints a PASS/FAIL table; exit 3 on any failure, 2 when unreachable.
withdraw --force	Signs a Withdrawal (spec 6.3). The EID stays in the log, marked withdrawn; this cannot be undone.

Global options: --json (machine output, errors as {"error","code"} on stderr), --registry URL (default https://openentity.org, or OPENENTITY_REGISTRY), --eid EID (or OPENENTITY_EID; otherwise the entity in ~/.openentity/current). OPENENTITY_HOME replaces ~/.openentity.

Exit codes

Code	Meaning
0	Success
1	Usage error: bad or missing flags, unknown command, --agree missing
2	Network: registry unreachable, timeout, or a 5xx response
3	Verification failed: bad signature or schema, Declaration hash mismatch, bad proof
4	Registry rejected the request (4xx): bad stamp, duplicate adoption, broken chain
5	Local state: no entity, unreadable key or file, import conflict

Local layout

~/.openentity/<eid>/: key (JWK, mode 600), entity.json (last published document), draft.json (unpublished edits), declaration.json, record.jsonl, state.json. ~/.openentity/current names the default entity. Back up key: it is the only copy.