> ## 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 timer

> Governance operations on actor timers (cancel, extend, update config)

## Synopsis

```bash theme={null}
cowboy timer cancel --timer-id <hex> [--rpc-url <url>] [--private-key <path>]
cowboy timer extend --timer-id <hex> --new-expires-at <height> [--rpc-url <url>] [--private-key <path>]
cowboy timer update-config --max-ttl-blocks <n> --max-cycles-per-fire <n> --max-cells-per-fire <n>
                           --max-timers-per-actor <n> --gc-cycles-per-block <n>
                           [--rpc-url <url>] [--private-key <path>]
```

These are the timer governance paths (Model B.4 / B.6 / B.8). The sender must be listed in `genesis.system_deployers` for all three subcommands. All three share one submit path: load the private key via [auto-discovery](https://docs.cowboy.inc/cli-specs/key-auto-discovery.md), fetch the account nonce, the current basefee, and the chain id, sign a system instruction with resource limits from the node's estimate (nothing is submitted if the estimate fails), print the transaction hash, `POST` it to `<rpc-url>/submit`, and print the node's response. The command returns on acceptance; it does not wait for the transaction to commit.

## Subcommands

### `cowboy timer cancel`

Submit a governance-authorized `CancelTimer`.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--timer-id` | Required | Target timer ID (hex, `0x` optional) |
| `--rpc-url` | Auto-discovered | RPC endpoint |
| `--private-key` | Auto-discovered | Private key file |

**Example:**

```bash theme={null}
$ cowboy timer cancel --timer-id 0xabc123...
Cancelling timer 0xabc123... (governance path)
  Transaction hash: 0xdef789...
✓ CancelTimer submitted: ...
```

***

### `cowboy timer extend`

Submit a governance-authorized `ExtendTimer`.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--timer-id` | Required | Target timer ID (hex, `0x` optional) |
| `--new-expires-at` | Required | New `expires_at` block height; must be at most current height + `TimerConfig.max_ttl_blocks` |
| `--rpc-url` | Auto-discovered | RPC endpoint |
| `--private-key` | Auto-discovered | Private key file |

**Example:**

```bash theme={null}
$ cowboy timer extend --timer-id 0xabc123... --new-expires-at 5000
Extending timer 0xabc123... → expires_at=5000 (governance path)
  Transaction hash: 0xdef789...
✓ ExtendTimer submitted: ...
```

***

### `cowboy timer update-config`

Submit a governance `UpdateTimerConfig`. All five fields are required.

**Flags:**

| Flag | Default | Description |
| - | - | - |
| `--max-ttl-blocks` | Required | Maximum timer TTL in blocks |
| `--max-cycles-per-fire` | Required | Cycles budget per timer fire |
| `--max-cells-per-fire` | Required | Cells budget per timer fire |
| `--max-timers-per-actor` | Required | Maximum timers one actor may hold |
| `--gc-cycles-per-block` | Required | Cycles spent on timer garbage collection per block |
| `--rpc-url` | Auto-discovered | RPC endpoint |
| `--private-key` | Auto-discovered | Private key file |

**Example:**

```bash theme={null}
$ cowboy timer update-config --max-ttl-blocks 1000 --max-cycles-per-fire 1000000 \
    --max-cells-per-fire 100000 --max-timers-per-actor 16 --gc-cycles-per-block 50000
Updating TimerConfig: ttl=1000 cycles=1000000 cells=100000 per_actor=16 gc=50000
  Transaction hash: 0xdef789...
✓ UpdateTimerConfig submitted: ...
```

## Edge Cases

* A sender outside `genesis.system_deployers` is rejected by the chain; the CLI only reports the submission, so check the transaction's receipt to confirm the effect.
* A non-2xx `/submit` response fails with a typed error (`transaction_rejected` for a 4xx refusal, `rate_limited` for 429, otherwise `request_timeout` or `transaction_submission_unknown`) and the context `HTTP <status>: <reason>`. A response that admits nothing fails with `transaction_skipped`.
* To read an actor's timers, use `cowboy actor timers` (see [cowboy actor](https://docs.cowboy.inc/cli-specs/cowboy-actor.md)).


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