Every subcommand parses its local artifacts before discovering a key or touching the network. Each on-chain step is submitted and then awaited: the CLI prints `submit <label> (nonce <n>)` and the transaction hash, waits up to 120 seconds for a committed receipt, and prints `committed <label>: block <height>`. A receipt that reports a failed execution is an error. Every submission is signed with limits from the node's estimate at the node's current fee quote; if the estimate fails, nothing is submitted.
The design is read-then-reconcile: the CLI reads committed rows first, submits only the missing ones, and refuses when an existing row differs from what the request describes. Rerunning a partially completed command therefore continues it instead of duplicating it.
## Subcommands
### `cowboy rooms create`
Create one v2 stream, then its RoomAuthority (`0x19`) record.
**Behavior:**
1. Read `--request` as a protocol `CreateRoomV1` JSON document; zero stream and operation ids in it are derived.
2. Read the committed stream and room records. If the stream exists and matches the request (ignoring `authorization_generation`, which advances in normal use), print `skip matching stream 0x...`; otherwise submit `CBQS CreateStream` and verify the committed record. A room that exists without its stream is refused.
3. If the room exists, print `skip matching room 0x...`; otherwise submit `RoomAuthority CreateRoom`, verify the committed record, and print `room 0x<room_id>; stream 0x<stream_id>`.
**Flags:**
| Flag | Default | Description |
|------|---------|-------------|
| `--request` | Required | Existing protocol `CreateRoomV1` JSON |
| `--provider` | Required | Provider address (20-byte hex) |
---
### `cowboy rooms add-seat`
Publish a signed control template, then add the seat referencing its sequence.
**Flags:**
| Flag | Default | Description |
|------|---------|-------------|
| `--room-id` | Required | Room id (32-byte hex) |
| `--seat` | Required | Existing protocol `RoomSeatConfigV1` JSON; `service_ref` is filled from the template |
| `--envelope-commitment` | Required | 32-byte hex; must be nonzero |
| `--template` | Required | Canonical signed `RoomWakeTemplateV1` bytes |
| `--control-lane` | Required | Existing ordinary control lane on the room's stream |
| `--admin-key` | Required | Stream admin Ed25519 seed: 32 bytes encoded as hex in a file |
| `--policy-epoch` | Required | Authoritative owner policy epoch (`0` for a newly provisioned stream) |
| `--wake-on-all` | `false` | Add the wake-on-all scope; must match the scopes `prepare-template` signed |
| `--broker-url` | Provider's first registered endpoint | Registered provider endpoint |
| `--broker-address` | None | Explicit broker socket for local/private deployments; requires `--broker-ca-der` |
| `--broker-ca-der` | None | DER CA certificate for `--broker-address` |
| `--template-sequence` | None | Resume after an append: read and compare this sequence instead of appending |
---
### `cowboy rooms create-control-lane`
Create an ordinary CBQS lane on the room's stream for signed wake templates. Takes `--room-id`, `--admin-key`, `--policy-epoch`, and the broker flags.
---
### `cowboy rooms seat-id`
Print the native actor seat id derived from `--room-id` and `--actor`. No network access.
---
### `cowboy rooms prepare-template`
Write canonical `session-open.bin`, `agent-job.bin` and `projected-seat.json` for a fresh actor seat into a new `--output-dir`. `--request` is the seat, group, session limits and Agent JobSpec JSON; `--wake-on-all` wakes the actor on every Human or door message instead of on mentions only.
---
### `cowboy rooms sign-template`
Sign the session descriptor and Agent job template for the seat in `--projected-seat` with the actor's record-signing Ed25519 seed (`--record-key`, 32 bytes as hex in a file), writing canonical signed `RoomWakeTemplateV1` bytes to a new `--output` file. Local only.
---
### `cowboy rooms update-template`
Replace the signed wake template referenced by an existing actor seat. Flags as `add-seat`, with `--seat-id` in place of `--seat`, `--envelope-commitment` and `--wake-on-all`.
---
### `cowboy rooms create-inbox-group`
Materialize an actor seat's inbox lane and create its CBQS consumer group. Takes `--room-id`, `--seat-id`, `--admin-key`, `--policy-epoch`, and the broker flags.
---
### `cowboy rooms bind-consumer`
Bind an existing CBQS inbox group (`--group-id`, nonzero) to an actor seat after its template is published. Prints `bound actor seat 0x... to group <n>`, or `skip matching actor consumer group <n>` when already bound.
---
### `cowboy rooms deploy-actor`
Deploy a room actor; the chain installs its native route with the code.
| Flag | Default | Description |
|------|---------|-------------|
| `--code` | Required | Actor source; must define the route handler `__cowboy_room_reply` |
| `--salt` | Required | Deploy salt, hex |
| `--manifest-json` | Required | ActorManifest JSON granting the route's `secrets.read` and `secrets.sign` keys |
| `--route` | Required | Route request JSON: `owner`, `room_key_name`, `seat_key_name`, `metering_public_key`, `bundle_hash` (SHA-256 of `--code`) and `runtime_hash` |
| `--init-handler` | None | Init handler name |
| `--init-payload` | None | Init payload, hex; requires `--init-handler` |
| `--cells-limit` | Node estimate | Cells limit |
---
### `cowboy rooms provision-gateway`
Enroll an independent Gateway seat and write its exact-lane access file.
| Flag | Default | Description |
|------|---------|-------------|
| `--room-id` | Required | Room id (32-byte hex) |
| `--gateway-ref` | Required | Native channel identifier, for example `telegram:-100123456` |
| `--role-label` | `telegram` | Seat role label |
| `--allow-current-room-read` | Required | Explicitly allow reading retained messages encrypted with the current room key |
| `--room-key` | Required | Room generation key: 32 hex bytes in a private file |
| `--admin-key` | Required | Stream admin seed; used only during provisioning, never saved in the access file |
| `--policy-epoch` | Required | Authoritative owner policy epoch |
| `--expires-in` | `86400` | Grant lifetime in seconds (60 to 604800); rerun with the same `--output` to renew |
| `--output` | Required | Private access file; existing identity and keys must match on renewal |
Also accepts the broker flags.
---
### `cowboy rooms close-session`
Close a native room session (`--session-id`, 32-byte hex) using its admitted relayer's signing key.
---
### `cowboy rooms trace`
Read-only: walk one room wake hop by hop and name the first broken hop. `--room-id` needs `--actor` or `--seat-id` unless `--tx` (a RouteInvocation wake transaction hash) or `--job` (its parent job id) names the wake. `--statusz` adds a daemon `/statusz` base URL and is repeatable. No key is needed.
## Example
```bash
$ cowboy rooms create --request room.json --provider 0x2222...
submit CBQS CreateStream (nonce 3)
Transaction hash: 0xabc...
committed CBQS CreateStream: block 1042
submit RoomAuthority CreateRoom (nonce 4)
Transaction hash: 0xdef...
committed RoomAuthority CreateRoom: block 1043
room 0x9c0d...; stream 0x7f1e...
