@test-lab-ai/cli 0.1.0

package/AGENTS.md

@@ -0,0 +1,115 @@
+# Importing test plans into test-lab with an AI agent
+
+This guide is for an AI coding agent (Claude Code, Codex, Cursor, etc.) asked to
+move a user's existing tests into test-lab.ai. You do the format translation; the
+`testlab` CLI handles auth and upload.
+
+## Install (zero-dependency)
+
+```bash
+npx @test-lab-ai/cli --help
+# or a global `testlab` command: npm i -g @test-lab-ai/cli
+```
+
+## The workflow
+
+1. **Read** whatever the user already has: Playwright/Cypress specs, Cucumber
+   `.feature` files, a TestRail/Zephyr export, a spreadsheet, or a prose doc.
+2. **Convert** each test into a plan object (schema below). test-lab tests are
+   natural language, not code:
+   - Put the explicit, fully-qualified URL in the `prompt` (imported plans have
+     no project, so there is no base URL to inherit).
+   - Replace any secret (passwords, tokens, test-account logins) with a
+     `{{credentials.NAME}}` placeholder, and collect the real values into the
+     top-level `credentials` array.
+   - Write clear pass/fail expectations into the prompt ("Confirm the dashboard
+     loads", "Expect an order-confirmation page with an order number").
+   - If the user's repo has a test-lab plan skill/format, prefer it.
+3. **Write** the plans to a JSON file (or a directory of `*.json`).
+4. **Run** `testlab import <path>`. Use `--dry-run` first to show the user the
+   creation order without writing anything.
+
+Authentication: the user runs `testlab login` once (browser), or you set
+`TESTLAB_API_KEY` in the environment for a fully headless run.
+
+## Plan object schema
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `name` | string | yes | Max 200 chars |
+| `prompt` | string | yes | The test in natural language, with explicit URL(s) and `{{credentials.X}}`. Max 32 KB |
+| `ref` | string | no | A handle unique within this import, used only to wire pre-steps (see below) |
+| `testType` | `"quickTest"` \| `"deepTest"` | no | Quick is a fast smoke; deep is more thorough |
+| `agentType` | string | no | `functional` (default), `accessibility`, `uiux`, `exploratory`, `performance`, `security` |
+| `devices` | string[] | no | e.g. `["Desktop Chrome"]` (default), `["iPhone 15 Pro"]` |
+| `labels` | (string \| number)[] | no | Names auto-create on the account; ids reuse existing labels. Max 25 |
+| `preSteps` | object[] | no | Pipeline dependencies. Max 25. See below |
+| `failOnPreStepFailure` | boolean | no | Default `true` |
+| `cookies` | `{name,value,domain}[]` | no | Injected at run time |
+| `headers` | `{name,value}[]` | no | Injected at run time |
+
+## File shapes
+
+Any of these is valid input to `testlab import`:
+
+```jsonc
+// 1. a single plan
+{ "name": "...", "prompt": "..." }
+
+// 2. an array of plans
+[ { "name": "...", "prompt": "..." }, { "name": "...", "prompt": "..." } ]
+
+// 3. plans + the credentials they reference (recommended)
+{
+  "credentials": [ { "key": "email", "value": "qa@example.com" } ],
+  "plans": [ { "name": "...", "prompt": "Sign in with {{credentials.email}} ..." } ]
+}
+```
+
+A directory imports every `*.json` file inside it (sorted by filename).
+
+## Pre-steps and ordering
+
+A pre-step makes one plan run after another, sharing browser state (a login that
+runs before a checkout). Reference the dependency in one of three ways:
+
+```jsonc
+{ "ref": "login" }            // another plan IN THIS IMPORT, by its ref (preferred)
+{ "name": "Existing Login" }  // a plan that already exists in the account, by name
+{ "testPlanId": 42 }          // an existing plan by id
+```
+
+You do NOT need to order the plans array yourself: the CLI topologically sorts by
+`ref` dependencies and creates them in the correct order, then wires each
+pre-step to the concrete id it just created. Cycles, self-references, and a `ref`
+that matches no plan are rejected before anything is written.
+
+## Credentials
+
+Put real secret values in the top-level `credentials` array; reference them in
+prompts (and cookie/header values) as `{{credentials.KEY}}`. Keys start with a
+letter and use letters/numbers/underscores only. The CLI upserts credentials
+before creating plans, and values are stored encrypted (never echoed back).
+
+## End-to-end example
+
+```bash
+# 1. (user, once) authenticate
+testlab login                      # or: export TESTLAB_API_KEY=tl_xxxxx
+
+# 2. you write ./tests/*.json from the user's existing suite (see examples/plans.json)
+
+# 3. preview, then import
+testlab import ./tests --dry-run
+testlab import ./tests
+```
+
+## Notes
+
+- Plans are created fresh every run (no de-duplication). Run `testlab plans list`
+  first if you need to avoid creating duplicates of plans already in the account.
+- Imported plans have no project and no geolocation proxy; set those in the
+  dashboard afterward if the user needs them.
+- Prefer calling the CLI over hand-rolling HTTP. If you must call the API
+  directly, it is documented at https://test-lab.ai/docs/api/test-plans and uses
+  the same `Authorization: Bearer tl_…` key.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Test-Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @test-lab-ai/cli (`testlab`)
+
+Import existing test plans into [test-lab.ai](https://test-lab.ai) from the command line, your CI, or an AI agent. Zero dependencies, Node 18+.
+
+## Install
+
+Published to npm. The CLI has **zero dependencies**, so an install pulls nothing
+else and runs no install scripts.
+
+One-off, no install:
+
+```bash
+npx @test-lab-ai/cli login
+```
+
+Or install the `testlab` command globally:
+
+```bash
+npm i -g @test-lab-ai/cli
+testlab login
+```
+
+Requires Node 18+.
+
+## Authenticate
+
+```bash
+testlab login
+```
+
+Opens your browser to approve access, then stores a key in `~/.test-lab/config.json` (mode 600).
+
+Headless / CI / agents (no browser): pass a key directly. Create one under **Settings → API Keys** (`/admin/settings/api-keys`).
+
+```bash
+export TESTLAB_API_KEY=tl_xxxxx
+# or
+testlab login --key tl_xxxxx
+```
+
+The key resolves to a single account, so the key you use IS the import target. To import into an organization account, mint the key with that org selected.
+
+## Commands
+
+```
+testlab whoami                          Show the authenticated account
+testlab plans list                      List your test plans
+testlab plans create -f plan.json       Create one plan from JSON
+testlab plans create --name N --prompt P
+testlab credentials set KEY --value V    Upsert a credential ({{credentials.KEY}})
+testlab import <path> [--dry-run]        Import a plan file or a directory of *.json
+```
+
+Global options: `--key`, `--api-url` (or env `TESTLAB_API_KEY` / `TESTLAB_API_URL`). The API base defaults to `https://www.test-lab.ai`.
+
+## Import
+
+A file can be a single plan object, an array of plans, or `{ "credentials": [...], "plans": [...] }`. Pointing at a directory imports every `*.json` inside it. See [`examples/plans.json`](./examples/plans.json) and [`AGENTS.md`](./AGENTS.md) for the full schema.
+
+```bash
+testlab import ./tests --dry-run    # validate + print creation order, write nothing
+testlab import ./tests              # upsert credentials, then create plans
+```
+
+The CLI topologically sorts plans by their pre-step dependencies and creates them one request each, wiring intra-import dependencies via the `ref` handle. Re-running is safe for credentials and labels (both upsert), but plans are always created fresh (no de-duplication), so import a given set once.
+
+## Local development
+
+Point at a local dev server (`pnpm dev:web`):
+
+```bash
+testlab login --api-url http://localhost:3000
+testlab import ./tests --api-url http://localhost:3000
+```
+
+## How it relates to the API
+
+Every command is a thin wrapper over the public [Import Test Plans API](https://test-lab.ai/docs/api/test-plans). An agent can call that API directly instead of shelling out to the CLI; the CLI just handles auth storage and import ordering for you.

package/bin/testlab.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * testlab — import existing test plans into test-lab.ai (driveable by a human,
+ * a CI job, or an AI agent).
+ *
+ * Commands:
+ *   testlab login [--key tl_…]              Authenticate (browser flow, or paste/flag a key)
+ *   testlab whoami                          Show the authenticated account
+ *   testlab plans list                      List the account's test plans
+ *   testlab plans create -f plan.json       Create one plan from a JSON file
+ *   testlab plans create --name N --prompt P
+ *   testlab credentials set KEY --value V    Upsert an account credential ({{credentials.KEY}})
+ *   testlab import <path> [--dry-run]        Import a plan file or a directory of *.json
+ *
+ * Auth:  --key  → $TESTLAB_API_KEY → ~/.test-lab/config.json
+ * API:   --api-url → $TESTLAB_API_URL → https://www.test-lab.ai
+ */
+import { parseArgs } from "node:util"
+import fs from "node:fs"
+import readline from "node:readline"
+import { resolveAuth, loadConfig, saveConfig } from "../lib/config.mjs"
+import { apiFetch } from "../lib/api.mjs"
+import { loadImportFile, runImport } from "../lib/import.mjs"
+import { browserLogin } from "../lib/login.mjs"
+
+const log = (...a) => console.log(...a)
+function errExit(msg) {
+  console.error(`error: ${msg}`)
+  process.exit(1)
+}
+
+const HELP = `testlab — import test plans into test-lab.ai
+
+Usage:
+  testlab login [--key tl_…]               Authenticate (browser, or paste/flag a key)
+  testlab whoami                           Show the authenticated account
+  testlab plans list                       List your test plans
+  testlab plans create -f plan.json        Create one plan from JSON
+  testlab plans create --name N --prompt P
+  testlab credentials set KEY --value V     Upsert a credential ({{credentials.KEY}})
+  testlab import <path> [--dry-run]         Import a plan file or directory of *.json
+
+Options:
+  --key <tl_…>      API key (else $TESTLAB_API_KEY or ~/.test-lab/config.json)
+  --api-url <url>   API base (else $TESTLAB_API_URL or https://www.test-lab.ai)
+  --stdin           Read the value (key/credential) from stdin
+  --force           (login) re-authenticate even if a stored key still works
+  --dry-run         (import) validate + print order without writing
+
+Get a key at <api-url>/admin/settings/api-keys`
+
+function parse() {
+  return parseArgs({
+    allowPositionals: true,
+    options: {
+      key: { type: "string" },
+      "api-url": { type: "string" },
+      value: { type: "string" },
+      file: { type: "string", short: "f" },
+      name: { type: "string" },
+      prompt: { type: "string" },
+      "dry-run": { type: "boolean" },
+      stdin: { type: "boolean" },
+      force: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+    },
+  })
+}
+
+function readStdin() {
+  try {
+    return fs.readFileSync(0, "utf8").trim()
+  } catch {
+    return ""
+  }
+}
+
+function promptLine(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise((resolve) => rl.question(question, (a) => {
+    rl.close()
+    resolve(a.trim())
+  }))
+}
+
+function requireAuth(flags) {
+  const { apiKey, apiUrl } = resolveAuth(flags)
+  if (!apiKey) errExit("not authenticated. Run `testlab login` (or set TESTLAB_API_KEY).")
+  return { apiKey, apiUrl }
+}
+
+async function verifyKey(apiUrl, apiKey) {
+  const r = await apiFetch(apiUrl, apiKey, "GET", "/api/v1/test-plans?limit=1")
+  return r
+}
+
+async function cmdLogin(flags) {
+  const { apiUrl, apiKey: existingKey } = resolveAuth(flags)
+
+  // Re-running `testlab login` with a still-valid stored key would otherwise
+  // mint a brand-new server-side key every time (they accrete). Short-circuit
+  // unless the user passed a key explicitly or forced re-auth.
+  if (existingKey && !flags.key && !flags.stdin && !flags.force) {
+    const check = await verifyKey(apiUrl, existingKey)
+    if (check.ok) {
+      log(`✓ Already authenticated to ${apiUrl}. Use --force to re-authenticate.`)
+      return
+    }
+  }
+
+  let apiKey = flags.key || (flags.stdin ? readStdin() : null)
+  let who = null
+
+  if (!apiKey) {
+    try {
+      who = await browserLogin(apiUrl)
+      apiKey = who.apiKey
+    } catch (e) {
+      log(`Browser login unavailable (${e.message}).`)
+      log(`Create a key at ${apiUrl}/admin/settings/api-keys, then paste it below.`)
+      apiKey = await promptLine("API key: ")
+    }
+  }
+  if (!apiKey) errExit("no API key provided")
+
+  const check = await verifyKey(apiUrl, apiKey)
+  if (!check.ok) errExit(`key rejected (${check.status}): ${check.json?.error || "invalid key"}`)
+
+  const cfg = loadConfig()
+  cfg.apiKey = apiKey
+  cfg.apiUrl = apiUrl
+  const path = saveConfig(cfg)
+  log(`✓ Authenticated${who?.email ? ` as ${who.email}` : ""}. Credentials saved to ${path}`)
+}
+
+async function cmdWhoami(flags) {
+  const { apiKey, apiUrl } = requireAuth(flags)
+  const r = await verifyKey(apiUrl, apiKey)
+  if (!r.ok) errExit(`not authenticated (${r.status}): ${r.json?.error || ""}`)
+  log(`✓ Authenticated to ${apiUrl}`)
+  log(`  Test plans in account: ${r.json?.total ?? "?"}`)
+}
+
+async function cmdPlansList(flags) {
+  const { apiKey, apiUrl } = requireAuth(flags)
+  const r = await apiFetch(apiUrl, apiKey, "GET", "/api/v1/test-plans?limit=100")
+  if (!r.ok) errExit(`${r.status}: ${r.json?.error || ""}`)
+  const plans = r.json?.testPlans || []
+  if (plans.length === 0) {
+    log("No test plans yet.")
+    return
+  }
+  for (const p of plans) {
+    const labels = (p.labels || []).map((l) => l.name).join(", ")
+    log(`  #${p.id}  ${p.name}${labels ? `  [${labels}]` : ""}`)
+  }
+  log(`\n${r.json.total} total`)
+}
+
+async function cmdPlansCreate(flags) {
+  const { apiKey, apiUrl } = requireAuth(flags)
+  let plan
+  if (flags.file) {
+    try {
+      plan = JSON.parse(fs.readFileSync(flags.file, "utf8"))
+    } catch (e) {
+      errExit(`could not read ${flags.file}: ${e.message}`)
+    }
+  } else if (flags.name && flags.prompt) {
+    plan = { name: flags.name, prompt: flags.prompt }
+  } else {
+    errExit("provide -f <plan.json>, or both --name and --prompt")
+  }
+  const r = await apiFetch(apiUrl, apiKey, "POST", "/api/v1/test-plans", plan)
+  if (!r.ok) errExit(`${r.status}: ${r.json?.error || ""}`)
+  log(`✓ Created plan #${r.json.testPlan.id}: ${r.json.testPlan.name}`)
+}
+
+async function cmdCredentialsSet(flags, args) {
+  const { apiKey, apiUrl } = requireAuth(flags)
+  const key = args[2]
+  if (!key) errExit("usage: testlab credentials set <key> --value <v>")
+  const value = flags.value ?? (flags.stdin ? readStdin() : null)
+  if (!value) errExit("provide --value <v> or --stdin")
+  const r = await apiFetch(apiUrl, apiKey, "POST", "/api/v1/credentials", { key, value })
+  if (!r.ok) errExit(`${r.status}: ${r.json?.error || ""}`)
+  log(`✓ Set credential ${key}`)
+}
+
+async function cmdImport(flags, args) {
+  const { apiKey, apiUrl } = requireAuth(flags)
+  const target = args[1]
+  if (!target) errExit("usage: testlab import <path> [--dry-run]")
+  let loaded
+  try {
+    loaded = loadImportFile(target)
+  } catch (e) {
+    errExit(e.message)
+  }
+  log(`Importing ${loaded.plans.length} plan(s)${loaded.credentials.length ? ` + ${loaded.credentials.length} credential(s)` : ""} from ${target}`)
+  const res = await runImport({ apiUrl, apiKey, ...loaded, dryRun: flags["dry-run"], log })
+  if (!res.ok && !res.dryRun) process.exit(1)
+}
+
+async function main() {
+  let parsed
+  try {
+    parsed = parse()
+  } catch (e) {
+    errExit(e.message)
+  }
+  const flags = parsed.values
+  const args = parsed.positionals
+
+  if (flags.help || args.length === 0 || args[0] === "help") {
+    log(HELP)
+    return
+  }
+
+  switch (args[0]) {
+    case "login":
+      return cmdLogin(flags)
+    case "whoami":
+      return cmdWhoami(flags)
+    case "plans":
+      if (args[1] === "list") return cmdPlansList(flags)
+      if (args[1] === "create") return cmdPlansCreate(flags)
+      return errExit("usage: testlab plans <list|create>")
+    case "credentials":
+      if (args[1] === "set") return cmdCredentialsSet(flags, args)
+      return errExit("usage: testlab credentials set <key> --value <v>")
+    case "import":
+      return cmdImport(flags, args)
+    default:
+      return errExit(`unknown command: ${args[0]}. Run \`testlab help\`.`)
+  }
+}
+
+main().catch((e) => errExit(e.message))

package/examples/plans.json

@@ -0,0 +1,24 @@
+{
+  "credentials": [
+    { "key": "email", "value": "qa@example.com" },
+    { "key": "password", "value": "replace-me" }
+  ],
+  "plans": [
+    {
+      "ref": "login",
+      "name": "Login",
+      "prompt": "Go to https://app.example.com/login and sign in with {{credentials.email}} / {{credentials.password}}. Confirm the dashboard at https://app.example.com/dashboard loads.",
+      "testType": "quickTest",
+      "agentType": "functional",
+      "labels": ["smoke", "auth"]
+    },
+    {
+      "ref": "checkout",
+      "name": "Checkout after login",
+      "prompt": "Starting on the dashboard, add the first product to the cart and complete checkout. Confirm an order-confirmation page appears with an order number.",
+      "testType": "deepTest",
+      "labels": ["regression"],
+      "preSteps": [{ "ref": "login" }]
+    }
+  ]
+}

package/lib/api.mjs

@@ -0,0 +1,31 @@
+/**
+ * Tiny fetch wrapper for the test-lab public API. Uses global fetch (Node 18+).
+ * Returns { ok, status, json } — json is the parsed body (or { raw } on non-JSON).
+ */
+export async function apiFetch(apiUrl, apiKey, method, pathname, body) {
+  const headers = {}
+  if (apiKey) headers["Authorization"] = `Bearer ${apiKey}`
+  if (body !== undefined) headers["Content-Type"] = "application/json"
+
+  let res
+  try {
+    res = await fetch(`${apiUrl}${pathname}`, {
+      method,
+      headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    })
+  } catch (e) {
+    return { ok: false, status: 0, json: { error: `network error: ${e.message}` } }
+  }
+
+  const text = await res.text()
+  let json = null
+  if (text) {
+    try {
+      json = JSON.parse(text)
+    } catch {
+      json = { raw: text }
+    }
+  }
+  return { ok: res.ok, status: res.status, json }
+}

package/lib/config.mjs

@@ -0,0 +1,44 @@
+/**
+ * Config + auth resolution for the testlab CLI.
+ *
+ * Resolution order (first hit wins):
+ *   API key:  --key flag  →  $TESTLAB_API_KEY  →  ~/.test-lab/config.json
+ *   API base: --api-url    →  $TESTLAB_API_URL   →  config  →  https://www.test-lab.ai
+ */
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+export const DEFAULT_API_URL = "https://www.test-lab.ai"
+const CONFIG_DIR = path.join(os.homedir(), ".test-lab")
+export const CONFIG_PATH = path.join(CONFIG_DIR, "config.json")
+
+export function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8"))
+  } catch {
+    return {}
+  }
+}
+
+export function saveConfig(cfg) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true })
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + "\n", { mode: 0o600 })
+  // writeFileSync's mode only applies on create; force it in case it existed.
+  try {
+    fs.chmodSync(CONFIG_PATH, 0o600)
+  } catch {
+    /* best effort */
+  }
+  return CONFIG_PATH
+}
+
+export function resolveAuth(flags) {
+  const cfg = loadConfig()
+  const apiKey = flags.key || process.env.TESTLAB_API_KEY || cfg.apiKey || null
+  const apiUrl = (flags["api-url"] || process.env.TESTLAB_API_URL || cfg.apiUrl || DEFAULT_API_URL).replace(
+    /\/+$/,
+    ""
+  )
+  return { apiKey, apiUrl }
+}

package/lib/import.mjs

@@ -0,0 +1,145 @@
+/**
+ * Import orchestration: load plan files, topo-sort by pre-step deps, upsert
+ * credentials, then create plans one request each (wiring intra-batch pre-steps
+ * to the concrete ids returned along the way).
+ */
+import fs from "node:fs"
+import path from "node:path"
+import { topoSortPlans } from "./toposort.mjs"
+import { apiFetch } from "./api.mjs"
+
+/**
+ * Load a plan file or a directory of *.json files into { credentials, plans }.
+ * Each file may be: a single plan object, an array of plans, or an object
+ * shaped { credentials?: [...], plans: [...] }.
+ */
+export function loadImportFile(target) {
+  const stat = fs.statSync(target)
+  const files = []
+  if (stat.isDirectory()) {
+    for (const f of fs.readdirSync(target).sort()) {
+      if (f.endsWith(".json")) files.push(path.join(target, f))
+    }
+    if (files.length === 0) throw new Error(`No .json files found in ${target}`)
+  } else {
+    files.push(target)
+  }
+
+  const credentials = []
+  const plans = []
+  for (const file of files) {
+    let data
+    try {
+      data = JSON.parse(fs.readFileSync(file, "utf8"))
+    } catch (e) {
+      throw new Error(`${file}: invalid JSON (${e.message})`)
+    }
+    if (Array.isArray(data)) {
+      plans.push(...data)
+    } else if (data && Array.isArray(data.plans)) {
+      plans.push(...data.plans)
+      if (Array.isArray(data.credentials)) credentials.push(...data.credentials)
+    } else if (data && typeof data.name === "string" && typeof data.prompt === "string") {
+      plans.push(data)
+    } else {
+      throw new Error(`${file}: expected a plan object, an array, or { plans, credentials }`)
+    }
+  }
+  return { credentials, plans }
+}
+
+/** Resolve a plan's preSteps for the API: intra-batch refs → concrete ids. */
+export function normalizePreSteps(preSteps, refToId) {
+  if (!Array.isArray(preSteps) || preSteps.length === 0) return undefined
+  return preSteps.map((ps) => {
+    if (ps.ref != null && refToId.has(ps.ref)) {
+      return { testPlanId: refToId.get(ps.ref), inputValues: ps.inputValues }
+    }
+    if (ps.testPlanId != null) return { testPlanId: ps.testPlanId, inputValues: ps.inputValues }
+    if (ps.name) return { name: ps.name, inputValues: ps.inputValues }
+    // Unreachable: topoSortPlans rejects a ref with no in-batch match and no
+    // name/testPlanId fallback before we get here. Throw loudly rather than
+    // silently shipping a bogus pre-step to the server.
+    throw new Error(`Cannot resolve pre-step: ${JSON.stringify(ps)}`)
+  })
+}
+
+export async function runImport({ apiUrl, apiKey, credentials = [], plans = [], dryRun = false, log = console.log }) {
+  if (plans.length === 0) {
+    log("Nothing to import (0 plans).")
+    return { ok: true, created: 0, failed: 0 }
+  }
+
+  // Basic per-plan shape check before any network calls.
+  for (let i = 0; i < plans.length; i++) {
+    const p = plans[i]
+    if (!p || typeof p.name !== "string" || typeof p.prompt !== "string") {
+      const msg = `Plan #${i + 1} is missing a string name and/or prompt`
+      log(`✗ ${msg}`)
+      return { ok: false, error: msg }
+    }
+  }
+
+  const sorted = topoSortPlans(plans)
+  if (!sorted.ok) {
+    log(`✗ ${sorted.error}`)
+    return { ok: false, error: sorted.error }
+  }
+
+  if (dryRun) {
+    log(`Dry run — ${plans.length} plan(s), ${credentials.length} credential(s). Creation order:`)
+    sorted.order.forEach((idx, n) => {
+      const p = plans[idx]
+      log(`  ${n + 1}. ${p.name}${p.ref ? `  (ref: ${p.ref})` : ""}`)
+    })
+    return { ok: true, dryRun: true }
+  }
+
+  // Credentials first so plans referencing {{credentials.X}} have them.
+  let credOk = 0
+  for (const c of credentials) {
+    if (!c || typeof c.key !== "string") {
+      log(`  ✗ credential: missing key`)
+      continue
+    }
+    const r = await apiFetch(apiUrl, apiKey, "POST", "/api/v1/credentials", { key: c.key, value: c.value })
+    if (r.ok) {
+      credOk++
+      log(`  ✓ credential ${c.key}`)
+    } else {
+      log(`  ✗ credential ${c.key}: ${r.json?.error || r.status}`)
+    }
+  }
+
+  const refToId = new Map()
+  let created = 0
+  let failed = 0
+  for (const idx of sorted.order) {
+    const plan = plans[idx]
+    const payload = {
+      name: plan.name,
+      prompt: plan.prompt,
+      testType: plan.testType,
+      agentType: plan.agentType,
+      devices: plan.devices,
+      labels: plan.labels,
+      cookies: plan.cookies,
+      headers: plan.headers,
+      failOnPreStepFailure: plan.failOnPreStepFailure,
+      preSteps: normalizePreSteps(plan.preSteps, refToId),
+    }
+    const r = await apiFetch(apiUrl, apiKey, "POST", "/api/v1/test-plans", payload)
+    if (r.ok) {
+      created++
+      const id = r.json?.testPlan?.id
+      if (plan.ref != null && id != null) refToId.set(plan.ref, id)
+      log(`  ✓ ${plan.name}${id != null ? ` (#${id})` : ""}`)
+    } else {
+      failed++
+      log(`  ✗ ${plan.name}: ${r.json?.error || r.status}`)
+    }
+  }
+
+  log(`\n${created} plan(s) created, ${failed} failed${credentials.length ? `, ${credOk}/${credentials.length} credential(s)` : ""}`)
+  return { ok: failed === 0, created, failed }
+}

package/lib/login.mjs

@@ -0,0 +1,93 @@
+/**
+ * Browser device-login. Reuses test-lab's existing one-time-code → API-key
+ * handshake (the same pattern the Chrome extension uses):
+ *
+ *   1. CLI starts a localhost callback server + opens the browser to
+ *      <api>/cli/authorize?state=…&port=…
+ *   2. The signed-in user approves; the page redirects to
+ *      http://127.0.0.1:<port>/callback?code=…&state=…
+ *   3. CLI verifies `state`, then exchanges the one-time code for a full-scope
+ *      API key at POST /api/v1/cli/token (direct HTTPS — the secret never rides
+ *      in the browser redirect).
+ *
+ * If the server doesn't support the flow (older deployment) the caller falls
+ * back to manual key paste.
+ */
+import http from "node:http"
+import crypto from "node:crypto"
+import { spawn } from "node:child_process"
+import { apiFetch } from "./api.mjs"
+
+function openBrowser(url) {
+  let cmd
+  let args
+  if (process.platform === "darwin") {
+    cmd = "open"
+    args = [url]
+  } else if (process.platform === "win32") {
+    cmd = "cmd"
+    args = ["/c", "start", "", url]
+  } else {
+    cmd = "xdg-open"
+    args = [url]
+  }
+  try {
+    spawn(cmd, args, { stdio: "ignore", detached: true }).unref()
+  } catch {
+    /* user can open the URL manually */
+  }
+}
+
+export function browserLogin(apiUrl, { timeoutMs = 180000 } = {}) {
+  const state = crypto.randomBytes(16).toString("hex")
+
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(async (req, res) => {
+      const url = new URL(req.url, "http://127.0.0.1")
+      if (url.pathname !== "/callback") {
+        res.writeHead(404)
+        res.end()
+        return
+      }
+      const finish = (status, html) => {
+        res.writeHead(status, { "Content-Type": "text/html" })
+        res.end(`<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;padding:3rem">${html}</body>`)
+      }
+      const code = url.searchParams.get("code")
+      const gotState = url.searchParams.get("state")
+      if (!code || gotState !== state) {
+        finish(400, "<h2>Login failed</h2><p>Invalid state. Return to your terminal and try again.</p>")
+        server.close()
+        clearTimeout(timer)
+        reject(new Error("state mismatch"))
+        return
+      }
+      const r = await apiFetch(apiUrl, null, "POST", "/api/v1/cli/token", { code })
+      if (r.ok && r.json?.apiKey) {
+        finish(200, "<h2>Authorized ✓</h2><p>You can close this tab and return to your terminal.</p>")
+        server.close()
+        clearTimeout(timer)
+        resolve({ apiKey: r.json.apiKey, accountId: r.json.accountId, email: r.json.email })
+      } else {
+        finish(r.status === 404 ? 404 : 400, `<h2>Login failed</h2><p>${r.json?.error || "Token exchange failed."}</p>`)
+        server.close()
+        clearTimeout(timer)
+        reject(new Error(r.json?.error || `token exchange failed (${r.status})`))
+      }
+    })
+
+    server.on("error", (e) => reject(e))
+
+    const timer = setTimeout(() => {
+      server.close()
+      reject(new Error("login timed out after 3 minutes"))
+    }, timeoutMs)
+
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address()
+      const authUrl = `${apiUrl}/cli/authorize?state=${state}&port=${port}`
+      console.log(`Opening your browser to authorize the CLI:\n  ${authUrl}\n`)
+      openBrowser(authUrl)
+    })
+  })
+}

package/lib/toposort.mjs

@@ -0,0 +1,77 @@
+/**
+ * Topologically sort import plans by intra-batch pre-step `ref` dependencies.
+ *
+ * Edge: plan A depends on plan B when A has a preStep `{ ref: <B.ref> }`.
+ * Pre-steps that reference EXISTING plans by `name`/`testPlanId` are NOT
+ * intra-batch edges (the server resolves those) and are ignored here.
+ *
+ * Returns:
+ *   { ok: true,  order: number[] }            // indices into `plans`, deps first
+ *   { ok: false, error: string, refs?: [] }   // duplicate/unknown ref, self-ref, cycle
+ *
+ * Pure + dependency-free so it's unit-testable under plain `node`.
+ */
+export function topoSortPlans(plans) {
+  const n = plans.length
+
+  // Map every declared ref to its plan index (reject duplicates).
+  const refToIndex = new Map()
+  for (let i = 0; i < n; i++) {
+    const ref = plans[i] && plans[i].ref
+    if (ref == null) continue
+    if (typeof ref !== "string" || !ref.trim()) {
+      return { ok: false, error: `Plan #${i + 1} has an invalid ref (must be a non-empty string)` }
+    }
+    if (refToIndex.has(ref)) {
+      return { ok: false, error: `Duplicate plan ref "${ref}"`, refs: [ref] }
+    }
+    refToIndex.set(ref, i)
+  }
+
+  const adjacency = Array.from({ length: n }, () => [])
+  const indegree = new Array(n).fill(0)
+
+  for (let i = 0; i < n; i++) {
+    const preSteps = Array.isArray(plans[i].preSteps) ? plans[i].preSteps : []
+    for (const ps of preSteps) {
+      if (!ps || ps.ref == null) continue // not an intra-batch edge
+      const ref = ps.ref
+      if (ref === plans[i].ref) {
+        return { ok: false, error: `Plan "${ref}" lists itself as a pre-step`, refs: [ref] }
+      }
+      if (!refToIndex.has(ref)) {
+        // A ref pointing outside the batch is only OK if a name/id fallback is
+        // present (then it targets an already-existing plan, server-resolved).
+        if (ps.name || ps.testPlanId) continue
+        return {
+          ok: false,
+          error: `Pre-step ref "${ref}" matches no plan in this import (and has no name/testPlanId fallback)`,
+          refs: [ref],
+        }
+      }
+      const dep = refToIndex.get(ref)
+      adjacency[dep].push(i)
+      indegree[i]++
+    }
+  }
+
+  // Kahn's algorithm (iterative — no recursion depth concerns).
+  const queue = []
+  for (let i = 0; i < n; i++) if (indegree[i] === 0) queue.push(i)
+  const order = []
+  while (queue.length > 0) {
+    const node = queue.shift()
+    order.push(node)
+    for (const next of adjacency[node]) {
+      if (--indegree[next] === 0) queue.push(next)
+    }
+  }
+
+  if (order.length < n) {
+    const cycle = []
+    for (let i = 0; i < n; i++) if (indegree[i] > 0) cycle.push(plans[i].ref ?? `#${i + 1}`)
+    return { ok: false, error: `Pre-step dependency cycle among: ${cycle.join(", ")}`, refs: cycle }
+  }
+
+  return { ok: true, order }
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@test-lab-ai/cli",
+  "version": "0.1.0",
+  "description": "Import existing test plans into test-lab.ai from the command line (or an AI agent).",
+  "type": "module",
+  "bin": {
+    "testlab": "bin/testlab.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "examples",
+    "README.md",
+    "AGENTS.md"
+  ],
+  "scripts": {
+    "test": "node test/toposort.test.mjs",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "test-lab",
+    "test-lab.ai",
+    "testing",
+    "qa",
+    "e2e",
+    "cli"
+  ],
+  "homepage": "https://test-lab.ai",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}