Output modes and exit codes

Human, JSON and NDJSON output, the result and error envelopes, exit codes, request IDs and the local command log.

Output modes

Mode	How to choose it	What you get
`human`	the default	Tables, colours and spinners for a terminal
`json`	`--json` (also `--machine`), `--output json` or `KISTE_OUTPUT=json`	One JSON envelope per result on standard output
`ndjson`	`--output ndjson`	One JSON envelope per line; collections and events stream item by item

The machine modes never prompt, never open a browser and never attach SSH. A command that needs confirmation, such as kiste delete, then needs --yes. --no-input (or KISTE_NO_INPUT=1) gives the same guarantees in human mode.

Envelopes

Every result:

{"ok":true,"event":"instance.created","data":{"name":"review-42","status":"running"}}

event names what happened; data is the object, in the same shape as the API. In ndjson mode a collection arrives as one envelope per item, followed by an ….end envelope with the count.

Every error goes to standard error:

{"ok":false,"error":{"code":"K01","type":"machine_not_found","message":"There is no Kiste named review-42 in your account. (code: K01)","hint":"Check available names with `kiste list`.","request_id":"01J9Z8X7W6V5T4S3R2Q1P0N9M8","docs_url":"https://kiste.run/errors/K01"}}

Scripts branch on error.type, whose meaning never changes. Errors lists every code.

Exit codes

Code	Meaning
`0`	Success
`1`	The operation failed
`2`	Invalid arguments
`3`	Not signed in, or the session expired
`4`	Not found
`5`	Conflict, such as a busy Kiste or an exhausted quota
`6`	Invalid request, or confirmation needed (pass `--yes`)
`7`	kiste.run is unreachable or temporarily unavailable
`8`	A request timed out
`10`	Not possible in this output mode
`127`	`exec` could not start the command in the Kiste (program missing)

kiste exec and kiste ssh NAME -- CMD exit with the remote command's own status, which can be any number, including the ones above. To tell the two apart, use --json: a command that ran prints one exec.completed envelope with its exit_code, stdout_base64 and stderr_base64 (and kiste exits with that code), while a failure of the CLI itself is an error envelope on standard error with its own code.

Request IDs

Every command sends one request ID with all of its requests, and every error shows it:

× kiste.run can't reach the compute service right now. Your Kisten are safe. (code: N01)
  hint Try again in a minute.
  request: 01J9Z8X7W6V5T4S3R2Q1P0N9M8

Pass your own with --request-id (or KISTE_REQUEST_ID) to correlate a command with your logs. Quote it when you contact support.

Verbose output

--verbose (-v, KISTE_VERBOSE=1) prints each step on standard error as it happens, with how long it took: useful to see where time goes on a slow connection.

Timeouts

--timeout (KISTE_TIMEOUT) sets the longest time a request may take, in seconds or with a unit such as 10m or 2h. It is also the deadline of kiste exec commands. Errors the server reports earlier return at once.

The local command log

The CLI keeps a log of its own commands on your computer, one JSON line per command with secrets masked, in logs/cli.jsonl under its configuration directory. Nothing from it is sent anywhere. When a command you started with kiste exec ran on this computer, kiste command ID also shows its local transcript.