ic-query 0.17.1: query the Internet Computer from your terminal
ic-query is a read-only toolkit for asking the Internet Computer what is deployed, how it is configured, and what its public governance and ledger state looks like.
The repository contains two crates:
-
ic-query, a Rust library of typed request/report models, renderers, cache logic, and live-source adapters. -
ic-query-cli, which installs theicqcommand used throughout this post.
The CLI currently covers three broad areas:
| Area | What you can inspect |
|---|---|
| NNS | Registry version, governance settings and metrics, subnets, nodes, providers, operators, data centres, proposals, public neurons, and joined topology reports |
| SNS | Deployed SNS projects, project metadata, tokens, parameters, canisters and health, proposals, and neurons |
| ICRC | Generic ledger capabilities, token metadata, index discovery, ledger history, archives, certified tips, balances, allowances, and complete account-history caches |
Everything is read-only. Most calls are ordinary query calls. The SNS canister-health report uses a read-only ingress update call with update_canister_list=false, because that is how the SNS Root API exposes its summary.
This guide targets
icq 0.17.1at commit20defa9, checked against mainnet on 30 July 2026. Output below is representative and abridged: IDs, counts, versions, balances, timestamps, and health state will naturally change.
Install it
From crates.io:
$ cargo install ic-query-cli
$ icq --version
icq 0.17.1
Or from the repository:
$ git clone https://github.com/dragginzgame/ic-query.git
$ cd ic-query
$ make install
$ icq --help
icq 0.17.1
Internet Computer metadata query CLI
Commands:
icrc Inspect generic ICRC ledger and account metadata
nns Inspect NNS metadata
sns Inspect SNS metadata
The old announcement used cargo install ic-query; the current executable package is ic-query-cli.
A few conventions before we query
Text is the default format. Almost every report can instead return a machine-readable schema-versioned document:
$ icq --network ic nns subnet info ryjl3-tyaaa-aaaaa-aaaba-cai --format json
{
"schema_version": 1,
"network": "ic",
"subnet_id": "tdb26-jop6k-aogll-7ltgs-...",
"kind": "system",
...
}
All current report schemas are version 1. Before 1.0, the project may replace a shape without incrementally preserving older pre-1.0 shapes.
The top-level --network option must appear before nns or sns. Only ic is currently supported:
$ icq --network ic nns registry version
network: ic
registry_canister_id: rwlgt-iiaaa-aaaaa-aaaaa-cai
registry_version: 62718
source_endpoint: https://icp-api.io
ICRC commands identify a ledger directly and therefore reject --network; use --source-endpoint on the ICRC command instead.
The examples use:
-
ryjl3-tyaaa-aaaaa-aaaba-cai— ICP ledger -
mxzaz-hqaaa-aaaar-qaada-cai— ckBTC ledger -
qhbym-qaaaa-aaaaa-aaafq-cai— official ICP index -
1— the first SNS in the deployed-SNS list, Dragginz
Commands have one of five data modes:
-
live — call the IC without using a report cache;
-
cache-backed — create a complete cache when missing, then query it;
-
cache-preferred — use a complete cache when present, otherwise query live;
-
local-only — inspect an existing cache without making a network request;
-
forced refresh — fetch and validate a complete snapshot, then replace the cache atomically.
The cache root is the first non-empty value among ICQ_CACHE_ROOT, $XDG_CACHE_HOME/ic-query, and $HOME/.cache/ic-query. ICQ_CACHE_ROOT must be absolute. The CLI does not search for dfx.json, icp.yaml, or old project-local .icq directories.
NNS queries
Registry
1. Current registry version
This is the smallest useful connectivity and freshness check.
$ icq nns registry version
network: ic
registry_canister_id: rwlgt-iiaaa-aaaaa-aaaaa-cai
registry_version: 62718
fetched_at: 2026-07-30T18:03:20Z
source_endpoint: https://icp-api.io
fetched_by: get_latest_version
Native NNS Governance reports
These four commands query the NNS Governance canister directly and do not use the inventory cache.
2. Network economics
$ icq nns governance economics
network: ic
governance_canister_id: rrkah-fqaaa-aaaaa-aaaaq-cai
minimum_neuron_stake_e8s: 100_000_000
maximum_number_of_proposals_with_ballots: 100
neuron_management_fee_per_proposal_e8s: 100_000_000
reject_cost_e8s: 5_000_000_000
transaction_fee_e8s: 10_000
...
source_endpoint: https://icp-api.io
3. Governance metrics
$ icq nns governance metrics
network: ic
governance_canister_id: rrkah-fqaaa-aaaaa-aaaaq-cai
total_supply_icp: 555228683
total_staked_e8s: 28_880_011_191_799_641
total_maturity_e8s_equivalent: 9_533_820_463_137_469
garbage_collectable_neurons_count: 344545
...
source_endpoint: https://icp-api.io
4. Latest reward event
$ icq nns governance reward-event
network: ic
governance_canister_id: rrkah-fqaaa-aaaaa-aaaaq-cai
day_after_genesis: 1907
actual_timestamp_seconds: 1785427201
total_available_e8s_equivalent: 5_392_047_543_044
distributed_e8s_equivalent: 4_188_793_140_978
settled_proposals: 143132..143143
5. Maturity modulation
$ icq nns governance maturity-modulation
network: ic
governance_canister_id: rrkah-fqaaa-aaaaa-aaaaq-cai
current_basis_points: -911
current_percent: -9.11
updated_at_timestamp_seconds: 1785369600
source_endpoint: https://icp-api.io
Registry inventory: subnets, nodes, providers, operators, and data centres
Each inventory family has the same three operations:
-
listreads the complete cached inventory, refreshing it if absent; -
inforesolves a full ID or unique prefix and prints one record; -
refreshforcibly recollects and atomically replaces that family’s cache.
Every refresh also supports --dry-run, --output PATH, and --lock-stale-after 30m. --dry-run performs collection and validation but does not publish the cache.
Subnets
6. List subnets
Filter with --kind application|cloud_engine|system|unknown, --specialization none|fiduciary|european|unknown, or --geo global|europe|unknown. Add --show-ranges, --verbose, --range-limit N, and --range-offset N when you need canister ranges.
$ icq nns subnet list --kind system --verbose
catalog_path: /home/alice/.cache/ic-query/subnet-catalog/ic/catalog.json
stale_reason: fresh
SUBNET KIND SPECIALIZATION GEO NODES CHARGES RANGES VERSION
------------ ------- --------------- ------- ------ -------- ------- -------
tdb26-jop6k… system none global 40 no 2 62718
uzr34-akd3s… system none global 34 no 2 62718
...
7. Inspect a subnet — or find the subnet for a canister
The input may be a subnet principal, a unique prefix, or a canister principal. Use --as subnet or --as canister to disambiguate.
$ icq nns subnet info ryjl3-tyaaa-aaaaa-aaaba-cai --as canister
input_principal: ryjl3-tyaaa-aaaaa-aaaba-cai
resolved_as: canister
resolved_from: routing_range
subnet_principal: tdb26-jop6k-aogll-7ltgs-...
subnet_kind: system
node_count: 40
charges_apply_to_subject: no
registry_version: 62718
8. Refresh subnets
$ icq nns subnet refresh
network: ic
cache_path: .../subnet-catalog/ic/catalog.json
registry_canister_id: rwlgt-iiaaa-aaaaa-aaaaa-cai
registry_version: 62718
dry_run: no
wrote_cache: yes
replaced_existing_cache: yes
subnet_count: 84
Nodes
9. List nodes
You can combine --subnet, --kind, --data-center, --node-provider, and --node-operator. --verbose expands IDs.
$ icq nns node list --subnet tdb26 --verbose
source_endpoint: https://icp-api.io
fetched_by: ic-query
NODE OPERATOR PROVIDER SUBNET KIND DC REGISTRY_VERSION
---------- ---------- ---------- ---------- ------- ---- ----------------
24fcm-3on… mbnsu-w4x… 4jjya-hly… tdb26-jop… system bt1 62718
...
10. Inspect a node
$ icq nns node info 24fcm
input: 24fcm
resolved_from: node_principal_prefix
node_principal: 24fcm-3onfs-...
node_operator_principal: mbnsu-w4xfc-...
node_provider_principal: 4jjya-hlyyc-...
subnet_principal: tdb26-jop6k-...
subnet_kind: system
data_center_id: bt1
registry_version: 62718
network: ic
11. Refresh nodes
$ icq nns node refresh
network: ic
cache_path: .../node/ic/nodes.json
registry_version: 62718
dry_run: no
wrote_cache: yes
replaced_existing_cache: yes
node_count: 814
Node providers
12. List node providers
$ icq nns node-provider list --verbose
source_endpoint: https://icp-api.io
fetched_by: ic-query
NODE_PROVIDER NODES REWARD_ACCOUNT REGISTRY_VERSION
-------------- ------ --------------- ----------------
4jjya-hlyyc-… 9 - 62718
...
13. Inspect a node provider
$ icq nns node-provider info 4jjya
input: 4jjya
resolved_from: node_provider_principal_prefix
node_provider_principal: 4jjya-hlyyc-...
node_count: 9
reward_account_hex: -
governance_canister_id: rrkah-fqaaa-aaaaa-aaaaq-cai
registry_version: 62718
network: ic
14. Refresh node providers
$ icq nns node-provider refresh
network: ic
cache_path: .../node-provider/ic/providers.json
registry_version: 62718
dry_run: no
wrote_cache: yes
replaced_existing_cache: yes
node_provider_count: 103
Node operators
15. List node operators
$ icq nns node-operator list --verbose
source_endpoint: https://icp-api.io
fetched_by: ic-query
NODE_OPERATOR PROVIDER NODES ALLOWANCE DC REGISTRY_VERSION
-------------- ---------- ------ ---------- ---- ----------------
mbnsu-w4xfc-… 4jjya-hly… 4 6 bt1 62719
...
16. Inspect a node operator
$ icq nns node-operator info mbnsu
input: mbnsu
resolved_from: node_operator_principal_prefix
node_operator_principal: mbnsu-w4xfc-...
node_provider_principal: 4jjya-hlyyc-...
node_count: 4
node_allowance: 6
data_center_id: bt1
registry_version: 62719
network: ic
17. Refresh node operators
$ icq nns node-operator refresh
network: ic
cache_path: .../node-operator/ic/operators.json
registry_version: 62719
dry_run: no
wrote_cache: yes
replaced_existing_cache: yes
node_operator_count: 135
Data centres
The command spelling is data-center, while output follows the repository’s data_center_* field naming.
18. List data centres
$ icq nns data-center list --verbose
source_endpoint: https://icp-api.io
fetched_by: ic-query
DC REGION OWNER OPS PROVIDERS NODES REGISTRY_VERSION
---- ------------------ --------- ---- ---------- ------ ----------------
bt1 Europe,LT,Vilnius Baltneta 2 2 5 62719
...
19. Inspect a data centre
$ icq nns data-center info bt1
input: bt1
resolved_from: data_center_id
data_center_id: bt1
region: Europe,LT,Vilnius
owner: Baltneta
node_operator_count: 2
node_provider_count: 2
node_count: 5
registry_version: 62719
network: ic
20. Refresh data centres
$ icq nns data-center refresh
network: ic
cache_path: .../data-center/ic/data-centers.json
registry_version: 62719
dry_run: no
wrote_cache: yes
replaced_existing_cache: yes
data_center_count: 100
NNS proposals
Proposal lists are cache-preferred and default to 25 rows, with a maximum view limit of 100. A complete cache is used when present; otherwise the command makes a bounded live query. refresh explicitly builds the complete snapshot.
Useful list filters:
-
--before ID -
--status any|open|rejected|adopted|executed|failed -
--reward-status any|accept-votes|ready-to-settle|settled|ineligible -
--topicwith NNS topics such asgovernance,network-economics,subnet-management,node-admin,node-provider-rewards,ic-os-version-election, oric-os-version-deployment -
--proposer NEURON_ID -
--query TEXT -
--sort api|id|status|reward-status|topic|proposer|title|action|yes|no|total-votes|tally-time|voting-power|ballots|reject-cost|reward-round|proposed|deadline|decided|executed|failed -
--asc,--desc, and--verbose
21. List NNS proposals
$ icq nns proposal list --status open --limit 3
network: ic
data_source: live
requested_limit: 3
status_filter: open
proposal_count: 3
ID TOPIC STATUS TITLE
------ ------------------------ ------ ----------------------------------------
143241 ic-os-version-deployment open Update subnet pzp6e-...
143240 ic-os-version-deployment open Update subnet eq6en-...
143239 ic-os-version-deployment open Update subnet snjp4-...
22. Inspect one NNS proposal
Add --ballots to print the public ballot table and --verbose to avoid normal text truncation.
$ icq nns proposal info 143241 --ballots
network: ic
proposal_id: 143241
proposer_neuron_id: 80
topic: ic-os-version-deployment
status: open
reward_status: accept-votes
action: execute-nns-function
title: Update subnet pzp6e-...
deadline: 2026-08-03T...
ballots:
NEURON_ID VOTE VOTING_POWER
------------------- ---- ------------
14315117116521128082 yes 173000000
...
23. Force a complete NNS proposal refresh
Use --page-size N and optionally --max-pages N. A capped or failed refresh records its attempt but does not replace the prior complete cache.
$ icq nns proposal refresh --page-size 100
network: ic
governance_canister_id: rrkah-fqaaa-aaaaa-aaaaq-cai
proposal_count: ...
page_size: 100
page_count: ...
complete: yes
replaced_existing_cache: yes
wrote_cache: yes
attempt_finalized: yes
cache_path: .../nns/ic/governance/proposals/full.json
24. List local NNS proposal caches
This command is strictly local.
$ icq nns proposal cache list
network: ic
cache_root: /home/alice/.cache/ic-query
cache_count: 1
STATUS GOVERNANCE ROWS PAGES FETCHED_AT
valid rrkah-fqaaa-aaaaa-aaaaq-cai ... ... 2026-07-30T...
25. Inspect NNS proposal-cache status
$ icq nns proposal cache status
network: ic
cache_root: /home/alice/.cache/ic-query
found: yes
cache_status: valid
complete: yes
row_count: ...
page_count: ...
cache_path: .../nns/ic/governance/proposals/full.json
latest_attempt_status: complete
Public NNS neurons
Only publicly readable neuron views are available. List and info are cache-preferred: they use a complete local public index when present and otherwise make a live query. The governance API does not expose snapshot versioning, so completed caches explicitly report point_in_time_guaranteed: no.
26. List public NNS neurons
$ icq nns neuron list --limit 3
network: ic
requested_limit: 3
data_source: live
point_in_time_guaranteed: no
neuron_count: 3
NEURON_ID VISIBILITY STAKE DISSOLVE_DELAY
--------- ---------- --------- --------------
1 private ... ...
2 public 100.00 ICP 730.50d
3 private ... ...
27. Inspect one public NNS neuron
$ icq nns neuron info 2 --verbose
network: ic
neuron_id: 2
state: not-dissolving
visibility: public
stake: 100.00 ICP
age: 1907.09d
dissolve_delay: 730.50d
recent_ballot_count: 77
...
28. Refresh the complete public-neuron index
$ icq nns neuron refresh --page-size 300
network: ic
governance_canister_id: rrkah-fqaaa-aaaaa-aaaaq-cai
neuron_count: ...
page_size: 300
page_count: ...
complete: yes
point_in_time_guaranteed: no
replaced_existing_cache: yes
attempt_finalized: yes
cache_path: .../nns/ic/governance/neurons/full.json
29. Inspect public-neuron cache status
$ icq nns neuron cache status
network: ic
cache_root: /home/alice/.cache/ic-query
found: yes
cache_status: valid
complete: yes
point_in_time_guaranteed: no
row_count: ...
cache_path: .../nns/ic/governance/neurons/full.json