Installation

The Quickstart gets you running with one global install. This page is the reference for every way to install: the CLI (global, per-project, or no-install), the agent skill, and the SDK. The toolkit ships on npm as a set of @artblocks/abx-* packages; most people only need the CLI.

Prerequisites

Node 22.5 or newer (the toolkit uses the built-in node:sqlite). Check with node --version.

The CLI

Install the CLI, then run it as abx. There are two supported installs, plus a no-install option for a quick try.

Global (simplest)

Install once and use abx from anywhere:

npm install -g @artblocks/abx-cli
abx doctor

Per-project (reproducible)

Add it to a project so the CLI version is pinned in package.json — reproducible operations, and the agent skill installs to match:

npm install @artblocks/abx-cli
npx abx doctor          # inside the project, `npx abx` runs the local binary

Examples throughout the docs are written as abx …. If you installed per-project rather than globally, prefix them with npx (npx abx …).

One-off, without installing

For a quick try with nothing installed, run it by its scoped package name. The bare abx name on npm belongs to an unrelated package, so npx abx alone won't reach this CLI — use the scoped name:

npx @artblocks/abx-cli doctor
npx @artblocks/abx-cli@latest doctor    # force the newest published release

Verify

abx version     # prints the installed CLI version (per-project: `npx abx version`)
abx doctor      # checks Node, RPC, signing key, canonical factory, and storage

abx checks npm for a newer release every few hours and prints a notify-only upgrade hint — see Upgrading.

About the `npm audit` warnings

Installing the CLI pulls in a large dependency tree and npm will report a pile of advisories, including criticals. Worth knowing what that actually is, because the shape is lopsided:

Effectively all of it comes from one optional dependency — @ardrive/turbo-sdk, the Arweave upload backend, and its own @dha-team/arbundles. Between them they bring a payments library, a browser-wallet UI stack, and a Solana SDK. Without them the CLI is ~21 packages with no advisories; with them it's ~790. Nothing in that subtree runs unless you upload to Arweave — abx lazy-loads it at the point of use.

Most of the serious advisories are fixed upstream, just not in the versions Turbo resolves. You can pull them forward with an overrides block in your package.json (overrides only apply to the top-level project, which is why we can't ship this for you):

{
  "overrides": {
    "elliptic": "^6.6.1",
    "secp256k1": "^5.0.1",
    "undici": "^6.27.0",
    "axios": "^1.18.1",
    "ws": "^8.21.1",
    "bigint-buffer": "^1.1.5",
    "uuid": "^11.1.1"
  }
}

Then npm install. That clears every critical and moderate. Two advisories have no upstream fix at any version and will remain: a bigint-buffer buffer-overflow (high) and an elliptic "risky cryptographic primitive" note that is filed against every published version, latest included. Both sit in the Arweave path.

If you don't need Arweave, npm install --omit=optional @artblocks/abx-cli skips the whole subtree — about 21 packages instead of 790, and nothing vulnerable on disk. Note that npm audit still reads your lockfile, so it will keep reporting the skipped tree even though none of it is installed. Every other storage backend (local disk, S3/R2, IPFS) works normally.

The agent skill

To let a coding agent drive the toolkit, install the skill. It ships bundled inside the CLI and is version-locked to it, so this is the recommended path:

abx skill install

By default it installs to both .claude/skills (Claude Code) and the neutral .agents/skills (Cursor, Codex CLI, Gemini CLI, GitHub Copilot) — one command covers every supported agent. Use --agent <name> to target one, or --global to install under your home directory. Restart your agent afterward. See Agent + skill for the per-agent matrix, version-locking, and cross-agent installation.

abx doctor checks the skill as its first check and, run interactively, offers to install or resync it right there — so in practice npm install → abx doctor sets up both the CLI and the agent. Use abx doctor --fix to install without the prompt (a non-TTY run never writes anything; it just prints the command).

Automating it for a team

The CLI deliberately does not install the skill from an npm postinstall hook: npm runs lifecycle scripts with the working directory set to the installed package, so the skill would land inside node_modules; pnpm blocks install scripts by default; and writing to your ~/.claude as a side effect of npm install is your decision to make, not ours.

Making that decision for your own repo is a different matter, and perfectly reasonable — add it to your package.json so a fresh clone is set up by npm install alone:

{
  "scripts": {
    "postinstall": "abx skill install"
  }
}

Correct working directory (your project root), and it re-runs on upgrade, so the skill stays version-locked to the CLI.

The SDK (as a library)

To build on the protocol directly, install the SDK:

npm install @artblocks/abx-sdk viem

import { deployOneOfOne, reconstructProject, makePublicClient } from '@artblocks/abx-sdk';
import { oneOfOneImageAbi } from '@artblocks/abx-sdk/abi';

The SDK is ESM-only, built on viem, and requires Node 22.5+. See the SDK reference.

The remaining packages — @artblocks/abx-indexer, @artblocks/abx-storage, @artblocks/abx-token-api, and @artblocks/abx-effects — are also on npm and power the reference services the CLI orchestrates. You rarely install them directly; the CLI wires them together for you.

Quickstart: deploy a live asset on testnet.
Agent + skill: let an agent run the toolkit.
Upgrading: stay on the latest release.