Reference
block-genomics CLI reference
npm install -g block-genomics or run any command with npx block-genomics.Commands
| Command | What 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.json | Attach 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-blocks | List the blocks your wallet owns (public read). |
block-genomics whoami | Your 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.