tpk — TesterPayKit CLI

Agent-friendly command-line client for TesterPayKit, the crowd-testing platform for indie apps. Read bug reports from your testers, build LLM-ready fix context, manage projects and payout rules — from the terminal or from an AI agent. Every command supports --json, so scripts and LLMs can consume the output without screen-scraping.

You need a TesterPayKit account. Apart from --help and --version, every command talks to the TesterPayKit API as a logged-in coordinator. Accounts are currently invite-only — to request access, write to business@moinsen.dev.

Install

dart pub global activate tpk_cli

With Flutter installed, flutter pub global activate tpk_cli does the same. This puts two executables on your path: tpk (the CLI) and tpk_mcp (an MCP server, see below).

If your shell can't find tpk afterwards, add the pub cache to your PATH — ~/.pub-cache/bin on macOS and Linux, %LOCALAPPDATA%\Pub\Cache\bin on Windows. Then check:

tpk --version

Update to the latest release with tpk update; remove the CLI with dart pub global deactivate tpk_cli. tpk and tpk_mcp check pub.dev once a day and say when a newer version is out (TPK_NO_UPDATE_CHECK=1 turns that off).

Log in

tpk login

Opens the TesterPayKit web console in your browser. Approve the request there (you sign in to the console with your invited account via magic link); the CLI waits, then stores the session in ~/.tpk/credentials.json. Use --no-browser to just print the URL, e.g. on a remote machine.

tpk whoami

Agents and CI: pass a token explicitly with the global --token flag instead of relying on the stored session.

Projects

# List your projects
tpk project list

# Create a project — the bundle id is the unique key
tpk project create --name "My App" --bundle-id com.example.myapp

# Look a project up by bundle id
tpk --json project get --bundle-id com.example.myapp

Bug reports

tpk bug list queries every environment you are logged in to (prod, a local API, staging, …) in parallel and merges the results into one table, newest first. Each row has a stage column.

tpk bug list
tpk bug list --severity critical --since 24h
tpk bug list --stage prod

# Machine-readable: { "bugs": [...], "stagesQueried": N, "errors": [...], "skipped": [...] }
tpk --json bug list

A stage that is down or logged out shows up as a warning (or in errors / skipped with --json); the other stages still list.

Single-bug commands act on the current environment (tpk env use <name>):

tpk bug get <bug-id>
tpk bug context <bug-id>          # LLM-ready JSON for a fix prompt
tpk bug download <bug-id>         # screenshots, recordings, voice notes
tpk bug fix <bug-id> --version 1.2.3
tpk bug comment <bug-id> "still crashes on iOS 26"

File bugs yourself (as a tester)

tpk tester login --project com.example.myapp
tpk bug report --title "Save button does nothing" --severity high \
  --step "Open settings" --step "Tap save twice"

tpk tester login creates an anonymous tester for that project (one per machine by default), parallel to your coordinator login.

Environments

tpk env list                       # prod (default) and local are built in
tpk env use local                  # http://localhost:18080
tpk env add staging --api https://staging.example.com

tpk login logs in to the active environment.

MCP server for AI agents

tpk_mcp exposes your coordinator data — environments, sessions, timelines, bugs and bug context — read-only over the Model Context Protocol (stdio). It reuses the session from tpk login. For Claude Code:

claude mcp add tpk -- tpk_mcp

Global options

Option Effect
--json Machine-readable JSON on stdout; errors as JSON on stderr.
--token <jwt> Use this token instead of ~/.tpk/credentials.json.
--api <url> Override the API base URL for one call.
--version Print the installed version.

Example: bootstrap a project from a script

PROJECT_ID=$(tpk --json project create \
  --name "My App" --bundle-id com.example.myapp | jq -r '.id')

flutter run --dart-define=TPK_PROJECT_ID=$PROJECT_ID

More in example/example.md.

License

Commercial licence, not open source: you may install and run the CLI to work with the TesterPayKit service, but not redistribute or modify it. Details in LICENSE.

Libraries