> ## Documentation Index
> Fetch the complete documentation index at: https://www.minitap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI commands

> Every minitest command and flag, organized by group.

This is the exhaustive reference. For the install steps and a quick tour, see [Cursor and Claude](/docs/minitest/integrations/cursor-and-claude).

## Global

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

Authentication is read from the environment or a saved session. See [auth](#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`) |

## 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.

### `minitest auth login`

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.

```bash theme={null}
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:

```bash theme={null}
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:

```yaml theme={null}
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:

```bash theme={null}
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>`      | —       | 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:

```bash theme={null}
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>` | —             |             |

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>`     | —       | 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`

```bash theme={null}
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. |

```bash theme={null}
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 list`

| Flag                        | Default | Description    |
| --------------------------- | ------- | -------------- |
| `--platform <ios\|android>` | —       | 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>`     | —         | iOS build UUID.                                       |
| `--android-build <id>` | —         | 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>`    | —       | 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>`     | —       |             |
| `--android-build <id>` | —       |             |

## 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>`       | —       | Filter by status. Repeatable.              |
| `--result <str>`       | —       | Filter by result. Repeatable.              |
| `--commit-sha <str>`   | —       |                                            |
| `--user-story-id <id>` | —       | Restrict to batches containing this story. |
| `--search <str>`       | —       | 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.

## maintenance

Keep a suite in sync with local app code **without connecting GitHub**. Run these from your app repository: the code stays on your machine, and the CLI sends only the proposed acceptance-criteria edits plus the local HEAD commit SHA. Your own AI coding agent does the reasoning against your checkout.

### `minitest maintenance`

Print the server-composed maintenance plan to hand to your coding agent. Pass `--agent` to force the raw agent prompt.

```bash theme={null}
minitest maintenance --agent
```

The agent then drives the run with the subcommands below.

### `minitest maintenance context`

Open a maintenance run and emit its context as JSON (`runId`, `mode`, `fromSha`, `headSha`, guardrails, and the stories in scope). The first run on an app returns audit mode over the whole suite; later runs return the previous SHA so the agent can `git diff <fromSha>..HEAD`.

```bash theme={null}
minitest --json maintenance context
```

### `minitest maintenance affected`

| Flag            | Default | Description                                                         |
| --------------- | ------- | ------------------------------------------------------------------- |
| `--file <path>` | —       | JSON file `{stories:[...]}` listing the stories the change affects. |

### `minitest maintenance change`

| Flag            | Default | Description                                                                  |
| --------------- | ------- | ---------------------------------------------------------------------------- |
| `--file <path>` | —       | JSON file with one proposed maintenance change to post to the Release queue. |

### `minitest maintenance divergence`

| Flag            | Default | Description                                         |
| --------------- | ------- | --------------------------------------------------- |
| `--file <path>` | —       | JSON file with one spec-vs-code divergence finding. |

### `minitest maintenance status`

| Flag               | Default | Description                           |
| ------------------ | ------- | ------------------------------------- |
| `--phase <str>`    | —       | `triage`, `writing`, or `finalizing`. |
| `--message <str>`  | —       | Short progress line.                  |
| `--progress <int>` | —       | 0-100.                                |

### `minitest maintenance complete`

Close the run. Pass `--changed` to advance the watermark, or `--no-changed` when nothing was produced.

```bash theme={null}
minitest maintenance complete --changed
```

### `minitest maintenance apply`

Apply the pending edits now, or pass `--review` to print the Release queue link and review them in the dashboard first.

```bash theme={null}
minitest maintenance apply
minitest maintenance apply --review
```

## 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.

```bash theme={null}
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.