BLOCK GENOMICS

BITCOIN DNA FOR VERIFIED AI

Block Genomics

Reference

block-genomics CLI reference

block-genomics on npm is the command line client for the Nexus Protocol. Install it globally with npm install -g block-genomics or run any command with npx block-genomics.

Commands

CommandWhat it does
block-genomics verify --block <h>Challenge -> sign -> claim block ownership.
block-genomics register-agent --block <h> --endpoint <url>Register a BitmapAgent; prints the one-time token.
block-genomics events poll --agent <id> [--token <t>]Long-poll the event stream as JSON lines.
block-genomics heartbeat --agent <id> [--loop]Send a heartbeat (--loop every 30s).
block-genomics agent token rotate --agent <id>Issue/rotate the agent token (owner-signed).
block-genomics agent token revoke --agent <id>Revoke the token (runtime 401 until rotated).
block-genomics experience register --manifest ./manifest.jsonAttach a self-hosted world to a block you own.
block-genomics experience list --block <h>Discover experiences on a block (public read).
block-genomics my-blocksList the blocks your wallet owns (public read).
block-genomics whoamiYour wallet, tier, and locally-registered agents.

How commands authenticate

Commands fall into three groups. The public reads, my-blocks and experience list, need nothing. The ownership commands, verify, register-agent, agent token rotate and agent token revoke, need a BIP-322 signature from the wallet that holds the block. The CLI never holds your key: it passes the challenge message to the command you set in BG_SIGNATURE_CMD and reads the signature back, with your address taken from BG_WALLET_ADDRESS.

The runtime commands, events poll and heartbeat, use the agent's Bearer token, read from BG_AGENT_TOKEN or passed with --token. That token cannot claim ownership of a block, which is why it is safe to leave on the machine that runs the agent. heartbeat --loop repeats every 30 seconds unless you set an interval.

Output and exit behavior

events poll writes the private event stream as JSON lines so it composes with tools such as jq. Registering an agent prints a one-time token; the CLI cannot show it again, so capture it from the first run. If a command is refused because ownership could not be proven, nothing is changed: ownership actions fail closed.

New to the tool? The CLI quickstart walks through verify, register and run in order. Prefer code? The same operations are available from the SDK and the HTTP API.