> For the complete documentation index, see [llms.txt](https://docs.catalog.cat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.catalog.cat/technical-manual/cli.md).

# CLI Reference

CATalog CLI reference for slot-machine

The [slot-machine](https://github.com/Yakuhito/slot-machine) binary provides the CATalog CLI. Run it as `slot-machine catalog <subcommand>` or `cargo run -- catalog <subcommand>` from a local checkout.

## Prerequisites

* **Rust 1.95.0+**
* [**Sage wallet**](https://github.com/xch-dev/sage) running locally

See [slot-machine LICENSE.md](https://github.com/Yakuhito/slot-machine/blob/master/LICENSE.md) for licensing terms.

## Shared flags

Most transaction commands accept:

| Flag          | Default  | Description                      |
| ------------- | -------- | -------------------------------- |
| `--testnet11` | `false`  | Use testnet11 instead of mainnet |
| `--fee`       | `0.0025` | Transaction fee in XCH           |

## Commands

### `catalog initiate-launch`

Start a new CATalog deployment. Creates the registry launcher and price singleton (state scheduler + medieval vault multisig).

| Flag          | Required | Description                                                      |
| ------------- | -------- | ---------------------------------------------------------------- |
| `--pubkeys`   | yes      | Comma-separated hex BLS pubkeys for the price singleton multisig |
| `-m`          | yes      | Signature threshold (m-of-n)                                     |
| `--testnet11` | no       | Use testnet11                                                    |
| `--fee`       | no       | Launch fee in XCH                                                |

### `catalog continue-launch`

Continues/Finishes launch by deploying premine precommit coins.

| Flag                 | Required | Description                                  |
| -------------------- | -------- | -------------------------------------------- |
| `--payment-asset-id` | yes      | Payment CAT tail hash from launch initiation |
| `--cats-per-spend`   | yes      | Number of premine CATs to deploy per spend   |
| `--testnet11`        | no       | Use testnet11                                |
| `--fee`              | no       | Fee in XCH                                   |

### `catalog unroll-state-scheduler`

Commit the price schedule to the state scheduler singleton.

| Flag          | Required | Description   |
| ------------- | -------- | ------------- |
| `--testnet11` | no       | Use testnet11 |
| `--fee`       | no       | Fee in XCH    |

### `catalog verify-deployment`

Audit the built-in deployment against trusted CSVs (`catalog_premine_mainnet.csv`, `catalog_price_schedule_mainnet.csv`).

| Flag          | Required | Description                                    |
| ------------- | -------- | ---------------------------------------------- |
| `--testnet11` | no       | Verify testnet11 deployment instead of mainnet |

### `catalog register`

Register a new CAT, or refund an invalid precommit with `--refund`.

**Registration flow:**

1. CLI creates a precommit CAT coin (phase 1)
2. User waits `relative_block_height` blocks
3. CLI runs register action (phase 2)

| Flag                   | Required | Description                                                |
| ---------------------- | -------- | ---------------------------------------------------------- |
| `--tail-reveal`        | yes      | TAIL program reveal (hex CLVM)                             |
| `--ticker`             | yes      | CAT ticker (e.g. `SBX`)                                    |
| `--name`               | yes      | CAT display name                                           |
| `--image-uris`         | yes      | Comma-separated image URIs                                 |
| `--image-hash`         | yes      | Image content hash (hex)                                   |
| `--payment-asset-id`   | yes      | Payment CAT tail hash                                      |
| `--description`        | no       | On-chain description (default `""`)                        |
| `--precision`          | no       | CAT precision (default `3`)                                |
| `--metadata-uris`      | no       | Metadata URIs (default `""`)                               |
| `--metadata-hash`      | no       | Metadata hash                                              |
| `--license-uris`       | no       | License URIs (default `""`)                                |
| `--license-hash`       | no       | License hash                                               |
| `--recipient`          | no       | NFT recipient address (defaults to first Sage derivation)  |
| `--payment-cat-amount` | no       | Override payment amount (mainly for refunds)               |
| `--refund`             | no       | Run refund action instead of register                      |
| `--local`              | no       | Sync from chain into local `data.db` instead of hosted API |
| `--log`                | no       | Write spend bundle to `sb.debug`                           |
| `--testnet11`          | no       | Use testnet11                                              |
| `--fee`                | no       | Fee in XCH                                                 |

### `catalog listen`

Long-running process: syncs CATalog from chain via Coinset WebSocket into SQLite `data.db`, and serves a local neighbors API on port **3000**.

| Endpoint                        | Description                                |
| ------------------------------- | ------------------------------------------ |
| `GET /`                         | Health check                               |
| `GET /neighbors?asset_id=<hex>` | Left/right neighbor slots for registration |

Use with `catalog register --local` on testnet (testnet API currently points to `http://localhost:3000`).

| Flag          | Required | Description   |
| ------------- | -------- | ------------- |
| `--testnet11` | no       | Use testnet11 |

### `catalog sign-state-update`

Sign a registry state update (fee token or amount change) as a multisig member.

| Flag                         | Required | Description                                  |
| ---------------------------- | -------- | -------------------------------------------- |
| `--new-payment-asset-id`     | yes      | New payment CAT tail hash                    |
| `--new-payment-asset-amount` | yes      | New registration price (CAT mojos)           |
| `--my-pubkey`                | yes      | Your BLS pubkey (hex)                        |
| `--launcher-id`              | yes      | Price singleton (medieval vault) launcher id |
| `--testnet11`                | no       | Use testnet11                                |
| `--debug`                    | no       | Debug signing (prompts for secret key)       |

### `catalog broadcast-state-update`

Broadcast a signed state update with collected multisig signatures.

| Flag                         | Required | Description                    |
| ---------------------------- | -------- | ------------------------------ |
| `--new-payment-asset-id`     | yes      | New payment CAT tail hash      |
| `--new-payment-asset-amount` | yes      | New registration price         |
| `--sigs`                     | yes      | Comma-separated BLS signatures |
| `--launcher-id`              | yes      | Price singleton launcher id    |
| `--testnet11`                | no       | Use testnet11                  |
| `--fee`                      | no       | Fee in XCH                     |

## Examples

```bash
# Verify mainnet deployment
cargo r catalog verify-deployment

# Register a CAT on testnet11 (requires Sage)
cargo r catalog register \
  --testnet11 \
  --tail-reveal ff... \
  --ticker SBX \
  --name Spacebucks \
  --image-uris https://example.com/sbx.png \
  --image-hash abc123... \
  --payment-asset-id def456...

# Refund an invalid precommit
cargo r catalog register --refund --testnet11 ...

# Run local sync + API
cargo r catalog listen --testnet11
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.catalog.cat/technical-manual/cli.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.