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

# CLI Command Reference

> Every testerarmy / ta command and its key flags - auth, projects, environments, credentials, groups, tests, runs, batches, memories, mobile uploads, and CI.

This page lists the full `ta` command surface. For install and sign-in, see [Getting Started](/cli). Run `ta <command> --help` for the complete options of any command.

## Shared flags

Most commands accept these flags:

| Flag               | Purpose                                                    |
| ------------------ | ---------------------------------------------------------- |
| `--json`           | Print machine-readable JSON. Errors are also JSON when set |
| `--api-key <key>`  | Override the stored API key                                |
| `--base-url <url>` | Override the API base URL (default `https://tester.army`)  |

Commands that create or update resources (`projects create`, `tests create`, `memories create`, and so on) read a JSON payload from stdin:

```bash theme={"theme":"vesper"}
echo '{"name":"Smoke"}' | ta groups update <groupId> --json
```

Project arguments accept either the project ID or its short ID.

## Setup and auth

| Command           | Purpose                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------- |
| `ta auth`         | Save an API key to local config. Flags: `--api-key`, `--base-url`                                               |
| `ta status`       | Show whether the CLI is authenticated and where the key comes from                                              |
| `ta signout`      | Remove the stored API key. `ta logout` is an alias                                                              |
| `ta agent init`   | Install the public TesterArmy skill and add discovery hints to `AGENTS.md`                                      |
| `ta docs [topic]` | Print agent-friendly CLI docs. Topics: `agent`, `auth`, `projects`, `memories`, `tests`, `groups`, `runs`, `ci` |

`ta agent init` accepts `--skip-skill-install` (only write `AGENTS.md`) and `--skip-agents-md` (only install the skill).

## Projects

| Command                                                       | Purpose                                                               |
| ------------------------------------------------------------- | --------------------------------------------------------------------- |
| `ta projects list`                                            | List team projects                                                    |
| `ta projects get <projectId>`                                 | Get one project                                                       |
| `ta projects create`                                          | Create a project from stdin JSON                                      |
| `ta projects update <projectId>`                              | Update a project from stdin JSON                                      |
| `ta projects delete <projectId>`                              | Delete a project                                                      |
| `ta projects files <projectId>`                               | List project files                                                    |
| `ta projects environments <projectId>`                        | List environments, including built-in Production and PR Preview       |
| `ta projects environments-create <projectId>`                 | Create a static environment. Flags: `--name`, `--url` (or stdin JSON) |
| `ta projects environments-delete <projectId> <environmentId>` | Delete a static environment                                           |
| `ta projects credentials <projectId>`                         | List credentials with secrets masked                                  |
| `ta projects credentials-create <projectId>`                  | Create a `login` or `inbox` credential from stdin JSON                |

See [Environments](/guides/environments) and [Credentials](/auth/credentials).

## Memories

| Command                                        | Purpose                         |
| ---------------------------------------------- | ------------------------------- |
| `ta memories list --project <id>`              | List project memories           |
| `ta memories create --project <id>`            | Create a memory from stdin JSON |
| `ta memories delete <memoryId> --project <id>` | Delete a memory                 |

Memory JSON fields: `category` (`site_structure`, `test_insights`, `user_preferences`), `title` (max 200 characters), `content`, `importance` (`high`, `medium`, `low`). See [Project Memory](/guides/project-memory).

## Groups

| Command                                    | Purpose                                              |
| ------------------------------------------ | ---------------------------------------------------- |
| `ta groups list --project <id>`            | List groups in a project                             |
| `ta groups get <groupId>`                  | Get one group                                        |
| `ta groups create`                         | Create a group from stdin JSON (`projectId`, `name`) |
| `ta groups update <groupId>`               | Update a group from stdin JSON                       |
| `ta groups delete <groupId>`               | Delete a group. The default group cannot be deleted  |
| `ta groups add-test <groupId> <testId>`    | Add an existing test to a group                      |
| `ta groups remove-test <groupId> <testId>` | Remove a test from a group                           |

## Tests

| Command                          | Purpose                                                           |
| -------------------------------- | ----------------------------------------------------------------- |
| `ta tests list --project <id>`   | List tests. Flags: `--group`, `--limit`, `--cursor`, `--all`      |
| `ta tests get <testId>`          | Get one test with its steps                                       |
| `ta tests create --project <id>` | Create a test from stdin JSON. `--group` adds it to a group       |
| `ta tests update <testId>`       | Update a test from stdin JSON. Sending `steps` replaces all steps |
| `ta tests enable <testId>`       | Enable a test                                                     |
| `ta tests disable <testId>`      | Disable a test without deleting it                                |
| `ta tests delete <testId>`       | Delete a test                                                     |
| `ta tests run [testId]`          | Queue a cloud run for one test, or for a group with `--group`     |

Tests take 1-30 steps. See [Writing Test Steps](/guides/writing-test-steps) for step types.

### `ta tests run` flags

| Flag                            | Purpose                                                            |
| ------------------------------- | ------------------------------------------------------------------ |
| `--wait`                        | Wait for the verdict instead of returning after queueing           |
| `--group <groupId>`             | Run every test in a group. Requires `--project`                    |
| `--env <nameOrSlug>`            | Target a saved project environment                                 |
| `--project-environment-id <id>` | Target a saved environment by ID                                   |
| `--url <url>`                   | Target URL override for group runs                                 |
| `--environment <label>`         | Group run environment label: `production`, `staging`, or `preview` |
| `--platform <platform>`         | `web`, `ios`, or `android`                                         |
| `--app-id <appId>`              | Uploaded mobile app to test                                        |
| `--device-model <model>`        | `iphone` or `ipad`. Defaults to the platform phone-sized device    |
| `--wait-timeout <ms>`           | Maximum wait time                                                  |
| `--wait-interval <ms>`          | Polling interval                                                   |

## Runs and batches

| Command                     | Purpose                                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------------------- |
| `ta runs list`              | List runs. Filters: `--project`, `--test`, `--batch`, `--status`. Paging: `--limit`, `--cursor`, `--all` |
| `ta runs get <runId>`       | Verdict, step results, and error codes for one run                                                       |
| `ta runs wait <runId>`      | Wait for a run to finish. Flags: `--timeout <ms>`, `--interval <ms>`                                     |
| `ta runs cancel <runId>`    | Cancel a queued or running run                                                                           |
| `ta runs messages <runId>`  | Agent transcript: reasoning and tool calls                                                               |
| `ta runs telemetry <runId>` | Browser console and network logs. Web runs only, available after the run finishes                        |
| `ta batches get <batchId>`  | Aggregate status of a group-run batch with per-run verdicts                                              |

`ta runs wait` backs off exponentially from `--interval`, capped at 30 seconds. See [Understand Results](/run/results).

## Mobile uploads

```bash theme={"theme":"vesper"}
ta upload-app --app-path MyApp.app --project <projectId> --json
```

| Flag                       | Purpose                                                                           |
| -------------------------- | --------------------------------------------------------------------------------- |
| `--app-path <path>`        | Required. `.app`, `.app.zip`, `.zip` (iOS Simulator) or `.apk`, `.apks` (Android) |
| `--project <id>`           | Required. Mobile project ID                                                       |
| `--remove-after <seconds>` | Delete the upload automatically after this many seconds                           |
| `--output <path>`          | Write the JSON result to a file or directory                                      |

Raw `.app` directories are zipped before upload. `.ipa`, `.aab`, `.xapk`, and `.tar.gz` archives are rejected. See [App Uploads](/mobile/app-uploads).

## CI and pull requests

`ta ci` runs a group in the cloud and waits for every run. `ta pr run-dynamic` runs the [exploration agent](/run/pr-exploration-agent) against a mobile build.

| `ta ci` flag                                    | Purpose                                                             |
| ----------------------------------------------- | ------------------------------------------------------------------- |
| `--group <groupId>`                             | Required. Group to run                                              |
| `--project <projectId>`                         | Project that owns the group. Required with `--delete-app-after-run` |
| `--platform`, `--app-id`                        | Mobile platform and uploaded app                                    |
| `--target-url <url>`                            | Target URL override for web tests                                   |
| `--project-environment-id <id>`                 | Target a saved environment                                          |
| `--commit-sha`, `--pr-number`                   | GitHub reporting metadata                                           |
| `--delete-app-after-run`                        | Delete the `--app-id` upload after runs finish                      |
| `--timeout <ms>`, `--poll-interval-seconds <s>` | Wait limits                                                         |
| `--output <path>`                               | Write the JSON result to a file or directory                        |

| `ta pr run-dynamic` flag                                                     | Purpose                                           |
| ---------------------------------------------------------------------------- | ------------------------------------------------- |
| `--project`, `--platform`                                                    | Required. Platform is `ios` or `android`          |
| `--app-id`, `--bundle-id`, or `--artifact-url` + `--artifact-filename`       | Required. Exactly one mobile build selector       |
| `--pr-number`, `--pr-title`, `--commit-sha`                                  | Required PR metadata                              |
| `--pr-description`, `--base-branch`, `--head-branch`, `--build-id`           | Optional PR and build context                     |
| `--simulator-region <region>`                                                | `eu-north1` or `us-west1`                         |
| `--deeplink <url>`                                                           | Deep link opened after app launch, before testing |
| `--delete-app-after-run`, `--timeout`, `--poll-interval-seconds`, `--output` | Same as `ta ci`                                   |

For workflow examples, see [GitHub Actions](/mobile/github-actions#direct-cli-usage) and [PR Exploration Agent](/run/pr-exploration-agent).

## Exit codes

| Code | Meaning                                                                                     |
| ---- | ------------------------------------------------------------------------------------------- |
| `0`  | Success. Waited runs passed or were skipped by the planner                                  |
| `1`  | A waited run failed, was blocked, was cancelled, or `ta ci` / `ta pr run-dynamic` timed out |
| `2`  | CLI or runtime error, including a wait timeout on `ta tests run`                            |

Without `--wait`, `ta tests run` exits `0` once the run is queued. `ta pr run-dynamic` exits `0` on a blocked run, matching its neutral GitHub check.

## Environment variables

| Variable              | Purpose                                        |
| --------------------- | ---------------------------------------------- |
| `TESTERARMY_API_KEY`  | API key. Takes priority over the stored config |
| `TESTERARMY_BASE_URL` | API base URL override                          |

## Related

<CardGroup cols={2}>
  <Card title="Getting Started" icon="terminal" iconType="duotone" href="/cli">
    Install the CLI and authenticate.
  </Card>

  <Card title="Agentic Usage" icon="robot" iconType="duotone" href="/cli/agentic-usage">
    Let a coding agent drive projects, tests, and runs.
  </Card>
</CardGroup>