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.

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