tpk_cli 0.1.0

TesterPayKit command-line client. Designed for agentic use — every command supports --json output and --token for non-interactive flows.

tpk — TesterPayKit CLI

Agentic-friendly command-line client for the TesterPayKit API (api.testerpaykit.com). Every command supports --json so an LLM or shell pipeline can pipe results without screen-scraping.

Install

cd cli
make install

This compiles the CLI to a native binary (~6 MB, ~15 ms cold-start) and drops it into ~/.pub-cache/bin/tpk — which should already be on your PATH if you have a working Dart toolchain.

Verify:

tpk --help

Re-run make install whenever cli/ source changes.

Auth — register first if you don't have an account

tpk register \
  --email [e-mail] \
  --password '…' \
  --full-name 'Ulrich Diedrichsen'

Creates a coordinator account AND logs in in a single call. Password ≥ 8 chars. If the email is already taken you get a clean 409.

Auth — two flows

tpk login

Opens https://app.testerpaykit.com/cli-auth?code=… in your default browser. Approve the request in the web console. The CLI polls the API in the background and stores the resulting JWT in ~/.tpk/credentials.json.

2. Direct password (agents / CI)

tpk login --email [e-mail] --password '…'

No browser, no polling — straight POST to /auth/coordinator/login.

Then verify:

tpk whoami
tpk whoami --json

Projects

# List all projects on the current coordinator
tpk project list
tpk project list --json

# Create a new project (bundle-id is the unique key)
tpk project create \
  --name Bonblick \
  --bundle-id dev.moinsen.bonblick \
  --description "Receipt-intelligence app — dogfooding TPK"

# Look up a project by its bundle-id
tpk project get --bundle-id dev.moinsen.bonblick --json

Bug reports — multi-stage by default

tpk bug list queries every logged-in stage in parallel and merges the results into one sorted table. Each row carries a stage column so you can see at a glance whether the bug came from prod, local, staging, or a custom env — no more tpk env use X to flip back and forth.

# List every bug from every logged-in stage (newest first).
tpk bug list

# Filter the merged list — these flags apply per-stage, before merge.
tpk bug list --severity critical
tpk bug list --status submitted --since 24h

# Limit to one stage when you do want a focused view.
tpk bug list --stage prod
tpk bug list --stage prod --stage staging       # union of two stages
tpk bug list --stage local --severity critical

# --json mode returns the merged set plus structured diagnostics:
#   { "bugs": [...], "stagesQueried": N, "errors": [...], "skipped": [...] }
tpk --json bug list

Per-stage failures don't break the whole listing — a dead local API or a logged-out stage shows up as a soft warning under the table (text mode) or in the errors / skipped arrays (JSON mode). The bug rows from the healthy stages still print.

Single-bug operations (tpk bug get / download / context / fix / comment) still act on the current stage — bug UUIDs are unique to their origin env. Use the stage column from tpk bug list to know which env to tpk env use first.

Global flags

Flag	Effect
--json	Emit machine-readable JSON on stdout. Stderr also becomes JSON for errors.
--token <jwt>	Override the stored JWT (bypasses ~/.tpk/credentials.json).
--api <url>	Override the API base URL. Useful for hitting a local Dart Frog instance.

Agentic bootstrap (Bonblick example)

# 1. Get a token (interactive once, or pipe creds for non-interactive)
tpk login --email [e-mail] --password "$TPK_PW"

# 2. Create the project, capture the UUID
PROJECT_ID=$(tpk project create \
  --name Bonblick \
  --bundle-id dev.moinsen.bonblick \
  --json | jq -r '.id')

# 3. Pass the UUID into the Flutter consumer
cd /path/to/bonblick/app
flutter run --dart-define=TPK_PROJECT_ID=$PROJECT_ID

Uninstall

make uninstall