IC Query

Query Internet Computer metadata from the command line.

IC Query provides the icq executable for read-only Internet Computer metadata queries. It gives Canic and other deployment tooling a simple CLI for looking up NNS and SNS metadata without embedding registry-query logic directly.

RustCLINNS/SNS metadataMITUsed by Canic

View repository See Canic

The problem

Deployment tools need live IC metadata

Canister orchestration often needs answers from the Internet Computer itself: registry version, subnet inventory, node providers, node operators, data centers, topology coverage, and deployed SNS instances.

Without a dedicated metadata tool, every project has to either duplicate registry adapters or hard-code assumptions that can drift from mainnet reality.

why icq

canic needs to deploy intelligently

but first it may need to know:
  - which subnets exist
  - what nodes and providers are active
  - what data centers are represented
  - what SNS projects are deployed
  - whether cached topology data is fresh

ic-query gives that metadata through a standalone CLI

How it works

Ask, cache, refresh, integrate

Read-only metadata queries

Provides the icq command for querying IC metadata without mutating canisters, registries, or deployment state.

NNS registry lookups

Supports registry version, subnet catalog lookup, node inventory, provider/operator/data-center inventory, and topology reports.

SNS discovery

Supports deployed SNS listings and SNS info queries for mainnet projects.

Project-local cache

Stores NNS query cache files under .icq/, with refresh commands that atomically replace stale cache data.

Where it shines

Most useful for deployment systems, canister orchestration, topology reporting, CI checks, and frameworks like Canic that need IC metadata without linking registry-specific query code.

Quick start

Install once, then query IC metadata

Install from crates.io, or build from a local checkout. Then query metadata directly — most commands support JSON output for scripting and CI.

shell

# install from crates.io
cargo install ic-query

# or from the checkout
make install

# example commands
icq nns registry version
icq nns subnet list
icq nns topology summary
icq sns list

# most commands support JSON output
icq --network ic nns subnet info ryjl3-tyaaa-aaaaa-aaaba-cai --format json

Command families

One CLI, NNS and SNS

The icq command groups its subcommands into NNS registry and topology families plus SNS discovery, each with consistent list, info, and refresh verbs.

icq

icq nns registry version
icq nns subnet [list|info|refresh]
icq nns node [list|info|refresh]
icq nns node-provider [list|info|refresh]
icq nns node-operator [list|info|refresh]
icq nns data-center [list|info|refresh]
icq nns topology [summary|coverage|versions|health|
                 gaps|capacity|regions|providers|refresh]
icq sns [list|info]

Canic integration

Metadata lookup for Canic

IC Query is installed alongside Canic so Canic can call icq when it needs Internet Computer metadata. This keeps Canic focused on orchestration and deployment while IC Query owns registry and SNS lookup behavior.

See Canic

Project status

IC Query is at version 0.0.3. It was separated out of Canic and expanded into a standalone metadata CLI, and Canic relies on it for NNS and SNS lookups.

Inspect IC metadata without coupling it to deployment code

Use IC Query as a standalone CLI, or call it from deployment and orchestration tooling when live IC metadata is needed.

Open IC Query on GitHub ↗ See Canic