enscli (CLI)

enscli is the CLI entry point to ENS. It wraps enssdk and the Omnigraph so you can resolve names, look up records, search domains, and run ad-hoc GraphQL queries against any ENSNode instance—without writing a script first.

It is designed to feel natural whether you drive it yourself or let an AI agent drive it: predictable arguments, machine-readable output, runtime schema introspection, and loud, structured errors.

Version compatibility with hosted instances

Our hosted ENSNode instances currently run ENSNode 1.15.1. ensskills is version-locked to the ENSNode suite—the Omnigraph schema and example queries the skills teach are bundled at a specific version—so pin an exact version (no ^ or ~) of ensskills, and drive the matching enscli, both at 1.15.1, to keep your agent's ENS knowledge and queries matched to the deployed API.

Quick start

No install step beyond npx:

# Namehash a Name
npx enscli namehash vitalik.eth

# Run a GraphQL query against the Omnigraph (default: mainnet)
npx enscli ensnode omnigraph '{ domain(by: { name: "vitalik.eth" }) { owner { address } } }'

Output contract

enscli is built for predictable parsing:

• JSON when piped, pretty in a TTY. When stdout is not a terminal (i.e. for agents), every command prints JSON; interactively you get a friendlier rendering. Force either with --output json or --output pretty.
• Structured errors. Failures print { "error": { "message": "…" } } to stderr and exit non-zero.
• Input hardening. Names, labels, and hashes containing control characters or ?/#/% are rejected before any network call.

Selecting an ENSNode instance

Most ensnode commands talk to an ENSNode instance. The target URL is resolved with this precedence:

--ensnode-url flag → ENSNODE_URL env → .env → namespace default.

--namespace (alias -n, or the NAMESPACE env var) selects a NameHash-hosted instance:

Namespace	Hosted default
mainnet	https://api.alpha.ensnode.io
sepolia	https://api.alpha-sepolia.ensnode.io
sepolia-v2	https://api.v2-sepolia.ensnode.io

npx enscli ensnode indexing-status --namespace sepolia
npx enscli ensnode indexing-status --ensnode-url http://localhost:4334

ENSRainbow commands resolve their URL similarly via --ensrainbow-url / ENSRAINBOW_URL.

Commands

ensnode omnigraph <query>

Send a raw GraphQL query—the string is the exact payload, so the schema doubles as your documentation.

npx enscli ensnode omnigraph 'query D($name: InterpretedName!) {
  domain(by: { name: $name }) {
    canonical { name { interpreted } }
    resolve { records { addresses(coinTypes: [60]) { address } } }
  }
}' --variables '{"name":"vitalik.eth"}'

Tip

GraphQL is naturally field-masked—select only the fields you need to keep responses small and avoid context bloat. Resolution lives in the graph: select Domain.resolve (records) and Account.resolve (primary names) inline rather than as separate calls.

ENS Omnigraph API The full data model, resolution, and query patterns.

ensnode omnigraph schema [Type[.field]]

Explore the Omnigraph schema offline (it ships with the CLI—no network):

npx enscli ensnode omnigraph schema                  # root query fields + major types
npx enscli ensnode omnigraph schema Domain           # a type's fields, with descriptions
npx enscli ensnode omnigraph schema Domain.canonical # a single field
npx enscli ensnode omnigraph schema --search primary # find types/fields by keyword

ensnode indexing-status

npx enscli ensnode indexing-status

ensrainbow heal <labelhash> / ensrainbow count

npx enscli ensrainbow heal 0xaf2caa1c2ca1d027f1ac823b529d0a67cd144264b2789fa2ea4d63a67c7103cc
npx enscli ensrainbow count

datasources identify <address>

Identify a well-known ENS contract by address—given 0xabc…, report which datasource contract it is across the namespace’s chains. Fully offline (the datasource catalog ships with the CLI). Accepts a bare address, a chain-scoped chainId:address, or full CAIP-10 eip155:chainId:address; --namespace (default mainnet) selects which namespace to search.

npx enscli datasources identify 0x00000000000c2e074ec69a0dfb2997ba6c7d2e1e         # bare address (mainnet)
npx enscli datasources identify 1:0x57f1887a8bf19b14fc0df6fd9b2acc9af147ea85       # scope to a chain
npx enscli datasources identify 0x94f523b8261b815b87effcf4d18e6abef18d6e4b -n sepolia  # another namespace

The result is { query, matches }. A miss is not an error: matches is [] with exit code 0, so branch on matches.length rather than the exit code. Contracts indexed only by event (no fixed address) can’t be identified and are never returned.

namehash <name> / labelhash <label>

npx enscli namehash vitalik.eth
npx enscli labelhash vitalik

For AI agents

enscli is the runtime that ensskills drive on your agent’s behalf. The omnigraph skill teaches an agent to author queries and run them through enscli, with the schema available via omnigraph schema. See the ensskills docs to install them.

Related

ensskills The agent-skill bundles that drive enscli on a developer's behalf.

enssdk The TypeScript SDK that enscli wraps.

ENS Omnigraph API The underlying GraphQL API enscli speaks to.