> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://platform.bctrl.ai/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://platform.bctrl.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://platform.bctrl.ai/_mcp/server.

# subaccounts Commands

> Manage subaccounts

Manage subaccounts

Output formatting flags (`--json`, `--jq`, and `--template`) are documented once in [Output Formatting](/cli/output) and are omitted from the tables below.

## `bctrl subaccounts archive`

Archive a subaccount so it can no longer be used for new work.

```bash
bctrl subaccounts archive <subaccountId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |

## `bctrl subaccounts create`

Create a subaccount for a tenant, customer, environment, or team. Optional limits can be provided inline.

```bash
bctrl subaccounts create [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl subaccounts get`

Get one subaccount. Pass include=usage to inline current usage and quota state.

```bash
bctrl subaccounts get <subaccountId> [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--include <value>`    | Query parameter include                            |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl subaccounts list`

List subaccounts using the simplified response envelope. Pass include=usage to inline current usage.

```bash
bctrl subaccounts list [flags]
```

| Flag                    | Description                                        |
| ----------------------- | -------------------------------------------------- |
| `--query <json>`        | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`       | Alias for --query                                  |
| `--cursor <value>`      | Query parameter cursor                             |
| `--order <value>`       | Query parameter order                              |
| `--limit <value>`       | Query parameter limit                              |
| `--include <value>`     | Query parameter include                            |
| `--status <value>`      | Query parameter status                             |
| `--external-id <value>` | Query parameter externalId                         |
| `--q <value>`           | Query parameter q                                  |
| `--headers <json>`      | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`  | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`  | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`  | Effective subaccount context (BCTRL-Subaccount-Id) |

## `bctrl subaccounts update`

Update one subaccount name, external identifier, metadata, or configured limits.

```bash
bctrl subaccounts update <subaccountId> [flags]
```

| Flag                      | Description                                        |
| ------------------------- | -------------------------------------------------- |
| `--headers <json>`        | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>`    | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>`    | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>`    | Effective subaccount context (BCTRL-Subaccount-Id) |
| `--idempotency-key <key>` | Retry key for this operation                       |
| `--body <json>`           | Request body: inline JSON, @file, or - for stdin   |

## `bctrl subaccounts usage list`

List current usage snapshots for subaccounts. Prefer GET /v1/subaccounts?include=usage when you also need subaccount metadata.

```bash
bctrl subaccounts usage list [flags]
```

| Flag                   | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `--query <json>`       | Query object: inline JSON, @file, or - for stdin   |
| `--params <json>`      | Alias for --query                                  |
| `--cursor <value>`     | Query parameter cursor                             |
| `--order <value>`      | Query parameter order                              |
| `--limit <value>`      | Query parameter limit                              |
| `--headers <json>`     | API headers: inline JSON, @file, or - for stdin    |
| `--api-version <date>` | Dated API contract (default: 2026-10-03)           |
| `--space <id-or-name>` | Select an authorized Space (BCTRL-Space)           |
| `--subaccount-id <id>` | Effective subaccount context (BCTRL-Subaccount-Id) |