CLI commands - Minitap Docs

This is the exhaustive reference. For the install steps and a quick tour, see Cursor and Claude.

Global

Flag	Short	Default	Description
`--version`	`-v`	None	Print `minitest-cli <version>` and exit.
`--json`	None	off	Emit JSON to stdout; diagnostics go to stderr.
`--app <id-or-slug>`	None	`$MINITEST_APP_ID`	Target app. Required for every command except `auth`, `apps`, `flow-types`, `skill`, `upgrade`.
`--help`	None	None	Standard help.

Authentication is read from the environment or a saved session. See auth for the MINITEST_API_KEY and MINITEST_TOKEN variables and their precedence.

Exit codes

Code	Meaning
0	Success
1	General error (validation, bad args)
2	Authentication error
3	Network / API error
4	Resource not found
5	Build rejected as invalid (only `build upload`)
6	Conflict: the resource changed under you. Re-read it and retry once.

auth

Authentication management. The CLI reads credentials from three sources, in priority order:

Source	What it is	When to use
`MINITEST_TOKEN`	A raw bearer token, used verbatim.	Legacy override. Usually unset.
`MINITEST_API_KEY`	A workspace-scoped key starting with `mtk_`.	CI and scripts.
`minitest auth login`	An interactive OAuth session saved to `~/.minitest/credentials.json`.	Local development.

If both MINITEST_TOKEN and MINITEST_API_KEY are set, MINITEST_TOKEN wins and the CLI prints a warning to stderr once per process. mtk_ keys are scoped to one workspace and grant the same access as a workspace member. Treat one like a deploy token: never commit it, and rotate it if it leaks. Run the OAuth 2.0 PKCE browser flow and save a session to ~/.minitest/credentials.json. Opens a browser; waits up to two minutes.

`minitest auth logout`

Delete the local credentials file.

`minitest auth status`

Print the current auth state: method (env_token / api_key / oauth / none), user id, email, token expiry. Honors --json.

`minitest auth api-key mint`

Mint a new mtk_ key for a workspace and print the token. This is the only time the full token is shown, so store it now. Needs an OAuth session or MINITEST_TOKEN; it exits with code 2 if MINITEST_API_KEY is your only credential.

Flag	Required	Description
`--tenant <id>`	yes	Workspace UUID the key belongs to.
`--name <str>`	yes	Human-readable label, shown in `list`.

Without --json, the token prints alone on stdout (no formatting) so you can pipe it. With --json, the token is the plaintextToken field.

minitest auth api-key mint --tenant 3f0e... --name ci-runner

`minitest auth api-key list`

List the active keys for a workspace. Shows the key id, name, prefix, creation time, and last-used time. The full token is never shown again.

Flag	Required	Description
`--tenant <id>`	yes	Workspace UUID.

`minitest auth api-key revoke`

Revoke a key. This is immediate and can’t be undone; calls using that key start failing with an auth error.

Flag	Required	Description
`--tenant <id>`	yes	Workspace UUID.
`--key <id>`	yes	Key id to revoke (from `list`).

mtk_ keys don’t expire, so rotate them yourself. Mint the replacement, update the secret in CI, then revoke the old key:

minitest auth api-key mint --tenant 3f0e... --name ci-runner-v2
minitest auth api-key list --tenant 3f0e...
minitest auth api-key revoke --tenant 3f0e... --key <old-key-id>

In CI, set the key once and run any command:

env:
  MINITEST_API_KEY: ${{ secrets.MINITEST_API_KEY }}
steps:
  - run: minitest apps list

apps

Read workspace + app metadata.

`minitest apps list`

List all apps you can see.

`minitest apps create`

Create a new app in a workspace. Prints the new app’s UUID to stdout.

Flag	Required	Description
`--name <str>`	yes	Human-readable app name.
`--tenant <id>`	no	Workspace UUID. Required only when you belong to more than one workspace.
`--description <str>`	no
`--slug <str>`	no	Auto-generated server-side if omitted.
`--icon <path>`	no	Path to a local image; uploaded as multipart.

Example:

minitest apps create --name "My App" --tenant 3f0e... --icon ./icon.png

user-story

User-story operations. All commands need --app or MINITEST_APP_ID.

`minitest user-story create`

Create a user story.

Flag	Required	Description
`--name <str>`	yes
`--type <str>`	yes	Validated against backend types. Run `minitest flow-types list` to see them.
`--description <str>`	no
`--criteria <str>`	no	Acceptance criterion. Repeatable.
`--depends-on <id>`	no	Parent user-story ID. Repeatable.

`minitest user-story list`

Paginated list.

Flag	Default	Description
`--type <str>`	None	Filter by type.
`--page <int>`	1
`--page-size <int>`	20	Max 100.
`--all`	off	Auto-paginate.

`minitest user-story get <user-story-id>`

Fetch a single story by UUID.

`minitest user-story update <user-story-id>`

Partial update. At least one mutating flag is required.

Flag	Description
`--name <str>`
`--type <str>`	Validated against backend types.
`--description <str>`
`--criteria <str>`	Replace the criteria set. Repeatable.
`--add-criteria <str>`	Append to the criteria set. Repeatable. Mutually exclusive with `--criteria`.
`--depends-on <id>`	Replace the dependency set. Repeatable.
`--remove-dependency <id>`	Subtract from current deps. Repeatable. Ignored with a warning if `--depends-on` is also passed.

`minitest user-story delete <user-story-id>`

Hard delete. --force is required.

user-story-binding

Attach a profile and files to a story.

`minitest user-story-binding set-profile <user-story-id>`

Bind or clear a test profile.

Flag	Description
`--profile <id>`	Profile UUID.
`--clear`	Remove the binding.

Exactly one of the two is required.

`minitest user-story-binding set-files <user-story-id>`

Atomically replace the set of test files bound to a story.

Flag	Description
`--file <id>`	Test-file UUID. Repeatable.
`--clear`	Replace with an empty set.

Exactly one mode is required.

`minitest user-story-binding list-files <user-story-id>`

Flag	Default	Description
`--page <int>`	1
`--page-size <int>`	50	Max 100.

test-profile

App-scoped profiles (credentials the agent uses to sign in).

`minitest test-profile create`

Flag	Required	Description
`--name <str>`	yes
`--username <str>`	no
`--password <str>`	no	Mutually exclusive with `--password-stdin`.
`--password-stdin`	no	Read password from stdin.
`--about <str>`	no	Free-text notes.

Example:

echo "$PASS" | minitest test-profile create --name "QA user" --username qa@x.com --password-stdin

`minitest test-profile get <profile-id>`

`minitest test-profile update <profile-id>`

Flag	Description
`--name <str>`
`--username <str>`
`--password <str>`	Mutually exclusive with `--password-stdin` and `--clear-password`.
`--password-stdin`	Read password from stdin.
`--clear-password`	Remove the stored password.
`--about <str>`	Pass empty string to clear.

`minitest test-profile delete <profile-id>`

--force is required.

`minitest test-profile list`

List app-scoped profiles.

`minitest test-profile list-shared`

List workspace-shared profiles (the ones under Shared by Minitap in the dashboard). Doesn’t need --app.

test-file

App-scoped reference assets (images, docs, video, audio) bound to user stories. Upload cap: 25 MB.

`minitest test-file upload <path>`

Flag	Default	Description
`--name <str>`	file basename
`--note <str>`	None

MIME type is guessed from the extension.

`minitest test-file get <file-id>`

`minitest test-file update <file-id>`

At least one flag is required.

Flag	Description
`--name <str>`
`--note <str>`	Mutually exclusive with `--clear-note`.
`--clear-note`

`minitest test-file delete <file-id>`

--force is required.

`minitest test-file list`

Flag	Default	Description
`--kind <kind>`	None	One of `image`, `document`, `video`, `audio`, `other`.
`--page <int>`	1
`--page-size <int>`	20	Max 100.

flow-types

`minitest flow-types list`

Print every valid user-story type, one per line (JSON array with --json).

app-knowledge

Read and update the per-app Mini’s memory prompt that grounds agent runs. Both subcommands require --app passed inline.

`minitest app-knowledge get`

minitest app-knowledge get --app 3f0e...

`minitest app-knowledge update`

Flag	Required	Description
`--app <id>`	yes
`--content <str>`	one of	Inline markdown.
`--content-file <path>`	one of	Path to a markdown file.

minitest app-knowledge update --app 3f0e... --content-file ./app_knowledge.md

build

`minitest build upload <file>`

Upload a .apk or .ipa. The server validates the build for virtual-device compatibility before accepting it.

Flag	Description
`--platform <ios\|android>`	Auto-detected from extension if omitted.

iOS builds must be Simulator builds. Android builds must be x86_64-compatible.

`minitest build from-commit [sha]`

Queue a build of a GitHub commit on Minitap’s build infrastructure without running any test. Omit the SHA to build the head of the default branch. Needs the GitHub integration.

Flag	Default	Description
`--platform <ios\|android\|web>`, `-p`	`ios` and `android`	Repeatable. Web apps must pass `--platform web`.
`--force-full`	off	Skip the incremental build cache.

`minitest build list`

Flag	Default	Description
`--platform <ios\|android>`	None	Filter.
`--page <int>`	1
`--page-size <int>`	20
`--all`	off	Auto-paginate.

run

Story-run execution. All subcommands need --app or MINITEST_APP_ID. At least one of --ios-build / --android-build is required to start a run.

`minitest run start <user-story>`

Start a run for one user story. <user-story> is either a UUID or a case-insensitive name match.

Flag	Default	Description
`--ios-build <id>`	None	iOS build UUID.
`--android-build <id>`	None	Android build UUID.
`--watch / --no-watch`	`--watch`	Poll every 2s until the run reaches a terminal state.

`minitest run status <run-id>`

Flag	Default	Description
`--watch / --no-watch`	`--no-watch`	If set and the run is non-terminal, poll every 2s.

`minitest run list <user-story>`

Historical runs for a story. <user-story> is a name or UUID.

Flag	Default	Description
`--status <str>`	None	One of `pending`, `running`, `completed`, `failed`, `cancelled`.
`--page <int>`	1
`--page-size <int>`	20
`--all`	off	Auto-paginate.

`minitest run cancel <run-id>`

Cancel a pending or running story-run.

`minitest run all`

Start a run covering every user story for the app. Fire-and-forget: prints the run ID and exits.

Flag	Default	Description
`--ios-build <id>`	None
`--android-build <id>`	None
`--web`	off	Include the app’s configured web targets. No build needed.

`minitest run from-commit <sha>`

Build a GitHub commit and run the suite against it in one step. Needs the GitHub integration.

Flag	Default	Description
`--platform <ios\|android\|web>`, `-p`	`ios` and `android`	Repeatable. Web apps must pass `--platform web`.
`--user-story <id-or-name>`, `-u`	every story	Repeatable.
`--watch / --no-watch`	`--watch`	Poll until the run reaches a verdict.
`--timeout <seconds>`	3600	How long to poll before giving up.

Native cloud device type (pending)

Coming soon. These flags are part of the pending native cloud tablet contract, not a deployed feature. Tablet execution requires native-tablets, off by default.

Flag	Effective default	Description
`--ios-device-type <phone\|tablet>`	`phone`	Form factor for the selected native cloud iOS lane.
`--android-device-type <phone\|tablet>`	`phone`	Form factor for the selected native cloud Android lane.

Both flags are optional on minitest run start <user-story>, minitest run start --tag <tag>, minitest run all, and minitest run from-commit <sha>. Omitting a flag leaves deviceType out of the request and preserves phone execution. Each platform accepts one form factor per run. For start and all, supply the corresponding --ios-build or --android-build. For from-commit, select the native lane with --platform; its existing default is iOS and Android. A device-type flag does not select a lane by itself and is rejected if its lane is not selected. These flags do not change web defaults or browser/viewport targets. See the target restrictions before choosing a device type.

`minitest run verdicts <run-id>`

The verdict of every story and criterion in a run, as JSON. Use it to decide whether a release goes out.

Flag	Description
`--platform <ios\|android\|web>`	One platform only.
`--only-failed`	Drop stories that fully passed.
`--actionable`	Only criteria that failed or were unprocessable and are critical or warning.
`--verbose`	Include passing criteria and per-criterion evidence.

batch

The CLI uses the term “batch” for a multi-story run (one click of Run tests in the dashboard = one batch).

`minitest batch list`

Flag	Default	Description
`--status <str>`	None	Filter by status. Repeatable.
`--result <str>`	None	Filter by result. Repeatable.
`--commit-sha <str>`	None
`--user-story-id <id>`	None	Restrict to batches containing this story.
`--search <str>`	None	Free-text search.
`--page <int>`	1
`--page-size <int>`	20	Max 100.
`--all`	off	Auto-paginate.

`minitest batch get <batch-id>`

Full batch payload with every story run.

`minitest batch cancel <batch-id>`

Cancel the batch and every pending or running story-run in it.

issues

`minitest issues list`

Open issues as JSON, each with its fix prompt, the build it was found on, and a link to it in the dashboard. Hand the output to a coding agent to fix them.

Flag	Description
`--batch <run-id>`	Issues from one run.
`--run <story-run-id>`	Issues from one story in a run.
`--issue <id>`	One issue.
`--platform <ios\|android\|web>`	Filter by platform.
`--criticality <critical\|warning>`	Filter by criticality.
`--include-resolved`	Include resolved issues.

`minitest issues fix <issue-id>...`

Mark one or more issues as fixed. Prints one result per ID.

env

The app’s environment variables, as set in Test Configuration.

Command	Description
`minitest env list [--show]`	List variables. Values are masked unless you pass `--show`.
`minitest env get <key>`	Print one value, unmasked, to stdout.
`minitest env set <key> <value> [--yes] [--dry-run]`	Create or update one variable, keeping the others.
`minitest env unset <key>`	Remove one variable, keeping the others.
`minitest env clear`	Delete every variable.

capabilities

`minitest capabilities`

Print what Mini can and can’t do, the same list as What Mini can and can’t do.

Flag	Description
`--platform <ios\|android\|web>`	One platform only.

skill

`minitest skill`

Fetch the latest agent skill for the CLI (the prompt that teaches AI coding agents how to drive it) and print it to stdout.

minitest skill > minitest-skill.md

upgrade

`minitest upgrade`

Self-update the CLI and refresh the agent skill. Detects whether you installed via Homebrew or uv and runs the right upgrade command, then reinstalls the skill if its content has changed.

​Global

​Exit codes

​auth

​minitest auth login

​minitest auth logout

​minitest auth status

​minitest auth api-key mint

​minitest auth api-key list

​minitest auth api-key revoke

​apps

​minitest apps list

​minitest apps create

​user-story

​minitest user-story create

​minitest user-story list

​minitest user-story get <user-story-id>

​minitest user-story update <user-story-id>

​minitest user-story delete <user-story-id>

​user-story-binding

​minitest user-story-binding set-profile <user-story-id>

​minitest user-story-binding set-files <user-story-id>

​minitest user-story-binding list-files <user-story-id>

​test-profile

​minitest test-profile create

​minitest test-profile get <profile-id>

​minitest test-profile update <profile-id>

​minitest test-profile delete <profile-id>

​minitest test-profile list

​minitest test-profile list-shared

​test-file

​minitest test-file upload <path>

​minitest test-file get <file-id>

​minitest test-file update <file-id>

​minitest test-file delete <file-id>

​minitest test-file list

​flow-types

​minitest flow-types list

​app-knowledge

​minitest app-knowledge get

​minitest app-knowledge update

​build

​minitest build upload <file>

​minitest build from-commit [sha]

​minitest build list

​run

​minitest run start <user-story>

​minitest run status <run-id>

​minitest run list <user-story>

​minitest run cancel <run-id>

​minitest run all

​minitest run from-commit <sha>

​Native cloud device type (pending)

​minitest run verdicts <run-id>

​batch

​minitest batch list

​minitest batch get <batch-id>

​minitest batch cancel <batch-id>

​issues

​minitest issues list

​minitest issues fix <issue-id>...

​env

​capabilities

​minitest capabilities

​skill

​minitest skill

​upgrade

​minitest upgrade

Global

Exit codes

auth

`minitest auth login`

`minitest auth logout`

`minitest auth status`

`minitest auth api-key mint`

`minitest auth api-key list`

`minitest auth api-key revoke`

apps

`minitest apps list`

`minitest apps create`

user-story

`minitest user-story create`

`minitest user-story list`

`minitest user-story get <user-story-id>`

`minitest user-story update <user-story-id>`

`minitest user-story delete <user-story-id>`

user-story-binding

`minitest user-story-binding set-profile <user-story-id>`

`minitest user-story-binding set-files <user-story-id>`

`minitest user-story-binding list-files <user-story-id>`

test-profile

`minitest test-profile create`

`minitest test-profile get <profile-id>`

`minitest test-profile update <profile-id>`

`minitest test-profile delete <profile-id>`

`minitest test-profile list`

`minitest test-profile list-shared`

test-file

`minitest test-file upload <path>`

`minitest test-file get <file-id>`

`minitest test-file update <file-id>`

`minitest test-file delete <file-id>`

`minitest test-file list`

flow-types

`minitest flow-types list`

app-knowledge

`minitest app-knowledge get`

`minitest app-knowledge update`

build

`minitest build upload <file>`

`minitest build from-commit [sha]`

`minitest build list`

run

`minitest run start <user-story>`

`minitest run status <run-id>`

`minitest run list <user-story>`

`minitest run cancel <run-id>`

`minitest run all`

`minitest run from-commit <sha>`

Native cloud device type (pending)

`minitest run verdicts <run-id>`

batch

`minitest batch list`

`minitest batch get <batch-id>`

`minitest batch cancel <batch-id>`

issues

`minitest issues list`

`minitest issues fix <issue-id>...`

env

capabilities

`minitest capabilities`

skill

`minitest skill`

upgrade

`minitest upgrade`