Install the testlab command-line tool to import test plans, data fixtures, labels, and credentials into test-lab from your terminal, your CI, or an AI agent.

testlab CLI

@test-lab-ai/cli imports test plans (and the test data they need) into test-lab from the command line, your CI, or an AI agent. It is zero-dependency and wraps the public Import API.

Install

npx @test-lab-ai/cli login        # one-off, no install
npm i -g @test-lab-ai/cli         # or install the `testlab` command globally

Authenticate

testlab login

This opens your browser to approve access, then stores a key in ~/.test-lab/config.json (readable only by you). The key belongs to the account you are signed into, so that account is the import target. For CI or an agent, skip the browser:

export TESTLAB_API_KEY=tl_xxxxx

To import into an organization account, switch to that organization in test-lab before you authorize. The authorize screen names the account you are granting access to (personal or the organization), so you can confirm before clicking.

Commands

testlab whoami                                  Show the authenticated account
testlab import <path> [--dry-run]                Import a file or directory of *.json
testlab plans list                              List your test plans
testlab plans create -f plan.json                Create one plan from JSON
testlab projects list                           List your projects
testlab credentials set <key> --value <value>     Set a credential
testlab credentials list                        List credential keys (values never shown)
testlab labels list                             List your labels
testlab data list                               List your data fixtures
testlab data create -f fixture.json              Create a data fixture
testlab skills install [--agent ...]             Install the test-lab-plan skill (Claude/Codex/Cursor)
testlab skills update                           Refresh installed skills (also auto-runs after a CLI upgrade)
testlab examples                                Full JSON reference for every resource

Import format

testlab import reads a JSON file (or a directory of *.json). A file can be a single plan, an array of plans, or a bundle with any of these sections, created in order: credentials, labels, fixtures, then plans.

{
  "credentials": [ { "key": "password", "value": "hunter2" } ],
  "labels": ["smoke"],
  "fixtures": [
    { "key": "newUser", "fields": [ { "key": "email", "mode": "dynamic", "generator": "internet.email" } ] }
  ],
  "plans": [
    { "ref": "signup", "name": "Sign up", "prompt": "Go to https://app.example.com/signup and register with {{data.newUser.email}} / {{credentials.password}}. Confirm the welcome screen." },
    { "name": "Onboarding", "prompt": "Complete the onboarding checklist.", "preSteps": [ { "ref": "signup" } ] }
  ]
}

testlab import ./bundle.json --dry-run   # validate and print order, write nothing
testlab import ./bundle.json             # create everything

The CLI topologically sorts plans by their pre-step ref dependencies, so the order in the file does not matter.

Projects

Imported plans can go in a project. With no flag, testlab import auto-picks when you have a single project and asks when you have several (testlab projects list shows them). To be explicit, add testlab import ./bundle.json --project <id|name>, or --project none to keep them account-level. Geolocation/proxy country is not configurable via import; set it in the dashboard.

Reference syntax (inside a plan prompt)

{{credentials.<key>}} a stored secret (never shown to the AI model)
{{data.<fixture>.<field>}} a value from a data fixture
{{run.shortId}} a unique per-run id (for unique emails, names, and so on)

Updating

npm i -g @test-lab-ai/cli@latest

The CLI also prints a one-line notice when a newer version is available.

AI agent skill

Let Claude Code or Codex write the plans, then import them with the CLI

Import API

The HTTP endpoints the CLI wraps

testlab CLI

AI agent skill

Import API

On this page