> Documentation index: https://docs.kiste.run/llms.txt, a list of every page in this documentation.

# Commands

> Run a program in a Kiste with its exact output and exit status, and follow durable command records.

Run a program in a Kiste with its exact output and exit status, and follow durable command records.

## Run a command

`POST /v1/instances/{name}/exec`

Runs `argv` in the Kiste without a shell and streams newline-delimited JSON: one `started` event, `output` events with base64 `stdout` or `stderr` bytes in order, then exactly one `completed` event with the exit code, signal, duration and byte counts, or `failed` when the command could not finish. Standard input is not forwarded. Pass your own `id` (a UUID) to cancel the command later or find its record. A slow reader slows the command down instead of losing output.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Kiste's name. |

```bash
curl -sS -X POST "https://kiste.run/v1/instances/review-42/exec" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"argv":["git","status","--short"],"cwd":"/workspace"}'
```

**Request body:** [ExecRequest](https://docs.kiste.run/api/schemas.md#execrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `argv` | array of string | yes | The program and its arguments, passed exactly, without a shell. |
| `cwd` | string or null | no | Working directory inside the Kiste. |
| `env` | map of string | no | Environment variables for the command. |
| `id` | string (uuid) or null | no | Your own UUID for the command, to cancel it or find its record. |
| `timeout_ms` | integer (int64) | no | Longest run time in milliseconds. |

**Responses:**

- `200` One JSON event per line. Body: [ExecEvent](https://docs.kiste.run/api/schemas.md#execevent) (`application/x-ndjson`)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Cancel a running command

`DELETE /v1/instances/{name}/exec/{id}`

Cancels a command started with your own `id` on this Kiste.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Kiste's name. |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X DELETE "https://kiste.run/v1/instances/review-42/exec/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [MessageResponse](https://docs.kiste.run/api/schemas.md#messageresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## List a Kiste's commands

`GET /v1/instances/{name}/commands`

Durable records of the commands run in one Kiste: state, exit code, timing and byte counts. Output itself is not stored.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | The Kiste's name. |

```bash
curl -sS "https://kiste.run/v1/instances/review-42/commands" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: list of [CommandResponse](https://docs.kiste.run/api/schemas.md#commandresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Get a command

`GET /v1/commands/{id}`

The durable record of one command, running or finished.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS "https://kiste.run/v1/commands/ID" \
  -H "Authorization: Bearer $KISTE_TOKEN"
```

**Responses:**

- `200` OK. Body: [CommandResponse](https://docs.kiste.run/api/schemas.md#commandresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Interrupt a command

`POST /v1/commands/{id}/interrupt`

Asks a running command to stop, with an optional reason for the record. The command receives an interrupt and can finish cleanly; its record shows when the interrupt was requested.

**Path parameters:**

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The object's ID. |

```bash
curl -sS -X POST "https://kiste.run/v1/commands/ID/interrupt" \
  -H "Authorization: Bearer $KISTE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason":"superseded"}'
```

**Request body:** [InterruptCommandRequest](https://docs.kiste.run/api/schemas.md#interruptcommandrequest)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `reason` | string or null | no |  |

**Responses:**

- `200` OK. Body: [InterruptCommandResponse](https://docs.kiste.run/api/schemas.md#interruptcommandresponse)

Errors use the [error envelope](https://docs.kiste.run/errors.md#reading-an-error).

## Related topics

- [Overview](https://docs.kiste.run/api.md)
- [Conventions](https://docs.kiste.run/api/conventions.md)
- [Kisten](https://docs.kiste.run/api/instances.md)
- [Snapshots](https://docs.kiste.run/api/snapshots.md)
- [SSH and terminal](https://docs.kiste.run/api/ssh-and-terminal.md)
- [Desktop](https://docs.kiste.run/api/desktop.md)
- [Kiste Stream](https://docs.kiste.run/api/stream.md)
- [Images and environments](https://docs.kiste.run/api/images.md)
- [Events, webhooks and alerts](https://docs.kiste.run/api/events.md)
- [Account and access](https://docs.kiste.run/api/account.md)
- [Sign-in and platform](https://docs.kiste.run/api/platform.md)
- [Schemas](https://docs.kiste.run/api/schemas.md)
- Previous: [Kisten](https://docs.kiste.run/api/instances.md)
- Next: [Snapshots](https://docs.kiste.run/api/snapshots.md)