The `pond` CLI

A thin, friendly client over /v1 — so operating pond isn’t raw curl + nested JSON. Set your context once, then everything is pond <noun> <verb>.

Install

uv tool install '.[cli]'    # recommended → an isolated global `pond`
# or:
pip install '.[cli]'        # global `pond` (or `pipx install '.[cli]'`)
python -m cli --help        # in the repo, no install

Update after pulling: uv tool install --reinstall '.[cli]'.

Connect once

pond config set-context local --url http://pond.localhost:8088 --token <service-token>
pond status        # deployment doctor: build, migrations, git, pool, config

--url/--token (or $POND_URL/$POND_TOKEN) override the context per command; --context <name> switches between several. -o json on any command for scripting.

Command map

Group	What
`pond status` / `health`	deployment doctor / liveness
`pond config`	`set-context` · `use` · `list` · `delete`
`pond run`	`submit` · `preflight` · `get` · `list` · `logs [-f]` · `cancel` · `artifacts`
`pond harness`	`presets` · `from-preset` · `dry-run` · `list` · `create -f` · `delete`
`pond model` / `credential` / `variable` / `egress`	`list` · `set`/`create`/`add` · `delete`
`pond pool`	`workers` · `orchestrators` · `pairing-code` · `enroll-code`

Set up & run an agent

# register a harness from a preset (no hand-authored argv)
pond harness from-preset codex
pond harness dry-run codex --prompt "find bugs"          # see the exact argv

# credentials/models (secrets sealed; values never shown back)
# KEY=@file reads from a file, KEY=- from stdin — keeps the secret out of argv/history
pond credential set --name openrouter --provider openrouter --secret OPENAI_API_KEY=@./key.txt
pond model create --key orx --provider openrouter --model-id openai/gpt-4o-mini --credential openrouter

# preflight, then submit and watch it live
P=00000000-0000-0000-0000-000000000001
pond run preflight --project $P --source https://github.com/sindresorhus/slugify \
  --harness codex --model-ref orx --profile none
pond run submit   --project $P --source https://github.com/sindresorhus/slugify \
  --harness codex --model-ref orx --profile none --wait     # streams logs to done

# inspect what it produced (raw, verbatim — not a Python repr)
pond run artifacts $RID                # list
pond run artifacts $RID results.jsonl  # print one

The agent emits ```result blocks → results.jsonl by default; override the extraction with --fence/--out (e.g. --fence review --out review_comments.jsonl). A spec file works too: pond run submit -f run.yaml (JSON or YAML). Blocking problems and preflight errors render as readable lines, not raw JSON.

Design (for contributors)

cli/ is a layered, modular package:

client.py — the only thing that talks HTTP; centralizes auth + friendly error mapping (connection, auth, and the 422 preflight problems list).
config.py — named contexts at ~/.config/pond/config.json.
state.py — ctx.obj: lazily builds the client, renders results.
output.py — table vs JSON rendering.
commands/ — one module per resource, each a self-registering Typer sub-app. Add a surface = add a module + one add_typer line in main.py.