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

# Automation

> Drive Kisten from scripts, CI and agents with JSON output, watch, the event stream and API keys.

Everything the CLI does works without a person in front of it.

## A CI job

```bash
export KISTE_TOKEN=ksta_...           # an API key, see Account → API keys
kiste new "ci-$GITHUB_RUN_ID" --ttl 1h --no-ssh --json
kiste exec "ci-$GITHUB_RUN_ID" --cwd /workspace -- make test
kiste delete "ci-$GITHUB_RUN_ID" --yes --json
```

- `KISTE_TOKEN` signs the CLI in with an [API key](https://docs.kiste.run/account/api-keys.md) instead
  of a saved sign-in. `kiste login --with-token < token.txt` saves one instead.
- `--json` prints one result envelope per command and never prompts, opens a
  browser or attaches SSH. Destructive commands then need `--yes`.
- `--ttl` makes sure a forgotten Kiste stops by itself.
- `kiste exec` exits with the command's own exit status.

[Output modes and exit codes](https://docs.kiste.run/cli/output.md) describes the envelopes and every
exit code.

## Wait for a state

```bash
kiste watch review-42 --until running
kiste watch review-42 --until stopped --json
```

`watch` polls one Kiste (every second by default, `--interval` in milliseconds)
and prints an event each time its state changes. `--until` stops when the
status, desired state or setup status reaches a value; `--count` after that
many changes.

## Follow the event stream

Your account has one durable, ordered stream of events: Kisten created,
running, stopped, renamed, deleted; snapshots; commands; published ports; API
keys; webhooks; alerts.

```bash
kiste events --follow
kiste events --follow --type instance.stopped
kiste events --after 4107 --output ndjson
```

Each event has a sequence number. Pass the last one you handled as `--after`
and you continue exactly there, even after a restart of your script. The same
stream is available from the API ([`GET /v1/events`](https://docs.kiste.run/api/events.md#read-events))
and as signed [webhooks](https://docs.kiste.run/account/webhooks-alerts.md).

## Agents

An agent can own a Kiste completely: create it, run commands with exact
output, fork it to try alternatives, and delete it. Useful details:

- Give each agent session its own selection with `KISTE_CURRENT`.
- `kiste exec --id UUID` makes a command addressable, so another process can
  cancel it with `kiste cancel UUID`, or `kiste interrupt UUID` it.
- `kiste commands` and `kiste command ID` show the durable record of commands.
- `kiste prompt` runs Codex or Claude Code inside a Kiste; see [Coding agents
  and credentials](https://docs.kiste.run/ssh/agents.md).

## Related topics

- [Overview](https://docs.kiste.run/kisten.md)
- [Create a Kiste](https://docs.kiste.run/kisten/create.md)
- [Lifecycle](https://docs.kiste.run/kisten/lifecycle.md)
- [Checkpoints and snapshots](https://docs.kiste.run/kisten/snapshots.md)
- [Fork](https://docs.kiste.run/kisten/fork.md)
- [Manage](https://docs.kiste.run/kisten/manage.md)
- [Images and environments](https://docs.kiste.run/kisten/images.md)
- Previous: [Images and environments](https://docs.kiste.run/kisten/images.md)
- Next: [Overview](https://docs.kiste.run/desktop.md)