Commands

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:

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

Responses:

• 200 One JSON event per line. Body: ExecEvent (application/x-ndjson)

Errors use the error envelope.

Cancel a running command

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

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

Path parameters:

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

Responses:

• 200 OK. Body: MessageResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: list of CommandResponse

Errors use the error envelope.

Get a command

GET /v1/commands/{id}

The durable record of one command, running or finished.

Path parameters:

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

Responses:

• 200 OK. Body: CommandResponse

Errors use the error envelope.

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:

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

Responses:

• 200 OK. Body: InterruptCommandResponse

Errors use the error envelope.