minitest-cli
Command-line interface for the Minitest testing platform for mobile and web apps.
Installation
One-liner (recommended)
macOS / Linux:
curl -fsSL https://raw.githubusercontent.com/minitap-ai/minitest-cli/main/install.sh | bash
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://raw.githubusercontent.com/minitap-ai/minitest-cli/main/install.ps1 | iex"
Both scripts use uv if available, or install it automatically.
Other methods
uv (all platforms):
uv tool install minitest-cli
Homebrew (macOS):
brew install minitap-ai/tap/minitest-cli
uvx (zero-install, all platforms):
uvx --from minitest-cli minitest --help
From source:
git clone https://github.com/minitap-ai/minitest-cli.git
cd minitest-cli
uv sync
uv run minitest --help
Quick Start
# Authenticate
minitest auth login
# List your apps
minitest apps list
# Inspect one app's full configuration
minitest apps get <app-id>
# Create a new app on your tenant
minitest apps create --name "My Mobile App" --platform ios --platform android
# Or create a web app target
minitest apps create --name "My Web App" --platform web --web-url https://example.com
# Upload native builds when testing iOS/Android apps
minitest --app <app-id> build upload ./app-release.apk
# Android App Bundle archives (.apks) are also accepted
minitest --app <app-id> build upload ./app-release.apks
# Run tests
minitest --app <app-id> run all --web
# or, for native lanes:
minitest --app <app-id> run all --ios-build <ios-build-id> --android-build <android-build-id>
Native cloud tablets
Native lanes default to phones. Use --ios-device-type phone|tablet or
--android-device-type phone|tablet on run start (including --tag), run all,
or run from-commit to configure an already selected native cloud lane:
minitest --app <app-id> run all --ios-build <ios-build-id> --ios-device-type tablet
minitest --app <app-id> run start --tag smoke --android-build <android-build-id> --android-device-type tablet
minitest --app <app-id> run from-commit <full-sha> --platform ios --ios-device-type tablet
The device-type options do not select an OS: start/all still need the
corresponding build flag; from-commit uses --platform (or its existing iOS +
Android default). An explicit device type, even phone, errors when that OS is
not selected. These options do not apply to physical devices, web/mobile-web
targets, or Edge. V1 supports one form factor per OS per run; run phone and
tablet suites separately. Tablet results are labelled iOS · Tablet or
Android · Tablet; phone labels stay unchanged.
An iPhone-only build may run on iPad in compatibility mode; the server warns that the run does not establish native tablet-layout coverage. Unknown device-family metadata produces a different warning with the same coverage limitation. Neither warning blocks launch. These per-run options do not change app defaults.
Configuration
| Environment Variable | Description | Required |
|---|---|---|
MINITEST_TOKEN |
API authentication token | Yes (or use minitest auth login) |
MINITEST_APP_ID |
Default app ID | No (can use --app flag) |
MINITEST_API_URL |
testing-service base URL | No (defaults to production) |
MINITEST_APPS_MANAGER_URL |
apps-manager base URL (used by minitest apps create) |
No (defaults to production) |
MINITEST_INTEGRATIONS_URL |
minihands-integrations base URL (used to list tenants) | No (defaults to production) |
MINITEST_WEBAPP_URL |
Minitest webapp base URL (used for review links) | No (defaults to production) |
MINITEST_SUPABASE_URL |
Supabase project URL used for OAuth login | No (defaults to production) |
MINITEST_SUPABASE_PUBLISHABLE_KEY |
Supabase publishable (anon) key used for OAuth login | No (defaults to production) |
The recommended way to set these is to copy
.env.exampleto.env— the CLI loads.envautomatically. The shipped.env.examplealready targets the dev environment (see below).
Global Flags
| Flag | Description |
|---|---|
--json |
Output JSON to stdout (diagnostics go to stderr) |
--app <id-or-name> |
Target app for commands that require one |
--version |
Show CLI version |
--help |
Show help |
Commands
| Command | Description |
|---|---|
minitest auth |
Authentication management |
minitest apps |
List, inspect, and create apps |
minitest user-story |
User-story operations |
minitest df |
Draft features — branches of the test suite |
minitest flow-types |
List flow types, create/rename/delete custom ones |
minitest screens |
Inspect the screens exploration mapped for an app |
minitest build |
Native iOS/Android build management |
minitest run |
Test execution for mobile and web lanes |
minitest maintenance |
CLI-only test-flow maintenance against local code |
CLI-only maintenance
minitest maintenance lets a coding agent keep Minitest user stories in sync
without connecting GitHub. Run it from the app repository: the code stays on the
machine, while the CLI sends only proposed test-flow edits and the local HEAD SHA.
# Print the server-composed maintenance instructions for your coding agent
minitest maintenance --agent
# Agent workflow primitives
minitest --json maintenance context
minitest maintenance affected --file affected.json
minitest maintenance change --file change.json
minitest maintenance status --phase writing --message "Updating affected stories"
minitest maintenance complete --changed
# Apply proposed edits now, or open the web review queue
minitest maintenance apply
minitest maintenance apply --review
Exit Codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Authentication error |
| 3 | Network / API error |
| 4 | Resource not found |
| 5 | Build rejected as invalid |
| 6 | Conflict — re-read, rebuild, retry once |
Using the Dev Environment
The shipped .env.example already targets the dev environment, so pointing the CLI at dev is just a matter of loading it. Copy it to .env once:
cp .env.example .env
The CLI loads .env automatically, so every command now runs against dev — no per-command environment variables needed:
minitest auth login # authenticates against dev, stores a dev-specific token
minitest apps list # runs against dev
To target production instead, either omit the .env file (the built-in defaults point at production) or comment out the dev values and uncomment the # Production lines in your .env.
Tip: You can still override any single variable inline for a one-off command, e.g.
MINITEST_API_URL=https://testing-service.dev.minitap.ai minitest apps list.
Development
# Install dependencies
uv sync --dev
# Run linter
uv run ruff check .
# Run formatter
uv run ruff format .
# Run type checker
uv run pyright
# Run tests
uv run pytest
1 maintainer
Metadata
1 maintainer
Release files for minitest-cli 0.32.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| minitest_cli-0.32.0.tar.gz | 228.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| minitest_cli-0.32.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 429.3 kB
Release files / minitest_cli-0.32.0.tar.gz
| Download URL | minitest_cli-0.32.0.tar.gz |
|---|---|
| Size | 228.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ef9395d039798184e22c20d49f99a3a5efc9ad34414c2c8df0896423c411a300
|
|
BLAKE2b-256 checksum How to use checksums |
68cb6c4d24b02d4bc5e22ed2add0d5a6c3b2afea08aba9255fe6874fa5a08bf1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency logRelease files / minitest_cli-0.32.0-py3-none-any.whl
| Download URL | minitest_cli-0.32.0-py3-none-any.whl |
|---|---|
| Size | 201.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ea6fab234be7e20a72a26eec4a5559c421b524e10510c298d9baf7c28fc8c190
|
|
BLAKE2b-256 checksum How to use checksums |
ab1686d05787e67b532f3a6e11589ac599377aad1516d9e325c5caa4250f6098
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 8, 2026.
Transparency log
