CLI

teaspill is the command-line client for a running deployment. Everything it does goes through the gateway — except keys, which is an operator command that talks to the database directly.

Install and run

The CLI ships as the teaspill bin of the @teaspill/cli workspace package. From the repository, run it through your package manager:

pnpm --filter @teaspill/cli exec teaspill --help

The examples below (and elsewhere in these docs) call teaspill directly, assuming the shell alias from Installation (alias teaspill="node $PWD/packages/cli/dist/index.js"). Without the alias, prefix any command with pnpm --filter @teaspill/cli exec.

Every command shares three global options.

Global configuration

Flags override environment; both fall back to a default.

Entity arguments accept the short form /a/<type>/<id> or a full canonical URL. Message and argument payloads are parsed as JSON when they parse, and treated as a bare string otherwise.

dev

teaspill dev [--deployment <url>]… [--watch] [--watch-path <dir>]… [--compose-file <path>] [--no-compose] [--no-logs]

Brings the stack up and keeps a local deployment registered: docker compose up -d → wait for the gateway to be healthy → register the deployment(s) through /registry/* with backoff → tail logs. The health-wait-then-register order is what avoids a register-before-ready race.

agents ls

teaspill agents ls [--type <type>] [--status <status>] [--parent <url>] [--json]

Lists entities from the catalog. --status is one of active, idle, archived.

teaspill agents ls --type researcher

active   /t/default/a/researcher/r1  (researcher) head=12
idle     /t/default/a/researcher/r2  (researcher) head=48

spawn

teaspill spawn <type> [args] [--id <id>] [--parent <url>] [--idempotency-key <key>]

Spawns an entity. args is JSON (or a bare string). --id supplies a caller-chosen instance id for idempotent spawn.

teaspill spawn researcher '{"topic":"the history of tea"}'

spawned /t/default/a/researcher/01j9z8k3q…
  logs: teaspill logs /t/default/a/researcher/01j9z8k3q…

send

teaspill send <url> <message> [--idempotency-key <key>]

Sends a message wake. The message is JSON (or a bare string).

teaspill send /a/researcher/r1 '{"kind":"message","content":[{"type":"text","text":"add a section on green tea"}]}'

sent → /t/default/a/researcher/r1

control

teaspill control <url> <verb> [--reason <reason>]

Applies a control verb: interrupt, pause, resume, or archive.

teaspill control /a/researcher/r1 interrupt --reason "user cancelled"

interrupt → /t/default/a/researcher/r1

logs

teaspill logs <url> [--deltas] [--from-snapshot <seq>]

Follows and renders an entity's timeline until the stream closes or you press Ctrl-C. Reconnection, dedup, and drift detection are handled for you.

teaspill logs /a/researcher/r1 --deltas

keys

teaspill keys create [--label <label>]
teaspill keys ls
teaspill keys revoke <id | id-prefix | tsp_token>

API-key administration. This is the one command that talks to Postgres directly rather than the gateway, so it needs a database connection: --database-url or DATABASE_URL. Add --json to any subcommand for machine-readable output. Full context in Auth & API keys.

export DATABASE_URL='postgresql://teaspill:teaspill@localhost:5432/teaspill?sslmode=disable'
teaspill keys create --label my-service

Created API key 6b1e…
  label: my-service
  token: tsp_…

Store this token now — it is shown ONCE and cannot be recovered.