# List the commands a key can run

URL: https://heaven.dev/docs/reference/command/view
Updated: 2026-11-21

List customer management commands or read a named command's full definition. The response shows which commands this credential can grant to an API key.

`GET /v1/command/`

## Parameters

- `command` (string): Command to describe, such as `pool create`. Omit to list commands.
- `full` (boolean): Include full definitions in the list. False returns names, summaries, routes and field names. Defaults to true. MCP defaults to false. A named command always gets its full definition.

## Returns

- `data` (object, always present): Available commands and their inputs.
  - `commands` (object[] | null, always present): Commands with their routes and fields. Full results also include terminal syntax and permission metadata.
    - `items` (object): A command's inputs, route and credential requirements.
      - `aliases` (string[]): Alternative terminal command names. May be omitted.
      - `annotations` (map<string, JSON value>): Tool behavior hints. May be omitted.
      - `charges` (string): How the command can spend money. May be omitted.
      - `confirm` (boolean): Whether terminal use previews the change unless confirmed. May be omitted.
      - `confirm_losses` (boolean): Whether only changes causing loss require terminal confirmation. May be omitted.
      - `confirm_unless` (string[]): Inputs exempting a terminal invocation from confirmation. May be omitted.
      - `description` (string): Command's full help text. May be omitted.
      - `field_help` (object[]): Descriptions of the command's fields. May be omitted.
        - `items` (object): Help for one command input.
          - `field` (string, always present): Input name.
          - `help` (string, always present): Input's meaning and applicable conditions.
      - `fields` (string[] | null, always present): API field names accepted by the command.
      - `flags` (object[]): Flags in terminal syntax. May be omitted.
        - `items` (object): A command input.
          - `api` (string, always present): Corresponding API field name.
          - `help` (string): Input's meaning and usage conditions. May be omitted.
          - `maximum` (integer): Largest accepted numeric value. May be omitted.
          - `minimum` (integer): Smallest accepted numeric value. May be omitted.
          - `name` (string, always present): Terminal input name.
          - `object` (string[]): Nested object members accepted by structured requests. May be omitted.
          - `one_of` (boolean): Whether structured requests require exactly one declared member. May be omitted.
          - `optional` (boolean): Whether this input can be omitted in terminal syntax. May be omitted.
          - `repeated` (boolean): Whether terminal syntax accepts repeated values. May be omitted.
          - `rest` (boolean): Whether this positional consumes the remaining words. May be omitted.
          - `sensitive` (boolean): Whether the value contains a secret. May be omitted.
          - `stdin` (boolean): Whether terminal input can be read from standard input. May be omitted.
          - `text_only` (boolean): Whether the input applies only to terminal syntax. May be omitted.
          - `tool_default` (JSON value): Default applied specifically by the tool interface. May be omitted.
          - `type` (string, always present): Input value's declared kind.
          - `values` (string[]): Accepted fixed values. May be omitted.
          - `within` (string): Enclosing structured field. May be omitted.
      - `grantable` (boolean, always present): Whether you can create a key permitting this command.
      - `name` (string, always present): Command's catalog name.
      - `positionals` (object[]): Positional arguments in terminal syntax. May be omitted.
        - `items` (object): A command input.
          - `api` (string, always present): Corresponding API field name.
          - `help` (string): Input's meaning and usage conditions. May be omitted.
          - `maximum` (integer): Largest accepted numeric value. May be omitted.
          - `minimum` (integer): Smallest accepted numeric value. May be omitted.
          - `name` (string, always present): Terminal input name.
          - `object` (string[]): Nested object members accepted by structured requests. May be omitted.
          - `one_of` (boolean): Whether structured requests require exactly one declared member. May be omitted.
          - `optional` (boolean): Whether this input can be omitted in terminal syntax. May be omitted.
          - `repeated` (boolean): Whether terminal syntax accepts repeated values. May be omitted.
          - `rest` (boolean): Whether this positional consumes the remaining words. May be omitted.
          - `sensitive` (boolean): Whether the value contains a secret. May be omitted.
          - `stdin` (boolean): Whether terminal input can be read from standard input. May be omitted.
          - `text_only` (boolean): Whether the input applies only to terminal syntax. May be omitted.
          - `tool_default` (JSON value): Default applied specifically by the tool interface. May be omitted.
          - `type` (string, always present): Input value's declared kind.
          - `values` (string[]): Accepted fixed values. May be omitted.
          - `within` (string): Enclosing structured field. May be omitted.
      - `restricted` (boolean, always present): True if an API key limited to a command list cannot run this command.
      - `retry` (string): Retry behavior: `read`, `request-id` for changes identified across retries, or `reconcile` for settings that can be read and reapplied. May be omitted.
      - `route` (object): HTTP method, path and selector for this command. May be omitted.
        - `action` (string): Action selector for a shared modify endpoint. May be omitted.
        - `method` (string, always present): HTTP method to use.
        - `path` (string, always present): Endpoint path.
        - `view` (string): View selector for a shared read endpoint. May be omitted.
      - `summary` (object, always present): Short description used in command listings.
        - `command` (string, always present): Command name.
        - `summary` (string, always present): What the command does.
      - `usage` (string): Terminal invocation pattern. May be omitted.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- Accepts any API key.

## Examples

```sh tab="heaven CLI"
heaven command view [COMMAND]
  [--full true|false]
```

```sh tab="SSH"
ssh cli@heaven.dev command view [COMMAND]
  [--full true|false]
```

```sh tab="cURL"
curl https://heaven.dev/v1/command/ \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

```json tab="MCP"
{ "tool": "command_view",
  "arguments": {  } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "commands": [
      {
        "annotations": {
          "readOnlyHint": true
        },
        "description": "List management commands or read the syntax and fields for a named command. Name a group to list its commands.",
        "field_help": [
          {
            "field": "[COMMAND...]",
            "help": "Command or group to describe, such as `create` or `pool`. Omit to list commands."
          }
        ],
        "fields": [
          "command"
        ],
        "grantable": true,
        "name": "help",
        "positionals": [
          {
            "api": "command",
            "help": "Command or group to describe, such as `create` or `pool`. Omit to list commands.",
            "name": "command",
            "optional": true,
            "repeated": true,
            "type": "string"
          }
        ],
        "restricted": false,
        "retry": "read",
        "summary": {
          "command": "help [COMMAND...]",
          "summary": "List management commands or read the syntax and fields for a named command."
        },
        "usage": "help [COMMAND...]"
      },
      {
        "aliases": [
          "account ls",
          "account list",
          "account show"
        ],
        "annotations": {
          "readOnlyHint": true
        },
        "description": "Read your sign-in identity and account details. The response includes the keys, billing details and settings your credential can read.",
        "field_help": [
          {
            "field": "--organization ORGANIZATION",
            "help": "Organization name or ID. A credential, named resource or sole membership can select the organization for you."
          }
        ],
        "fields": [
          "organization"
        ],
        "flags": [
          {
            "api": "organization",
            "help": "Organization name or ID. A credential, named resource or sole membership can select the organization for you.",
            "name": "organization",
            "optional": true,
            "type": "string"
          }
        ],
        "grantable": true,
        "name": "account view",
        "restricted": false,
        "retry": "read",
        "route": {
          "method": "GET",
          "path": "/v1/account/"
        },
        "summary": {
          "command": "account view",
          "summary": "Read your sign-in identity and account details."
        },
        "usage": "account view [OPTIONS]"
      },
      {
        "aliases": [
          "command ls",
          "command list",
          "command show"
        ],
        "annotations": {
          "readOnlyHint": true
        },
        "description": "List customer management commands or read a named command's full definition. The response shows which commands this credential can grant to an API key.",
        "field_help": [
          {
            "field": "[COMMAND]",
            "help": "Command to describe, such as `pool create`. Omit to list commands."
          },
          {
            "field": "--full true|false",
            "help": "Include full definitions in the list. False returns names, summaries, routes and field names. Defaults to true. MCP defaults to false. A named command always gets its full definition."
          }
        ],
        "fields": [
          "command",
          "full"
        ],
        "flags": [
          {
            "api": "full",
            "help": "Include full definitions in the list. False returns names, summaries, routes and field names. Defaults to true. MCP defaults to false. A named command always gets its full definition.",
            "name": "full",
            "optional": true,
            "tool_default": false,
            "type": "true|false"
          }
        ],
        "grantable": true,
        "name": "command view",
        "positionals": [
          {
            "api": "command",
            "help": "Command to describe, such as `pool create`. Omit to list commands.",
            "name": "command",
            "optional": true,
            "rest": true,
            "type": "string"
          }
        ],
        "restricted": false,
        "retry": "read",
        "route": {
          "method": "GET",
          "path": "/v1/command/"
        },
        "summary": {
          "command": "command view [COMMAND]",
          "summary": "List customer management commands or read a named command's full definition."
        },
        "usage": "command view [COMMAND] [OPTIONS]"
      }
    ]
  }
}
```
