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 artwork 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 artworks 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). |
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 art 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. 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. (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-artwork 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 artworks); 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 artwork (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. |
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-field | Set an on-chain metadata field. Low-level. |
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. |
refresh | Ask marketplaces to re-index a token. |
ping-uri | Edition-only, permissionless: re-emit ERC-1155's native URI event 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 natively. Refused on a 721 target, which uses ERC-4906 instead. |
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. 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). |
set-schema | Attach or replace one PostParam's schema (--schema key:Type:Auth[:lock=<when>]) — 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. |
retire-param | Permanently stop further writes to a governed key, by moving its lock into the past. 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. |
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. |
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. |
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.