# Buildkite CLI queue command

The `bk queue` command allows you to manage cluster queues from the command line.

## Commands

| Command | Description |
| --- | --- |
| `bk queue list` | List cluster queues. |
| `bk queue view` | View a cluster queue. |
| `bk queue create` | Create a new cluster queue. |
| `bk queue update` | Update a cluster queue. |
| `bk queue delete` | Delete a cluster queue. |
| `bk queue pause` | Pause dispatch for a cluster queue. |
| `bk queue resume` | Resume dispatch for a cluster queue. |

## List queues

List cluster queues.

```bash
bk queue list <cluster-uuid> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<cluster-uuid>` | Cluster UUID to list queues for |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Enable debug output for REST API calls |
| `--json` | Output as JSON |
| `--limit=100` | Maximum number of queues to return |
| `--per-page=30` | Number of queues per page |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

List all queues for a cluster:

```bash
bk queue list my-cluster-uuid
```

Return more queues:

```bash
bk queue list my-cluster-uuid --limit 200
```

List in JSON format:

```bash
bk queue list my-cluster-uuid -o json
```

## View a queue

View a cluster queue.

```bash
bk queue view <cluster-uuid> <queue-uuid> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<cluster-uuid>` | Cluster UUID the queue belongs to |
| `<queue-uuid>` | Queue UUID to view |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Enable debug output for REST API calls |
| `--json` | Output as JSON |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

View a queue:

```bash
bk queue view my-cluster-uuid my-queue-uuid
```

View a queue in JSON format:

```bash
bk queue view my-cluster-uuid my-queue-uuid -o json
```

## Create a queue

Create a new cluster queue.

```bash
bk queue create --key=STRING <cluster-uuid> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<cluster-uuid>` | Cluster UUID to create the queue in |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Enable debug output for REST API calls |
| `--description=STRING` | A description of the queue |
| `--json` | Output as JSON |
| `--key=STRING` | A unique key for the queue |
| `--retry-agent-affinity=STRING` | Retry agent affinity setting (prefer-warmest or prefer-different) |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

Create a queue with just a key:

```bash
bk queue create my-cluster-uuid --key my-queue
```

Create a queue with a description:

```bash
bk queue create my-cluster-uuid --key my-queue --description "My new queue"
```

Create a queue with retry agent affinity set:

```bash
bk queue create my-cluster-uuid --key my-queue --retry-agent-affinity prefer-different
```

Create a queue and output as JSON:

```bash
bk queue create my-cluster-uuid --key my-queue -o json
```

## Update queue

Update a cluster queue.

```bash
bk queue update <cluster-uuid> <queue-uuid> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<cluster-uuid>` | Cluster UUID the queue belongs to |
| `<queue-uuid>` | Queue UUID to update |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Enable debug output for REST API calls |
| `--description=STRING` | New description for the queue |
| `--json` | Output as JSON |
| `--retry-agent-affinity=STRING` | Retry agent affinity (prefer-warmest or prefer-different) |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

Update a queue's description:

```bash
bk queue update my-cluster-uuid my-queue-uuid --description "New description"
```

Update retry agent affinity:

```bash
bk queue update my-cluster-uuid my-queue-uuid --retry-agent-affinity prefer-different
```

Update both settings:

```bash
bk queue update my-cluster-uuid my-queue-uuid --description "New description" --retry-agent-affinity prefer-warmest
```

Output the updated queue as JSON:

```bash
bk queue update my-cluster-uuid my-queue-uuid --description "New description" -o json
```

## Delete queue

Delete a cluster queue.

```bash
bk queue delete <cluster-uuid> <queue-uuid>
```

### Arguments

| Argument | Description |
| --- | --- |
| `<cluster-uuid>` | Cluster UUID the queue belongs to |
| `<queue-uuid>` | Queue UUID to delete |

### Flags

| Flag | Description |
| --- | --- |
| `--debug` | Enable debug output for REST API calls |

### Examples

Delete a queue:

```bash
bk queue delete my-cluster-uuid my-queue-uuid
```

Delete a queue without confirmation:

```bash
bk queue delete my-cluster-uuid my-queue-uuid --yes
```

## Pause a queue

Pause dispatch for a cluster queue.

```bash
bk queue pause <cluster-uuid> <queue-uuid> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<cluster-uuid>` | Cluster UUID the queue belongs to |
| `<queue-uuid>` | Queue UUID to pause |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Enable debug output for REST API calls |
| `--json` | Output as JSON |
| `--note=STRING` | Optional note explaining why the queue is being paused |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

Pause a queue:

```bash
bk queue pause my-cluster-uuid my-queue-uuid
```

Pause a queue with a note:

```bash
bk queue pause my-cluster-uuid my-queue-uuid --note "Pausing for maintenance"
```

Output the paused queue as JSON:

```bash
bk queue pause my-cluster-uuid my-queue-uuid --note "Maintenance" -o json
```

## Resume a queue

Resume dispatch for a cluster queue.

```bash
bk queue resume <cluster-uuid> <queue-uuid> [flags]
```

### Arguments

| Argument | Description |
| --- | --- |
| `<cluster-uuid>` | Cluster UUID the queue belongs to |
| `<queue-uuid>` | Queue UUID to resume |

### Flags

| Flag | Description |
| --- | --- |
| `-o`, `--output=""` | Output format. One of: json, yaml, text |
| `--debug` | Enable debug output for REST API calls |
| `--json` | Output as JSON |
| `--text` | Output as text |
| `--yaml` | Output as YAML |

### Examples

Resume a queue:

```bash
bk queue resume my-cluster-uuid my-queue-uuid
```

Output the resumed queue as JSON:

```bash
bk queue resume my-cluster-uuid my-queue-uuid -o json
```