The 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 you

Output

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 (130 if 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. With `--arweave-nodes`, roots are read from Arweave nodes and every byte proven, so no gateway is trusted
`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. From Release 86, verifies every band before it writes a row of it; from Release 87, `l1-4` bands' witnesses let it fill the whole chain with no `--allow-*` flag. 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 the chain: a gateway's own `core.db` (`--core-db`), or a directory of bands with no gateway at all (`--bands-dir`). Read-only. From Release 86 it anchors the index's top block (`--anchor-from`), samples what nothing else binds, and fails closed: what it cannot bind fails the run unless an `--allow-*` flag accepts it. From Release 87 it reads `l1-4` bands, whose witness files bind every block, so a whole set passes with no such flag. See Verifying Shared Indexes
`index-l1-audit`	Checks the blocks `index-l1-verify` reports as `unbound.txRootFormat1` (in a `core.db` or an `l1-3` band), those holding a format-1 transaction with data, by fetching a sample of that data and recomputing each block's `tx_root`. Read-only
`index-l2-verify`	Checks a `parquet-l2` index (a directory of bands, such as `ardrive-l2`) with no gateway: every band's id, every table row by row, every location and parent link, the lookups, and a sample of locations against Arweave nodes. Read-only. See Verifying Shared Indexes
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?

The ar-io-node CLI

Output

Commands

Full Reference

On this page