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

# CLI

> Trigger tests from your terminal or any CI pipeline.

```bash theme={null}
npm install -g @testorim/cli
```

Requires Node 20 or later.

## Signing in

```bash theme={null}
testorim login
```

The key is written to `~/.testorim/config.json` with `0600` permissions. In CI,
set `TESTORIM_API_KEY` in the environment instead. It takes precedence over
the stored file.

Mint a key from [Team settings](https://app.testorim.com/settings/team).

## Commands

<CodeGroup>
  ```bash Run a saved test theme={null}
  testorim run <procedure-id>
  ```

  ```bash Run against a preview theme={null}
  testorim run <procedure-id> --base-url https://preview-42.staging.example.com
  ```

  ```bash Ad-hoc test theme={null}
  testorim run \
    --project <project-id> \
    --description "Sign in with test@example.com and verify the dashboard loads"
  ```

  ```bash Negative test theme={null}
  testorim run \
    --project <project-id> \
    --description "Try to log in with the wrong password and verify the error" \
    --expectation fail
  ```

  ```bash List theme={null}
  testorim list                    # projects
  testorim list --project <id>     # that project's saved tests
  ```

  ```bash Scaffold theme={null}
  testorim init                    # writes .testorim.json in this directory
  ```
</CodeGroup>

`testorim init` creates a `.testorim.json` so you can give saved tests short
aliases and run them by name: `testorim run checkout`.

## Flags

| Flag                                  | Meaning                                                        |
| ------------------------------------- | -------------------------------------------------------------- |
| `--api-key <key>`                     | Override the stored key                                        |
| `--api-url <url>`                     | Override the API base URL (default `https://app.testorim.com`) |
| `--project <id>`                      | Project id, required for ad-hoc tests                          |
| `--description "…"`                   | The plain-English instruction for an ad-hoc test               |
| `--base-url <url>`                    | Override the project's address for this run only               |
| `--expectation <pass\|fail\|unknown>` | Test intent (default `pass`)                                   |
| `--json`                              | Machine-readable output                                        |
| `--quiet`                             | Suppress progress lines                                        |
| `--help`                              | Usage                                                          |

## Exit codes

| Code | Meaning                                                        |
| ---- | -------------------------------------------------------------- |
| `0`  | The run passed                                                 |
| `1`  | The run failed                                                 |
| `2`  | It could not run: auth error, bad input, server error, timeout |

That is what makes the CLI a pipeline step: a failing test fails the build, and
an infrastructure problem is distinguishable from a real failure.

## In GitHub Actions

```yaml theme={null}
- name: Smoke test
  env:
    TESTORIM_API_KEY: ${{ secrets.TESTORIM_API_KEY }}
  run: npx @testorim/cli run <procedure-id>
```

To test a pull-request preview, pass its URL:

```yaml theme={null}
- name: Smoke test the preview
  env:
    TESTORIM_API_KEY: ${{ secrets.TESTORIM_API_KEY }}
  run: npx @testorim/cli run <procedure-id> --base-url "${{ steps.deploy.outputs.url }}"
```

<Note>
  For a repository whose pull requests should always be tested, the
  [GitHub integration](/integrations/github) is less work, because it resolves the
  preview URL itself and reports in the PR.
</Note>

## Configuration precedence

1. CLI flags
2. `TESTORIM_API_KEY` / `TESTORIM_API_URL` in the environment
3. `~/.testorim/config.json`


## Related topics

- [FAQ](/resources/faq.md)
- [Integrations overview](/integrations/overview.md)
- [Get one procedure by id](/api-reference/procedures/get-one-procedure-by-id.md)
- [Environments](/projects/environments.md)
- [Platform overview](/developers/platform-overview.md)