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

# Installation

> Install the TestSprite CLI and sign in in under 2 minutes.

## Prerequisites

Before installing, make sure you have:

* **Node.js >= 20** (Node 22 recommended)
* A **TestSprite account** — [Sign up for free <Icon icon="arrow-up-right-from-square" size={12} />](https://www.testsprite.com/auth/cognito/sign-up)
* A **TestSprite API key** (you'll create one in the next section)

<AccordionGroup>
  <Accordion title="How do I check my Node version?">
    Run the following in your terminal:

    ```bash theme={null}
    node --version
    ```

    If the output is below `v20.0.0`, download a newer release from [nodejs.org <Icon icon="arrow-up-right-from-square" size={12} />](https://nodejs.org/). Node 22 is the recommended version.
  </Accordion>

  <Accordion title="Where do I get an API key?">
    Sign in to your TestSprite dashboard, navigate to <kbd>Settings → API Keys</kbd>, and click <kbd>Create new key</kbd>. The key is shown exactly once — copy it before closing the dialog. If you lose it, just create a new one.

    See [API Keys](/web-portal/admin/api-keys) for the full walkthrough.
  </Accordion>
</AccordionGroup>

## Install

Install the CLI globally with npm:

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

Alternatively, run it without installing using npx:

```bash theme={null}
npx @testsprite/testsprite-cli --version
```

Verify the installation:

```bash theme={null}
testsprite --version
```

```text theme={null}
0.1.x
```

The CLI's source code, releases, and issue tracker live on [GitHub](https://github.com/TestSprite/testsprite-cli).

## Get Your API Key

1. Sign in to your [TestSprite dashboard <Icon icon="arrow-up-right-from-square" size={12} />](https://www.testsprite.com/dashboard).
2. Navigate to <kbd>Settings → API Keys</kbd> and click <kbd>Create new key</kbd>.

<Frame>
  <img src="https://mintcdn.com/testspriteinc/3tFsKENc_ol65zBe/images/api-key.png?fit=max&auto=format&n=3tFsKENc_ol65zBe&q=85&s=dd320eb057f5a51049e597f319fab0e7" alt="API Keys page with the Create new key button" width="3460" height="1790" data-path="images/api-key.png" />
</Frame>

3. Copy the key — it is shown **once only**. If you lose it, delete the key and create a new one.

<Frame>
  <img src="https://mintcdn.com/testspriteinc/3tFsKENc_ol65zBe/images/created-api-key.png?fit=max&auto=format&n=3tFsKENc_ol65zBe&q=85&s=ecbe1b1674e82fd332fde3751e7f97ff" alt="API Key Created dialog with the copy button" width="3284" height="1508" data-path="images/created-api-key.png" />
</Frame>

New and grandfathered keys both default to the scopes the CLI needs: `read:me`, `read:projects`, `read:tests`, `write:tests`, and `run:tests`.

## Sign In

<Tabs>
  <Tab title="With the agent skill (recommended)">
    Run `testsprite setup`. It prompts for your API key, verifies it against the platform, and installs the verification skill into your project's agent configuration — all in one step:

    ```bash theme={null}
    testsprite setup
    ```

    ```text theme={null}
    TestSprite API key: ********
    TestSprite initialized.

      profile:  default
      env:      production
      email:    alice@example.com
      scopes:   read:me, read:projects, read:tests, write:tests, run:tests

      agent:    claude (installed)

    Next steps:
      testsprite test list            # list tests in the current project
      testsprite agent list           # check installed agent targets
      testsprite agent install --target=<t>  # re-install or install additional targets
    ```

    `setup` chains credential configuration → identity verification → agent skill install. You only need to run it once per project. Pass `--agent <target>` to pick a different coding agent (default `claude`).
  </Tab>

  <Tab title="Credentials only">
    Add `--no-agent` to configure credentials without installing the agent skill:

    ```bash theme={null}
    testsprite setup --no-agent
    ```

    Then confirm the identity bound to the key:

    ```bash theme={null}
    testsprite auth status
    ```
  </Tab>
</Tabs>

<Tip>
  `testsprite setup` is the single onboarding command — it configures credentials, verifies them, and installs the agent skill in one pass. Add `--no-agent` when you only want credentials.
</Tip>

## Verify

After signing in, confirm the active profile:

```bash theme={null}
testsprite auth status
```

```text theme={null}
userId    u_01abc...
name      Alice Example
email     alice@example.com
keyId     key_01xyz...
env       production
scopes    read:me, read:projects, read:tests, write:tests, run:tests
```

If any scopes are missing, the CLI prints a `note:` line telling you which commands will be blocked.

## Using It in CI

In a CI environment, set `TESTSPRITE_API_KEY` as a secret and run setup non-interactively:

```bash theme={null}
TESTSPRITE_API_KEY=$TS_KEY testsprite setup --from-env --yes
```

`--from-env` reads the key from the environment instead of prompting. `--yes` accepts all defaults without interactive prompts. The CLI never accepts the API key as a positional argument or writes it to logs.

<Card title="CI/CD Integration" href="/cli/integrations/ci-cd" icon="github">
  The full CI setup — pipeline examples and exit code handling
</Card>

## Where to Go Next

<Columns cols={2}>
  <Card title="Quickstart" href="/cli/getting-started/quickstart" icon="play">
    Create a test, run it, and read the failure bundle end to end
  </Card>

  <Card title="Authentication" href="/cli/core/authentication" icon="key">
    Profiles, env vars, scope errors, and rotating keys
  </Card>

  <Card title="Key Terms" href="/cli/concepts/key-terms" icon="book">
    Projects, tests, runs, and the object model
  </Card>

  <Card title="CI/CD Integration" href="/cli/integrations/ci-cd" icon="github">
    Pipeline examples and non-interactive setup
  </Card>
</Columns>