ar.io DocumentationThe ar-io-node CLI
Release Requirement: the ar-io-node CLI requires gateway Release 85 or
later.
ar-io-node is the gateway's command-line tool. Its own commands build and check index bands and fill and check a gateway's L1 index. Any other command runs as the ar.io CLI from @ar.io/sdk.
It runs in the core image. From the gateway's directory (where .env and docker-compose.yaml are), ./tools/ar-io-node runs it in the image named by CORE_IMAGE_TAG, so the host needs only Docker. It mounts only what a command needs.
./tools/ar-io-node --help
./tools/ar-io-node network-help # the ar.io commands it runs for youOutput
It follows the ar.io CLI's conventions, so a script or an agent can drive it:
- A command's result is one JSON value on stdout, with exit code
0. - An error goes to stderr, with exit code
1(130if you interrupt it). A check that fails prints its full result, as JSON, on stderr. - Logs go to stderr too, so stdout can always be parsed.
Read stdout and branch on the exit code; don't parse stderr for success. Band commands never prompt and never take a key.
Commands
| Command | What it does |
|---|---|
index-band-build | Builds one root-TX band from CSV records, checks a sample of its headers against their root transactions, and publishes it for the index-swarm sidecar |
index-band-verify | Runs that header check on any built or installed band |
index-band-export | Writes one source's root-TX records for a height range as the CSV index-band-build reads. The source is this gateway's ClickHouse or SQLite, a peer's ClickHouse, or an overlay directory of CSV files |
index-l1-import --fill | Fills the gateway's core.db from installed parquet-l1 bands while the gateway runs, writing only the heights missing beneath what it indexed itself. Core runs this by itself with L1_BAND_IMPORT_ENABLED=true |
index-l1-import | Without --fill, imports the bands with the gateway stopped. Faster, but only for a new core.db the gateway has never run on |
index-l1-verify | Checks an L1 index against what the chain commits to: a gateway's own core.db (--core-db), or a directory of bands with no gateway at all (--bands-dir). Read-only |
index-l1-audit | Checks the blocks index-l1-verify has to skip, those holding a format-1 transaction with data, by fetching a sample of that data and recomputing each block's tx_root. Read-only |
| Any other command | Runs as the ar.io CLI of the @ar.io/sdk the gateway carries, with the same arguments, output and exit code. For example, ./tools/ar-io-node get-gateway --address <wallet> |
The ar.io commands use the SDK's own network defaults and flags, not your gateway's settings. For one that signs, prefer --wallet-file to --private-key: an inline key is visible in ps and docker inspect.
For how these fit together, see Bootstrap from L1 Bands and Publishable Bands.
Full Reference
Every option, the paths it mounts, and the JSON each command prints are in the ar-io-node CLI reference.
How is this guide?
Importing SQLite Database Snapshots
Bootstrap your ar.io gateway's index from a SQLite snapshot or, from Release 85, from published L1 bands, instead of indexing the chain block by block.
Setting Apex Domain Content
Complete guide to configuring your ar.io Gateway to serve custom content from the apex domain