> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# cowboy cbqs

> Register CIP-39 CBQS providers and manage stream accounts and streams

## Synopsis

```bash theme={null}
cowboy cbqs [--rpc-url <url>] [--private-key <path>] <subcommand>

cowboy cbqs provider-register --signing-key <hex> --endpoint <wss-url>... [--max-streams <n>]
cowboy cbqs provider-update [--endpoint <wss-url>]... [--max-streams <n>] [--accepts-new <bool>] [--signing-key <hex>]
cowboy cbqs top-up --provider <address> --amount <n>
cowboy cbqs create-stream --provider <address> --owner-nonce <n> --admin-key <hex>
cowboy cbqs close-stream --stream-id <hex>
```

`cowboy cbqs` submits [CIP-39](https://docs.cowboy.inc/cips/cip-39-cowboy-queue-system.md) v2 instructions to the Stream Registry system actor (`0x17`): provider registration and updates, account top-ups, and stream lifecycle.

All subcommands sign with the key found by [key auto-discovery](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md); none are read-only.

**Parent flags:**

| Flag | Default | Description |
| - | - | - |
| `--rpc-url` | Auto-discovered | RPC URL (`--rpc-url`, then `COWBOY_RPC_URL`, then `.cowboy/config.json`, then `http://localhost:4000`) |
| `--private-key` | Auto-discovered | Private key file path, or set `COWBOY_PRIVATE_KEY_FILE` / `COWBOY_PRIVATE_KEY` |

## Subcommands

### `cowboy cbqs provider-register`

CIP-39 §4.1 `RegisterProvider`. Costs 5 CBY, paid to the zero address.

**Behavior:**

1. Require at least one `--endpoint` (CIP-39 §4.1 endpoint rule 1 requires a nonempty list; the CLI refuses an empty one before submission).
2. Build `RegisterProviderV2` with `accepts_new = true` and a zero `metadata_hash`.
3. Sign and submit; print the node response and the transaction hash.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--signing-key` | Required | Provider's Ed25519 signing key, hex (32 B) |
| `--endpoint` | Required | `wss://` URI clients dial verbatim; repeatable. The reference `cbqsd` serves on the `/ws` path, so include it for that daemon |
| `--max-streams` | `64` | Maximum concurrent streams |

**Example:**

```bash theme={null}
$ cowboy cbqs provider-register --signing-key 0xab12... --endpoint wss://queue.example.com/ws
  Transaction hash: 0xabc123...
CBQS RegisterProvider submitted: <node response>
```

***

### `cowboy cbqs provider-update`

CIP-39 §4.1 `UpdateProvider`. Every field is optional; only what is passed changes.

**Behavior:**

1. An empty `--endpoint` list means "leave endpoints alone", never "clear them" -- clearing would strand every stream the provider serves.
2. `--signing-key` rotates the Ed25519 key; the outgoing key is retained on chain as `previous_signing_key` so older receipts still verify. Two rotations at one height are refused.
3. Sign and submit.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--endpoint` | None | Replace the endpoint list; repeatable. Omit to leave unchanged |
| `--max-streams` | None | New maximum concurrent streams |
| `--accepts-new` | None | `true` or `false`: whether the provider accepts new streams |
| `--signing-key` | None | New Ed25519 signing key, hex (32 B) |

***

### `cowboy cbqs top-up`

CIP-39 §4.3 `TopUpAccount`. Owner-only, and the only instruction that creates a `(owner, provider)` account; a stream on an accountless pair is unserviceable.

**Behavior:**

1. Derive the owner address from the signing key.
2. Build `TopUpAccountV2 { owner, provider, amount }`, sign, and submit.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--provider` | Required | Provider address, hex (20 B) |
| `--amount` | Required | Amount to add to the account, in base units (1 CBY = 10^9) |

***

### `cowboy cbqs create-stream`

CIP-39 §4.2 `CreateStream`. Costs 5 CBY and requires the account to fund `rate_per_block × (active_streams + 1)`.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--provider` | Required | Provider address, hex (20 B) |
| `--owner-nonce` | Required | Owner-chosen nonce for the stream |
| `--admin-key` | Required | Stream admin Ed25519 key, hex (32 B); signs every `StreamGrantV2` |

***

### `cowboy cbqs close-stream`

CIP-39 §4.2 `CloseStream`. Releases the stream's provider capacity and billing.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--stream-id` | Required | Stream id, hex (32 B) |

## Edge Cases

* `provider-register` fails locally with `--endpoint is required at least once` if no endpoint is given.
* Consensus checks only the endpoint count, length, `wss://` prefix, and printable-ASCII bytes ([CIP-39 §4.1](https://docs.cowboy.inc/cips/cip-39-cowboy-queue-system.md#41-providerrecordv2)); it never parses or compares endpoints. Clients dial the registered URI verbatim, so an endpoint without the path the provider serves is admitted but unreachable.
* `--signing-key` and `--admin-key` must decode to exactly 32 bytes; `--provider` to exactly 20; `--stream-id` to exactly 32.
* `top-up` is the only way to create an account for an `(owner, provider)` pair; create a stream only after topping up.
* Every write signs with resource limits from the node's estimate.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.