Reference
CLI
abx is the command-line interface to the toolkit. After installing it,
run a command as abx <command> (per-project installs: npx abx <command>). This page groups every
command by lane. For the current flags of any command, run abx <command> --help.
Deploy and index
| Command | Purpose |
|---|---|
demo | Deploy a token to testnet, index it, and serve it, as a one-command walkthrough. |
deploy | Deploy and index a single 1/1 token. --copies <n|open> deploys an ERC-1155 edition of the work instead — copies, not a unique token; open is an uncapped open edition. See Editions. |
deploy-series | Deploy a collection from a folder of media: one contract, many tokens. --copies <n|open> makes it an edition: the same N works from the folder, each with that many copies — with the same custody choices as the 721 lane, including --onchain-image and the no-server --onchain-uri --backend arweave|ipfs route (a uniform file extension uploads the folder as ONE directory behind a single {id} image field, stored as the bare CID with the gateway supplied at read time — see set-gateway). |
deploy-code | Deploy a generative or code project. --resume <address> finishes one whose setup transaction failed instead of deploying: a code deploy is two transactions, and when the second fails the contract is live but unusable while the salt for its address is spent. Pass the same content flags and it reads what is already on-chain, then sends only what is missing in one transaction (not yet wired for an edition target). --copies <n|open> deploys a generative edition instead — each id minted as copies. On-chain dependencies (--dep) work there; --code-dir and the on-chain field renderers aren't wired for an edition deploy yet and are refused by name. |
preview | Run a code project on localhost while you're still making it. No chain, no key, no deploy. |
inspect | Analyze a code project: traits, on-chain reproducibility, dependencies, and a recommended lane. |
scaffold-renderer | Write a buildable Foundry project for the in-chain Solidity render lane: a seed + PostParam renderer, its traits sibling, and a deploy script. Forge builds and deploys it; abx never compiles or deploys Solidity. |
predict | Compute a deploy address in advance, from the salt, deployer, and factory. --copies predicts against the matching edition factory instead. |
add | Register and index a project this node did not deploy. With --remote, waits out a service's catch-up and reports the result; --no-wait returns as soon as it's accepted. |
index | Re-index from chain. Incremental by default; --full replays from the start. |
verify | Re-hash the served bytes and compare them to the on-chain commitment; also reports whether renders are current. A byte mismatch exits non-zero. With --remote, the byte check runs on the service, so it needs that service's credential — without one it reports byte integrity NOT checked rather than implying a pass. |
render | Render the still image and traits once. Repair lane for code projects. |
effects | Run the effects runner locally to render new mints and param changes. |
tokenuri | Read tokenURI on-chain and decode the JSON. The token id is --token <id>; a stray positional is refused rather than silently answering about token 0. --fetch follows the URL the contract commits to and prints what is actually served — the body a marketplace reads, and the way a provider mismatch becomes visible rather than guessed at. On a fully on-chain token there is nothing to fetch, and it says so. |
contracturi | Read contractURI (ERC-7572 collection metadata) on-chain, follow it, and decode the JSON. Use this instead of hand-building a resolver URL: a contract commits its own metadata URL on-chain, so the answer comes from the chain rather than from remembering the route grammar. |
tokens | List every token's owner, seed, and params, straight from the contract — no indexer and no running resolver. --json for the machine-readable form; --from <id> / --limit <n> to window a large collection. For a generative collection this is the "what did the seeds actually deal?" read. Traits are not here: a trait comes from running the script against the seed, which is render's job. On an edition, each row shows supply/maxSupply instead of an owner — an id can have many concurrent holders — and --holder 0x… adds a held column (balanceOf(holder, id) per id), which is the only way to ask what one specific address holds. Refused on a 721, where the owner column already answers it. |
serve | Run the resolver: re-index from chain and serve metadata, images, and a dashboard. |
state | Print an on-chain snapshot: owner, supply, paused, minter, payee, royalty, renderer — plus the 721C transfer validator for a collection that enrolled at deploy. Also the whole PostParam surface read straight from chain: every declared schema with its type, auth, bounds/options and either an upcoming lock date or a retired marker, and the three param hooks with whether the set is frozen. On an edition the readout is per id (id space, that id's copies/cap, paused/minter/payee/royalty/renderer) instead of a single owner and whole-contract supply, and an enrolled edition shows its 1155C validator the same way. Does not print the metadata field/URI locks — read those with eth_call. (What the chain says — for who is serving it and how fresh, see status.) |
Sales and ownership
| Command | Purpose |
|---|---|
mint | Mint a token. The next token, or --count N for a collection. On an edition, mint copies of one id instead with --token-id <n> (required unless a one-work edition) and --amount <n> — --count is refused there. |
minter configure | Set price and allocation for a token on the shared fixed-price minter. Optional --erc20. On an edition, --token-id <n> prices that one id on the sibling AbxFixedPriceMinter1155 — required, and refused against a plain collection. |
minter show | Show a token's minter configuration. --token-id <n> on an edition. |
minter buy | Buy a token from the fixed-price minter. On an edition, --token-id <n> --quantity <n> buys that many copies in one purchase, paying price × quantity. |
set-minter | Authorize the minting contract for a collection. Contract-wide, including on an edition. |
set-primary-payee | Set the primary-sale payout address. Contract-wide, including on an edition. |
set-max-invocations | Lower the supply cap. Decreasing only. On an edition this caps the id space (how many distinct works); see set-max-supply for a per-id copy cap. |
set-max-supply | Edition-only: lower one id's ERC-1155 supply cap (--token-id <n> --cap <n>) — the per-id twin of set-max-invocations. Decreasing only, and a cap can never return to open once set. Refused on a 721 target. |
pause / unpause | Close or open the mint gate. Owner-only minting while paused. Contract-wide, including on an edition. |
mint-page | Scaffold a self-contained mint site for the fixed-price minter. Works against a Series, or an edition (OneOfOneEdition/EditionImage/EditionCode) — an edition gets a token-id-and-quantity purchase card, not a gallery. Refuses a plain 1/1 (no minter lane); deploy a one-token collection instead (deploy-series --count 1), or an edition of one work (deploy --copies <n|open>). |
set-royalty | Set the royalty basis points and receiver. |
set-transfer-validator | Manage a creator-token collection's transfer validator (ERC-721C, or ERC-1155C on an edition): re-point (0x…), suspend (none — stays enrolled), or recommended. Only for a collection that enrolled at deploy (--721c on the deploy commands, either standard); enrollment can never be added later. |
set-seed-source | Re-point a code project's mint-seed source: the project's own IAbxSeedSource (0x…), the shared canonical one, or none. The candidate is probed before any gas — it must answer seed(uint256,address) with 32 bytes, because a source that cannot reverts every mint while every read surface still reports the project as configured. Applies to future mints only (an assigned seed is settled). Refused on a token with no Seed Source extension — an image 1/1 or Series has none, and one cannot be added. |
transfer | Transfer or sell a token. The id is --token <id>, and --token-id <id> is accepted as an alias (every other id-taking command spells it that way; passing both with different values is refused). On an edition, move copies of an id instead with --amount <n> and --from 0x… (required — an id can have many concurrent holders, so there's no single on-chain owner to default from). |
Metadata and hosting config
| Command | Purpose |
|---|---|
set-token-uri | Re-point a token's metadata URI. |
set-contract-uri | Re-point the collection URI. |
set-renderer | Toggle URI resolution between on-chain and off-chain. |
set-gateway | Repoint where this collection's ipfs/arweave fields are served from: --ipfs <prefix> / --arweave <prefix> (or none to fall back to the public default). The CID never moves — it is identity — so this is one transaction rather than a re-upload, it moves every token at once, and it works even on fields you have already locked. Two flags so a project can run a dedicated IPFS gateway and leave Arweave public. Set them at deploy with --ipfs-gateway / --arweave-gateway; see Preferred gateways. |
set-field | Set an on-chain metadata field. Low-level. --file <path> stores bytes on-chain via the chunk store, subject to the same render-gas report as deploy --onchain-image: no size is refused, and past the ~50M gas (~117 KB) that every endpoint serves it measures your RPC's real cap and says who else can read the token. |
attach | Attach a named, typed file to the token's data plane. |
lock-field | Freeze a metadata field permanently. Fields and parameters are separate namespaces that may share a name, so a declared param key is refused here (locking the field would leave the param writable) — weld a param with set-schema … :lock=now. --force-field overrides when you do mean the field. |
lock-uri | Freeze the URI configuration permanently. With the fields locked too, the stored metadata can never change — which is not the same as a frozen output: no metadata lock reaches a parameter, and the renderer serves parameters into tokenURI. Freezing one is a separate act — set-schema … :lock=now per key. |
refresh | Ask marketplaces to re-index a token. |
ping-uri | Edition-only, owner-only: re-emit the per-id refresh events for --token-ids <csv|range> — the fix when a contract-wide re-point (set-token-uri/set-renderer) didn't ping the ids a marketplace/indexer watches per id. Emits ERC-4906 MetadataUpdate(id) per id, plus ERC-1155's native URI(uri(id), id) when no on-chain renderer is set (with one, that event would carry the whole rendered document). ERC-4906's range form fires on both lanes at the re-point itself, so a 4906-aware consumer already saw the change; this covers the ones that only honor a per-id event. Refused on a 721 target, which has no native per-id URI event to re-emit. |
set-admin | Transfer contract ownership. |
migrate | Copy off-chain state to a new resolver and verify parity. Does not cut over; you re-point DNS or the base URI when ready. |
Code projects
| Command | Purpose |
|---|---|
preview | Serve the program on localhost:8788, live: shuffle seeds, drive PostParams from real inputs, read the traits it reports, /grid many seeds at once. Serves the same document the generator serves, with a synthetic seed, and re-reads the program from disk each render — so edit and refresh. --shoot <dir> renders the same document headlessly to PNGs and exits (for an agent with no browser). |
configure-param | Set a governed parameter. SeriesCode / EditionCode only — image kinds have no param surface and the CLI refuses them before the tx. Typed, and re-addresses the render. A Bytes value must be 0x-prefixed hex or --file <path>; a bare string is refused (String is the type whose value is the characters). Quote --schema values that contain [ / ] (zsh glob-expands them). |
set-schema | Attach or replace one PostParam's schema (--schema key:Type:Auth[:lock=<when>]). SeriesCode / EditionCode only. A project's param surface isn't frozen at deploy. A full-row upsert; refuses a change that could strand already-stored values unless --force. :lock= is monotonic and one-way: it may only move earlier, and once the deadline is past the whole schema is welded (a further set-schema on that key reverts). |
retire-param | Permanently stop further writes to a governed key, by moving its lock into the past. SeriesCode / EditionCode only. Welds both halves: value writes and further schema edits revert ParamLockExpired, so the type, auth, bounds and Select options are frozen with it. Irreversible — the lock date can only ever move earlier (ParamLockNotExtendable). The closest thing to removing a param; the key and any stored value remain readable. |
set-param-hooks | Wire or clear a code project's three param-lifecycle hooks (--configure, --augment, --transfer). Reads the current trio and re-sends it with your change applied; run with no flags to print the current hooks. The --transfer hook is a veto: its revert fails the transfer, and mints too. |
set-dependency | Declare or replace a code dependency: name@version or an on-chain address. |
remove-last-dependency | Remove the last declared dependency. |
set-dependency-registry | Point at a dependency registry. |
lock-dependencies | Freeze the dependency set — the list and the registry pointer. That pins which library each ref means; a Registry ref's bytes still live in the registry, so this cannot freeze them. |
lock-param-hooks | Freeze all three param hooks permanently — the lock a buyer reads, because the --transfer hook can block transfers and mints. Freezing an empty set proves a transfer veto can never be armed; a hook already set keeps running. No carve-out: setParamHooks is owner-only forever and a freeze holds against everyone, including on an ownerless project (why). abx state reports it. |
lock-script | Freeze the on-chain program (the script chunks) permanently — the lock that freezes a code project's work, which lock-field/lock-uri do not cover. With lock-dependencies and the metadata locks, everything the contract stores is frozen; what that does and doesn't promise. |
Storage
| Command | Purpose |
|---|---|
storage show | Show the resolved byte-custody backend. --check goes beyond "is it configured" to a real read/write against it — for cloud that's a PUT through the signed API followed by a GET over the public base with a plain unsigned fetch, which is the only thing that catches a public-base-points-at-the-wrong-bucket mismatch. |
storage upload | Upload a file and print its locator. |
storage status | Is a locator retrievable yet, not just accepted? Probes the gateway your project uses plus two others, since propagation is per-gateway: ready · propagating (the data provably exists elsewhere — wait, don't re-upload) · unreachable. Exits non-zero unless ready. |
storage balance | Show Arweave upload credits and the funded address. |
storage topup | Buy Arweave upload credits. |
storage backup-key | Copy the managed storage key to a path you choose. |
Hosting
| Command | Purpose |
|---|---|
deploy-resolver | Deploy the resolver to a host: fly, render, or a VPS. |
deploy-effects | Deploy the effects runner as a hosted service. |
remote | Inspect a remote service: configured named remotes, a target's descriptor, and the projects your token sees. --conformance self-certifies a target against the control-plane spec instead. |
Several commands target a remote resolver — self-hosted or a
managed provider — instead of this machine's store:
add, index, forget, render, verify take --remote <name|url>, and migrate takes
--from/--to in the same forms. Credentials follow one grammar regardless of which: a name reads
ABX_REMOTE_<NAME>_URL and ABX_REMOTE_<NAME>_TOKEN from the environment; a URL takes
--remote-token or ABX_REMOTE_SELF_TOKEN; bare --remote is the self-host default
(ABX_PUBLIC_BASE_URL plus ABX_REMOTE_SELF_TOKEN) — "self" is just another named remote, with zero
special-casing. ABX_RESOLVER_ADMIN_TOKEN is a different thing: it's the resolver's own
server-side config (what abx deploy-resolver sets on the node to gate its control plane), never a
client credential.
abx remote <name|url> --conformance [--remote-token <t>] [--chain-id <n>] [--address <a>] [--from-block <n>]
self-certifies any service — yours or a third party's — against
the control-plane spec: descriptor shape, unauthenticated writes
refused, the read-plane's error taxonomy, and (with --chain-id + --address naming a contract you
own) the full register → poll-to-live → status → reindex → deregister loop. Prints one ✓/✗/· line
per assertion and exits non-zero on any failure, so CI can gate on it directly — a bare URL plus
--remote-token needs no .env setup, which is what makes this runnable against any published CLI
install, not just from a checkout of this repo.
Node
| Command | Purpose |
|---|---|
doctor | Check the environment: agent skill (installed and version-matched to this CLI — the first check, and the one it offers to fix interactively), RPC, canonical factory (the three ERC-721 factories and their ERC-1155 edition twins), storage (the same real probe as storage show --check), binary provenance and npm currency, and — under Optional — signing key balance, configured named remotes, and a stale ABX_RESOLVER_ADMIN_TOKEN left over from before the named-remote grammar. |
capabilities | Print the stable deployment lanes, extension seams, irreversible choices, and unsupported cases. --json emits the machine-readable capability contract used by agents and tests. |
status | Indexing status: queued → backfilling → live, plus stale and failed. Bare lists every project this node tracks; status <address> shows one in detail (floor, blocks indexed vs head, cause on failure). --remote [name|url] asks a hosted node or provider instead; --watch follows until it settles. |
forget | Drop a project's local registration and projection. The chain is untouched. |
skill install | Install the version-locked ABX agent skill into your agent(s). Default: .claude/skills + the neutral .agents/skills. Flags: --agent claude|cursor|codex|gemini|copilot, --global, --target <dir>. skill path prints the bundled skill. |
version | Print the running CLI version. |
help | Print grouped help, or per-command help with <command> --help. |
abx checks npm for a newer release every few hours and prints a notify-only hint to stderr; it never
upgrades itself. It's already a no-op in CI and when offline. To suppress it otherwise, set
ABX_NO_UPDATE_CHECK=1 or pass --no-update-check on any command. See
Upgrading.
Signing lanes
Every command that writes to the chain runs in one of three signing lanes:
--sign: sign in a browser wallet. Nothing is stored.--send: sign and broadcast with a hot key from the environment.--unsigned: print the raw transaction to sign elsewhere.
Add --dry-run to preview a write without sending it. A deploy preview's summary always carries an
approvals N line — the number of wallet transaction signatures the real run will ask for (a
connected-wallet storage upload, e.g. Arweave via --storage-signer eth, is a message signature, not
a transaction, and is counted separately). Without --salt, a deploy preview does not print a
deterministic address — that salt was only just reserved at random, so a plain re-run would land
somewhere else — it prints the salt itself and the two ways to pin it: re-run with --salt <shown>,
or abx predict --salt <shown> --for <signer>. Pass --salt and the address prints exactly as
before, because it's genuinely stable.