@desplega.ai/qa-use 2.11.0 → 2.13.2

package/dist/src/cli/generated/docs-content.d.ts

@@ -3,7 +3,7 @@
  * DO NOT EDIT MANUALLY — Generated from plugins/qa-use/skills/qa-use/
  * Run 'bun run generate:docs' to regenerate.
  */
-export declare const MAIN_DOC = "---\nname: qa-use\ndescription: E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.\nallowed-tools: Bash(qa-use *)\n---\n\n# qa-use\n\nE2E testing and browser automation for AI-driven development workflows.\n\n## Critical Insight: Plugin Commands as Shortcuts\n\n**For AI Harnesses (codex, opencode, etc.):**\n\nPlugin commands (slash commands like `/qa-use:verify`) are **convenience shortcuts** that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.\n\n**Pattern throughout this document:**\n- **CLI Workflow**: Step-by-step CLI commands (works for ALL harnesses)\n- **Plugin Shortcut**: Optional slash command (convenience)\n\n## Setup & Configuration\n\nBefore using any qa-use commands, verify configuration is in place:\n\n```bash\n# Check current configuration (no-op if already configured)\nqa-use setup\n\n# Configure with API key (validates against server)\nqa-use setup --api-key <key>\n\n# View full configuration details\nqa-use info\n```\n\n**Environment Variables (alternative to config file):**\n\n| Variable | Description |\n|----------|-------------|\n| `QA_USE_API_KEY` | API key for authentication |\n| `QA_USE_REGION` | Region: `us` (default) or `auto` |\n| `QA_USE_API_URL` | Override API base URL |\n\n**Config file:** `.qa-use.json` in the project directory or `~/.qa-use.json` in the home directory. Precedence: env vars > project `.qa-use.json` > `~/.qa-use.json`.\n\n**If you encounter \"API key not configured\", 401, or auth errors:** Run `qa-use setup` to check config state. NEVER fabricate or guess API keys.\n\n## Core Workflow\n\n### 1. Browser Control & Session Lifecycle\n\n**CLI Workflow:**\n```bash\n# Create browser session\nqa-use browser create --viewport desktop\n\n# For localhost testing\nqa-use browser create --tunnel --no-headless\n\n# Navigate\nqa-use browser goto https://example.com\n\n# Snapshot to get element refs (ALWAYS do this before interacting)\nqa-use browser snapshot\n\n# Interact by ref\nqa-use browser click e3\nqa-use browser fill e5 \"text\"\n\n# Close\nqa-use browser close\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore https://example.com\n```\n(Wraps create + goto + snapshot with autonomous exploration)\n\n**Critical:** Always run `snapshot` before your **first** interaction on a page. Never guess element refs.\n\n**Snapshot Diff Feature (use it to avoid unnecessary snapshots):**\nAfter each action (goto, click, fill, etc.), the browser automatically shows DOM changes:\n- **Summary**: \"5 elements added, 1 element modified\"\n- **Added elements**: `+ [e54] generic \"Thanks for agreeing!\"` (green)\n- **Modified elements**: `~ [e18] checkbox \"I agree...\"` with `+attrs: checked, active` (yellow)\n- **Removed elements**: `- [e99] button \"Submit\"` (red)\n\n**When you can skip a full `snapshot`:** If the diff output from your last action already shows the element ref you need to interact with next, use it directly \u2014 no need for an intermediate `snapshot`. For example, if clicking a button shows `+ [e54] button \"Submit\"` in the diff, you can `click e54` immediately.\n\n**When you still need a full `snapshot`:** Run `snapshot` when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows \"... and N more changes\").\n\n### 2. Understanding Blocks\n\n**What are blocks?**\n\nBlocks are atomic recorded interactions from a browser session. They are:\n- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)\n- Stored server-side with the session\n- Retrieved via `qa-use browser get-blocks`\n- The foundation for test generation\n\n**Why blocks matter:**\n- **Record-once, replay-many**: Interactive recording becomes automated test\n- **AI-friendly**: Agents can analyze blocks to understand user intent\n- **Version control**: Blocks stored with session enable test iteration\n- **Bridge CLI \u2192 Tests**: Natural workflow from exploration to automation\n\n**How blocks work:**\n\n```bash\n# 1. Create session and interact\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://example.com\nqa-use browser snapshot        # Returns: [ref=e1] button\nqa-use browser click e1        # Records as block\nqa-use browser fill e5 \"text\"  # Records as block\n\n# 2. Retrieve blocks (JSON array)\nqa-use browser get-blocks\n# Returns:\n# [\n#   {\"type\": \"goto\", \"url\": \"...\", \"timestamp\": \"...\"},\n#   {\"type\": \"click\", \"ref\": \"e1\", \"timestamp\": \"...\"},\n#   {\"type\": \"fill\", \"ref\": \"e5\", \"value\": \"text\", \"timestamp\": \"...\"}\n# ]\n\n# 3. Generate test YAML from blocks\nqa-use browser generate-test -n \"my_test\" -o qa-tests/my_test.yaml\n\n# 4. Run generated test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n(Wraps the interactive workflow with AI-powered test generation)\n\n### 3. Test Management\n\n**CLI Workflow:**\n```bash\n# Run test by name\nqa-use test run login\n\n# Run with autofix (AI self-healing)\nqa-use test run login --autofix\n\n# Validate syntax\nqa-use test validate login\n\n# Show test details\nqa-use test info login\n\n# List test runs\nqa-use test runs --status failed\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:test-run login --autofix\n```\n(Convenience shortcut for common test execution)\n\n### 4. Test Sync Lifecycle\n\n**CLI Workflow:**\n```bash\n# Pull tests from cloud\nqa-use test sync pull\n\n# Push all local tests to cloud\nqa-use test sync push --all\n\n# Push specific test\nqa-use test sync push --id <uuid>\n\n# Force push (overwrite conflicts)\nqa-use test sync push --force\n\n# Compare local vs cloud\nqa-use test diff login.yaml\n```\n\n**No Plugin Shortcut** - Use CLI commands directly\n\n## Essential Commands\n\n### Browser Session Management\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser create` | Create remote browser session |\n| `qa-use browser create <url>` | Create session and navigate to URL |\n| `qa-use browser create --tunnel` | Create local browser with API tunnel |\n| `qa-use browser create --no-headless` | Show browser window (tunnel mode only) |\n| `qa-use browser create --viewport <size>` | Set viewport: `desktop`, `tablet`, `mobile` |\n| `qa-use browser create --ws-url <url>` | Connect to existing WebSocket browser |\n| `qa-use browser create --after-test-id <uuid>` | Run a test first, then become interactive |\n| `qa-use browser create --var <key=value>` | Override app config variables (repeatable) |\n| `qa-use browser list` | List active sessions |\n| `qa-use browser status` | Show current session details (app_url, recording_url, etc.) |\n| `qa-use browser close` | Close active session |\n\nSessions auto-persist in `~/.qa-use.json`. One active session = no `-s` flag needed.\n\n### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser goto <url>` | Navigate to URL |\n| `qa-use browser back` | Go back |\n| `qa-use browser forward` | Go forward |\n| `qa-use browser reload` | Reload page |\n\n### Element Interaction\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser click <ref>` | Click element by ref |\n| `qa-use browser click --text \"Button\"` | Click by semantic description |\n| `qa-use browser fill <ref> \"value\"` | Fill input field |\n| `qa-use browser type <ref> \"text\"` | Type with delays (for autocomplete) |\n| `qa-use browser press <key>` | Press key (e.g., `Enter`, `Tab`) |\n| `qa-use browser check <ref>` | Check checkbox |\n| `qa-use browser uncheck <ref>` | Uncheck checkbox |\n| `qa-use browser select <ref> \"option\"` | Select dropdown option |\n| `qa-use browser hover <ref>` | Hover over element |\n| `qa-use browser scroll down 500` | Scroll by pixels |\n| `qa-use browser scroll-into-view <ref>` | Scroll element into view |\n| `qa-use browser drag <ref> --target <ref>` | Drag element to target |\n| `qa-use browser mfa-totp [ref] <secret>` | Generate TOTP code (optionally fill) |\n| `qa-use browser upload <ref> <file>...` | Upload file(s) to input (base64-encoded, works remote & tunnel) |\n\n### Inspection & Snapshot Diff\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser snapshot` | Get full ARIA tree with element refs (use only when diff output is insufficient) |\n| `qa-use browser url` | Get current URL |\n| `qa-use browser screenshot` | Save screenshot.png |\n| `qa-use browser screenshot file.png` | Save to custom path |\n| `qa-use browser screenshot --base64` | Output base64 to stdout |\n| `qa-use browser evaluate <expression>` | Execute JavaScript in browser context |\n\nThe snapshot-diff feature automatically displays DOM changes after each browser action:\n- **Added elements**: Shown with `+` prefix and green color \u2014 these refs are immediately usable\n- **Modified elements**: Shown with `~` prefix and yellow color, including attribute changes (`+attrs: checked`)\n- **Removed elements**: Shown with `-` prefix and red color \u2014 do NOT use these refs\n\n**Downloads:** When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use `qa-use browser downloads` to list all downloads or `--save <dir>` to save them locally.\n\nUse diff output to interact with newly appeared elements directly, without running a full `snapshot` first.\n\n### Test Operations\n\n| Command | Description |\n|---------|-------------|\n| `qa-use test run <name>` | Run test by name |\n| `qa-use test run --all` | Run all tests |\n| `qa-use test run <name> --tunnel` | Run with local browser tunnel |\n| `qa-use test run <name> --autofix` | Enable AI self-healing |\n| `qa-use test run <name> --update-local` | Persist AI fixes to file |\n| `qa-use test run <name> --download` | Download assets to `/tmp/qa-use/downloads/` |\n| `qa-use test run <name> --var key=value` | Override variable |\n| `qa-use test validate <name>` | Validate test syntax |\n| `qa-use test list` | List available tests |\n| `qa-use test info <name>` | Show test details (steps, tags, description) |\n| `qa-use test info --id <uuid>` | Show cloud test details by ID |\n| `qa-use test runs [name]` | List test run history |\n| `qa-use test runs --id <uuid>` | Filter runs by test ID |\n| `qa-use test runs --status failed` | Filter runs by status |\n| `qa-use test init` | Initialize test directory |\n| `qa-use test sync pull` | Pull tests from cloud |\n| `qa-use test sync push --all` | Push all local tests to cloud |\n| `qa-use test sync push --id <uuid>` | Push specific test |\n| `qa-use test sync push --force` | Push tests, overwriting conflicts |\n| `qa-use test diff <file>` | Compare local vs cloud test |\n| `qa-use test schema [path]` | View test definition schema |\n\n### API Operations (Dynamic OpenAPI)\n\n`qa-use api` dynamically discovers operations from `/api/v1/openapi.json` and caches metadata locally for offline fallback.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use api ls` | List available `/api/v1/*` routes from OpenAPI |\n| `qa-use api ls --refresh` | Force refresh OpenAPI cache |\n| `qa-use api ls --offline` | Use cached OpenAPI metadata only |\n| `qa-use api /api/v1/tests` | Call endpoint (method inferred when possible) |\n| `qa-use api -X GET /api/v1/test-runs -f limit=5` | GET with query fields |\n| `qa-use api -X POST /api/v1/tests-actions/run --input body.json` | POST with JSON body file |\n| `qa-use api -X GET /api/v1/test-runs/<id>` | Fetch detail endpoint by ID |\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### Logs & Debugging\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser logs console` | View console logs from session |\n| `qa-use browser logs console -s <id>` | View logs from specific/closed session |\n| `qa-use browser logs network` | View network request logs |\n| `qa-use browser logs network -s <id>` | View network logs from specific session |\n| `qa-use browser downloads` | List downloaded files from session |\n| `qa-use browser downloads --save <dir>` | Save downloaded files to local directory |\n| `qa-use browser downloads --json` | Output download info as JSON |\n\n### Test Generation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser generate-test` | Generate test YAML from recorded session |\n| `qa-use browser generate-test -s <id>` | Generate from specific session |\n| `qa-use browser generate-test -n <name>` | Specify test name |\n| `qa-use browser generate-test -o <path>` | Specify output path |\n| `qa-use browser get-blocks` | Get recorded interaction blocks (JSON) |\n\n### Waiting\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser wait <ms>` | Fixed wait |\n| `qa-use browser wait-for-selector \".class\"` | Wait for selector |\n| `qa-use browser wait-for-load` | Wait for page load |\n\n### Variable Overrides\n\nUse `--var` to override app config variables at runtime. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `base_url` | Base URL for the app (e.g., preview deployment URL) |\n| `login_url` | Login page URL |\n| `login_username` | Username/email for authentication |\n| `login_password` | Password for authentication |\n\nExample with ephemeral preview URL:\n```bash\nqa-use browser create --after-test-id <login-test-uuid> \\\n  --var base_url=https://preview-123.example.com \\\n  --var login_url=https://preview-123.example.com/auth/login\n```\n\n## Common Patterns\n\n### Pattern 1: Feature Verification\n\n**CLI Workflow:**\n```bash\n# 1. Search for existing test\nqa-use test list | grep \"login\"\n\n# 2. Run test with autofix\nqa-use test run login --autofix\n\n# 3. Debug failures\nqa-use browser logs console\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:verify \"login works with valid credentials\"\n```\n(Wraps the above CLI workflow with AI-powered test discovery and analysis)\n\n### Pattern 2: Record & Generate Test\n\n**CLI Workflow:**\n```bash\n# 1. Create session\nqa-use browser create --tunnel --no-headless\n\n# 2. Navigate and interact\nqa-use browser goto https://example.com\nqa-use browser snapshot\nqa-use browser click e1\nqa-use browser fill e5 \"test\"\n\n# 3. Generate test from blocks\nqa-use browser get-blocks\nqa-use browser generate-test -n \"my_test\"\n\n# 4. Run test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n\n### Pattern 3: Authenticated Exploration\n\n**CLI Workflow:**\n```bash\n# Create session that runs login test first\nqa-use browser create --after-test-id <login-test-uuid>\n\n# Session now authenticated, explore\nqa-use browser goto /dashboard\nqa-use browser snapshot\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore /dashboard\n```\n(Automatically handles auth detection and session creation)\n\n### Pattern 4: Edit Existing Test\n\n**CLI Workflow:**\n```bash\n# 1. Open test file in editor\nvim qa-tests/login.yaml\n\n# 2. Validate syntax\nqa-use test validate login\n\n# 3. Run to verify\nqa-use test run login\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record edit login\n```\n(AI-assisted editing with validation)\n\n### Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots\n\n**CLI Workflow:**\n```bash\n# Create session and navigate\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://evals.desplega.ai/checkboxes\n\n# goto shows diff \u2014 initial page load shows all elements:\n# Changes: 45 elements added\n# + [e18] checkbox \"I agree to the terms and conditions\"\n# + [e19] generic \"I agree to the terms and conditions\"\n\n# \u2705 Use ref from diff directly \u2014 no snapshot needed!\nqa-use browser click e18\n\n# Diff shows what changed:\n# Changes: 5 elements added, 1 element modified\n# + [e54] generic \"Thanks for agreeing!\"\n# + [e55] link \"Terms and Conditions\"\n# ~ [e18] checkbox \"I agree to the terms and conditions\"\n#     +attrs: active, checked\n\n# \u2705 Can click e55 directly from diff output \u2014 no snapshot needed!\nqa-use browser click e55\n\n# \u274C Need to find an element NOT in the diff? Now run snapshot:\nqa-use browser snapshot\n```\n\n**Key principle:** Use diff output as your primary source of element refs after actions. Only fall back to `snapshot` when you need to find elements that weren't in the diff.\n\n**Benefits:**\n- Fewer API calls = faster automation\n- Diff refs are always fresh (just returned from the server)\n- Instantly see what changed (new elements, attribute changes, removals)\n\n**No Plugin Shortcut** - Automatic feature in all browser commands\n\n## CI/CD Integration\n\n### Running Tests in CI\n\n**Environment Variables:**\n```bash\nexport QA_USE_API_KEY=\"your-api-key\"\nexport QA_USE_REGION=\"us\"  # Optional: \"us\" or \"auto\"\n```\n\n**Basic Test Execution:**\n```bash\n# Run all tests\nqa-use test run --all\n\n# Run specific tag\nqa-use test run --tag smoke\n\n# Exit codes: 0 = pass, 1 = fail\n```\n\n### GitHub Actions Example\n\n```yaml\nname: QA Tests\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n      - name: Install qa-use\n        run: npm install -g @desplega.ai/qa-use\n      - name: Run tests\n        run: qa-use test run --all\n        env:\n          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}\n```\n\n### Test Artifacts\n\n**Screenshots:**\n- Automatically saved on failure\n- Location: `/tmp/qa-use/downloads/` (local) or cloud (remote)\n\n**Logs:**\n- Console logs: `qa-use browser logs console -s <session-id>`\n- Network logs: `qa-use browser logs network -s <session-id>`\n\n## Advanced Topics\n\n### Localhost Testing (Tunnel Mode)\n\n**When to use tunnel mode:**\n\n```\nTesting localhost (http://localhost:3000)?\n  \u251C\u2500 YES \u2192 Use --tunnel\n  \u2502   \u2514\u2500 qa-use browser create --tunnel [--no-headless]\n  \u2502       (Starts local Playwright, creates localtunnel, keeps running)\n  \u2502\n  \u2514\u2500 NO (Public URL) \u2192 Use remote browser (default)\n      \u2514\u2500 qa-use browser create\n          (Uses desplega.ai cloud browser via WebSocket)\n```\n\n**The `--tunnel` flag is a binary choice:**\n- **Local tunnel mode**: Playwright on your machine + localtunnel\n- **Remote mode**: WebSocket URL to cloud-hosted browser\n\n**For test execution:**\n```bash\n# Local app\nqa-use test run my_test --tunnel [--headful]\n\n# Public app\nqa-use test run my_test\n```\n\n**Plugin shortcuts handle tunnel detection automatically:**\n```\n/qa-use:explore http://localhost:3000\n/qa-use:record start local_test\n```\n\nSee [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.\n\n### Session Persistence\n\nSessions are stored in `~/.qa-use.json` and have:\n- **TTL**: 30 minutes (default)\n- **Auto-resolve**: One active session = no `-s` flag needed\n- **Cleanup**: Automatic on timeout or explicit `browser close`\n\n### Block Limitations\n\n**What's captured:**\n- goto, click, fill, type, check, uncheck, select, hover\n- scroll, scroll-into-view, drag, upload, press\n\n**What's NOT captured:**\n- Assertions (must be added manually)\n- Waits (inferred from timing, may need adjustment)\n- Complex interactions (multi-drag, hover sequences)\n\n**Manual editing:** Edit generated YAML to add assertions and refine selectors.\n\n### WebSocket Sessions\n\n**Sharing sessions across processes:**\n```bash\n# Process 1: Create session\nqa-use browser create --tunnel\n# Output: ws://localhost:12345/browser/abc123\n\n# Process 2: Connect to session\nqa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123\n```\n\n## Deep-Dive References\n\nAccess any reference at runtime via the CLI: `qa-use docs <topic>`\n\n| Topic | CLI Command | Description |\n|-------|-------------|-------------|\n| [browser-commands.md](references/browser-commands.md) | `qa-use docs browser-commands` | Complete browser CLI reference with all flags |\n| [test-format.md](references/test-format.md) | `qa-use docs test-format` | Full test YAML specification |\n| [localhost-testing.md](references/localhost-testing.md) | `qa-use docs localhost-testing` | Tunnel setup for local development |\n| [failure-debugging.md](references/failure-debugging.md) | `qa-use docs failure-debugging` | Failure classification and diagnostics |\n| [ci.md](references/ci.md) | `qa-use docs ci` | CI/CD integration patterns and examples |\n\nUse `qa-use docs --list` to discover all available topics and templates.\n\n## Templates\n\n| Template | Description |\n|----------|-------------|\n| [basic-test.yaml](templates/basic-test.yaml) | Simple navigation and assertion |\n| [auth-flow.yaml](templates/auth-flow.yaml) | Login flow with credentials |\n| [form-test.yaml](templates/form-test.yaml) | Form submission with validation |\n\n## Test Format Overview\n\n```yaml\nname: Login Test\ndescription: Validates login functionality with valid credentials\ntags:\n  - smoke\n  - auth\napp_config: <app-config-id>\nvariables:\n  email: test@example.com\n  password: secret123\ndepends_on: setup-test  # Optional\nsteps:\n  - action: goto\n    url: /login\n  - action: fill\n    target: email input\n    value: $email\n  - action: click\n    target: login button\n  - action: to_be_visible\n    target: dashboard\n```\n\nSee [references/test-format.md](references/test-format.md) for complete specification.\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Correct |\n|---------|-----------|\n| `browser navigate <url>` | `browser goto <url>` |\n| `browser destroy` | `browser close` |\n| `browser close <session-id>` | `browser close` |\n| Guessing element refs | Use refs from diff output or `snapshot` |\n| Running `snapshot` after every action | Use diff output; only `snapshot` when needed |\n| Testing localhost without `--tunnel` | Use `--tunnel` flag |\n| `test sync --pull` | `test sync pull` (subcommand, not flag) |\n| `test sync --push` | `test sync push` (subcommand, not flag) |\n\n## Troubleshooting\n\nWhen stuck or encountering unexpected errors, use the built-in documentation:\n\n```bash\n# Check configuration state\nqa-use setup\n\n# Browse main documentation\nqa-use docs\n\n# List all available topics\nqa-use docs --list\n\n# Access specific topic\nqa-use docs <topic>\n```\n\n| Situation | Command |\n|-----------|---------|\n| Auth / API key errors | `qa-use setup` then `qa-use docs` |\n| Unknown browser command | `qa-use docs browser-commands` |\n| Test failures | `qa-use docs failure-debugging` |\n| Localhost / tunnel issues | `qa-use docs localhost-testing` |\n| Test YAML syntax | `qa-use docs test-format` |\n| CI/CD setup | `qa-use docs ci` |\n\n**Key rules:**\n- ALWAYS consult `qa-use docs` before improvising workarounds\n- NEVER fabricate API keys, tokens, URLs, or credentials\n- If `qa-use setup` shows no config, report it \u2014 don't guess\n\n## npx Alternative\n\nAll commands use `qa-use` assuming global install. For one-off use:\n```bash\nnpx @desplega.ai/qa-use browser <command>\n```\n";
+export declare const MAIN_DOC = "---\nname: qa-use\ndescription: E2E testing and browser automation with qa-use CLI. Use when the user needs to run tests, verify features, automate browser interactions, or debug test failures.\nallowed-tools: Bash(qa-use *)\n---\n\n# qa-use\n\nE2E testing and browser automation for AI-driven development workflows.\n\n## Critical Insight: Plugin Commands as Shortcuts\n\n**For AI Harnesses (codex, opencode, etc.):**\n\nPlugin commands (slash commands like `/qa-use:verify`) are **convenience shortcuts** that wrap CLI workflows. Harnesses with only the Bash tool can access ALL functionality via CLI commands documented below.\n\n**Pattern throughout this document:**\n- **CLI Workflow**: Step-by-step CLI commands (works for ALL harnesses)\n- **Plugin Shortcut**: Optional slash command (convenience)\n\n## Setup & Configuration\n\nBefore using any qa-use commands, verify configuration is in place:\n\n```bash\n# Check current configuration (no-op if already configured)\nqa-use setup\n\n# Configure with API key (validates against server)\nqa-use setup --api-key <key>\n\n# View full configuration details\nqa-use info\n```\n\n**Environment Variables (alternative to config file):**\n\n| Variable | Description |\n|----------|-------------|\n| `QA_USE_API_KEY` | API key for authentication |\n| `QA_USE_REGION` | Region: `us` (default) or `auto` |\n| `QA_USE_API_URL` | Override API base URL |\n\n**Config file:** `.qa-use.json` in the project directory or `~/.qa-use.json` in the home directory. Precedence: env vars > project `.qa-use.json` > `~/.qa-use.json`.\n\n**If you encounter \"API key not configured\", 401, or auth errors:** Run `qa-use setup` to check config state. NEVER fabricate or guess API keys.\n\n## Core Workflow\n\n### 1. Browser Control & Session Lifecycle\n\n**CLI Workflow:**\n```bash\n# Create browser session\nqa-use browser create --viewport desktop\n\n# For localhost testing\nqa-use browser create --tunnel --no-headless\n\n# Navigate\nqa-use browser goto https://example.com\n\n# Snapshot to get element refs (ALWAYS do this before interacting)\nqa-use browser snapshot\n\n# Interact by ref\nqa-use browser click e3\nqa-use browser fill e5 \"text\"\n\n# Close\nqa-use browser close\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore https://example.com\n```\n(Wraps create + goto + snapshot with autonomous exploration)\n\n**Critical:** Always run `snapshot` before your **first** interaction on a page. Never guess element refs.\n\n**Snapshot Diff Feature (use it to avoid unnecessary snapshots):**\nAfter each action (goto, click, fill, etc.), the browser automatically shows DOM changes:\n- **Summary**: \"5 elements added, 1 element modified\"\n- **Added elements**: `+ [e54] generic \"Thanks for agreeing!\"` (green)\n- **Modified elements**: `~ [e18] checkbox \"I agree...\"` with `+attrs: checked, active` (yellow)\n- **Removed elements**: `- [e99] button \"Submit\"` (red)\n\n**When you can skip a full `snapshot`:** If the diff output from your last action already shows the element ref you need to interact with next, use it directly \u2014 no need for an intermediate `snapshot`. For example, if clicking a button shows `+ [e54] button \"Submit\"` in the diff, you can `click e54` immediately.\n\n**When you still need a full `snapshot`:** Run `snapshot` when you need to find elements that weren't in the diff (e.g., pre-existing elements you haven't interacted with yet), or when the diff was truncated (shows \"... and N more changes\").\n\n### 2. Understanding Blocks\n\n**What are blocks?**\n\nBlocks are atomic recorded interactions from a browser session. They are:\n- Automatically captured during any browser interaction (click, fill, goto, scroll, etc.)\n- Stored server-side with the session\n- Retrieved via `qa-use browser get-blocks`\n- The foundation for test generation\n\n**Why blocks matter:**\n- **Record-once, replay-many**: Interactive recording becomes automated test\n- **AI-friendly**: Agents can analyze blocks to understand user intent\n- **Version control**: Blocks stored with session enable test iteration\n- **Bridge CLI \u2192 Tests**: Natural workflow from exploration to automation\n\n**How blocks work:**\n\n```bash\n# 1. Create session and interact\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://example.com\nqa-use browser snapshot        # Returns: [ref=e1] button\nqa-use browser click e1        # Records as block\nqa-use browser fill e5 \"text\"  # Records as block\n\n# 2. Retrieve blocks (JSON array)\nqa-use browser get-blocks\n# Returns:\n# [\n#   {\"type\": \"goto\", \"url\": \"...\", \"timestamp\": \"...\"},\n#   {\"type\": \"click\", \"ref\": \"e1\", \"timestamp\": \"...\"},\n#   {\"type\": \"fill\", \"ref\": \"e5\", \"value\": \"text\", \"timestamp\": \"...\"}\n# ]\n\n# 3. Generate test YAML from blocks\nqa-use browser generate-test -n \"my_test\" -o qa-tests/my_test.yaml\n\n# 4. Run generated test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n(Wraps the interactive workflow with AI-powered test generation)\n\n### 3. Test Management\n\n**CLI Workflow:**\n```bash\n# Run test by name\nqa-use test run login\n\n# Run with autofix (AI self-healing)\nqa-use test run login --autofix\n\n# Run and save the (non-synced) local test to cloud\nqa-use test run login --persist\n\n# Validate syntax\nqa-use test validate login\n\n# Show test details\nqa-use test info login\n\n# List test runs\nqa-use test runs --status failed\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:test-run login --autofix\n```\n(Convenience shortcut for common test execution)\n\n### 4. Test Sync Lifecycle\n\n**CLI Workflow:**\n```bash\n# Pull tests from cloud\nqa-use test sync pull\n\n# Push all local tests to cloud\nqa-use test sync push --all\n\n# Push specific test\nqa-use test sync push --id <uuid>\n\n# Force push (overwrite conflicts)\nqa-use test sync push --force\n\n# Compare local vs cloud\nqa-use test diff login.yaml\n```\n\n**Persist vs Sync:**\n\nA local test is **synced** when its YAML has both an `id:` and a `version_hash:`\n(these are written back by `test sync push`/`pull`). `--persist` on `test run`\nand `qa-use test sync` are related but not the same:\n\n| Local file state | `persist` | What happens at run time |\n|---|---|---|\n| Non-synced | `false` (default) | Runs locally; nothing saved to cloud. Re-run with `--persist` or use `test sync push` to persist. |\n| Non-synced | `true` | Test is uploaded as a **new** cloud entry after the run. Re-running like this creates **duplicates** \u2014 prefer `test sync push` once the file tracks the cloud id. |\n| Synced | `false` | Runs against the cloud-tracked definition; no extra write. |\n| Synced | `true` | Cloud definition is **upserted** (may overwrite newer cloud edits). Use `test sync push`/`pull` for explicit version control. |\n\nRule of thumb: `test sync push`/`pull` is the deliberate path. Reserve `--persist`\n(or `defaults.persist: true` in `.qa-use.json`) for one-off uploads of brand-new\nlocal tests.\n\n**No Plugin Shortcut** - Use CLI commands directly\n\n## Essential Commands\n\n### Browser Session Management\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser create` | Create remote browser session |\n| `qa-use browser create <url>` | Create session and navigate to URL |\n| `qa-use browser create --tunnel` | Create local browser with API tunnel |\n| `qa-use browser create --no-headless` | Show browser window (tunnel mode only) |\n| `qa-use browser create --viewport <size>` | Set viewport: `desktop`, `tablet`, `mobile` |\n| `qa-use browser create --ws-url <url>` | Connect to existing WebSocket browser |\n| `qa-use browser create --after-test-id <uuid>` | Run a test first, then become interactive |\n| `qa-use browser create --var <key=value>` | Override app config variables (repeatable) |\n| `qa-use browser list` | List active sessions |\n| `qa-use browser status` | Show current session details (app_url, recording_url, etc.) |\n| `qa-use browser close` | Close active session |\n\nSessions auto-persist in `~/.qa-use.json`. One active session = no `-s` flag needed.\n\n### Navigation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser goto <url>` | Navigate to URL |\n| `qa-use browser back` | Go back |\n| `qa-use browser forward` | Go forward |\n| `qa-use browser reload` | Reload page |\n\n### Element Interaction\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser click <ref>` | Click element by ref |\n| `qa-use browser click --text \"Button\"` | Click by semantic description |\n| `qa-use browser fill <ref> \"value\"` | Fill input field |\n| `qa-use browser type <ref> \"text\"` | Type with delays (for autocomplete) |\n| `qa-use browser press <key>` | Press key (e.g., `Enter`, `Tab`) |\n| `qa-use browser check <ref>` | Check checkbox |\n| `qa-use browser uncheck <ref>` | Uncheck checkbox |\n| `qa-use browser select <ref> \"option\"` | Select dropdown option |\n| `qa-use browser hover <ref>` | Hover over element |\n| `qa-use browser scroll down 500` | Scroll by pixels |\n| `qa-use browser scroll-into-view <ref>` | Scroll element into view |\n| `qa-use browser drag <ref> --target <ref>` | Drag element to target |\n| `qa-use browser mfa-totp [ref] <secret>` | Generate TOTP code (optionally fill) |\n| `qa-use browser upload <ref> <file>...` | Upload file(s) to input (base64-encoded, works remote & tunnel) |\n\n### Inspection & Snapshot Diff\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser snapshot` | Get full ARIA tree with element refs (use only when diff output is insufficient) |\n| `qa-use browser url` | Get current URL |\n| `qa-use browser screenshot` | Save screenshot.png |\n| `qa-use browser screenshot file.png` | Save to custom path |\n| `qa-use browser screenshot --base64` | Output base64 to stdout |\n| `qa-use browser evaluate <expression>` | Execute JavaScript in browser context |\n\nThe snapshot-diff feature automatically displays DOM changes after each browser action:\n- **Added elements**: Shown with `+` prefix and green color \u2014 these refs are immediately usable\n- **Modified elements**: Shown with `~` prefix and yellow color, including attribute changes (`+attrs: checked`)\n- **Removed elements**: Shown with `-` prefix and red color \u2014 do NOT use these refs\n\n**Downloads:** When an action triggers a file download (e.g., clicking a download link), the response includes download info: filename, size, and a presigned URL. Use `qa-use browser downloads` to list all downloads or `--save <dir>` to save them locally.\n\nUse diff output to interact with newly appeared elements directly, without running a full `snapshot` first.\n\n### Test Operations\n\n| Command | Description |\n|---------|-------------|\n| `qa-use test run <name>` | Run test by name |\n| `qa-use test run --all` | Run all tests |\n| `qa-use test run <name> --tunnel` | Run with local browser tunnel |\n| `qa-use test run <name> --autofix` | Enable AI self-healing |\n| `qa-use test run <name> --update-local` | Persist AI fixes to file |\n| `qa-use test run <name> --download` | Download assets to `/tmp/qa-use/downloads/` |\n| `qa-use test run <name> --var key=value` | Override variable |\n| `qa-use test validate <name>` | Validate test syntax |\n| `qa-use test list` | List available tests |\n| `qa-use test info <name>` | Show test details (steps, tags, description) |\n| `qa-use test info --id <uuid>` | Show cloud test details by ID |\n| `qa-use test runs [name]` | List test run history |\n| `qa-use test runs --id <uuid>` | Filter runs by test ID |\n| `qa-use test runs --status failed` | Filter runs by status |\n| `qa-use test init` | Initialize test directory |\n| `qa-use test sync pull` | Pull tests from cloud |\n| `qa-use test sync push --all` | Push all local tests to cloud |\n| `qa-use test sync push --id <uuid>` | Push specific test |\n| `qa-use test sync push --force` | Push tests, overwriting conflicts |\n| `qa-use test diff <file>` | Compare local vs cloud test |\n| `qa-use test schema [path]` | View test definition schema |\n\n### API Operations (Dynamic OpenAPI)\n\n`qa-use api` dynamically discovers operations from `/api/v1/openapi.json` and caches metadata locally for offline fallback.\n\n| Command | Description |\n|---------|-------------|\n| `qa-use api` | Show help and available subcommands |\n| `qa-use api ls` | List available `/api/v1/*` routes from OpenAPI |\n| `qa-use api ls --refresh` | Force refresh OpenAPI cache |\n| `qa-use api ls --offline` | Use cached OpenAPI metadata only |\n| `qa-use api info /api/v1/<route>` | Show route details: parameters, request body, responses |\n| `qa-use api info /api/v1/<route> -X POST` | Show info for specific HTTP method |\n| `qa-use api info /api/v1/<route> --json` | Route info as JSON |\n| `qa-use api examples` | Show usage examples |\n| `qa-use api openapi` | Print OpenAPI spec URL |\n| `qa-use api openapi --raw` | Dump full OpenAPI spec as JSON |\n| `qa-use api /api/v1/tests` | Call endpoint (method inferred when possible) |\n| `qa-use api -X GET /api/v1/test-runs -f limit=5` | GET with query fields |\n| `qa-use api -X POST /api/v1/tests-actions/run --input body.json` | POST with JSON body file |\n| `qa-use api -X GET /api/v1/test-runs/<id>` | Fetch detail endpoint by ID |\n\n**No Plugin Shortcut** - Use CLI commands directly.\n\n### Logs & Debugging\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser logs console` | View console logs from session |\n| `qa-use browser logs console -s <id>` | View logs from specific/closed session |\n| `qa-use browser logs network` | View network request logs |\n| `qa-use browser logs network -s <id>` | View network logs from specific session |\n| `qa-use browser downloads` | List downloaded files from session |\n| `qa-use browser downloads --save <dir>` | Save downloaded files to local directory |\n| `qa-use browser downloads --json` | Output download info as JSON |\n\n### Test Generation\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser generate-test` | Generate test YAML from recorded session |\n| `qa-use browser generate-test -s <id>` | Generate from specific session |\n| `qa-use browser generate-test -n <name>` | Specify test name |\n| `qa-use browser generate-test -o <path>` | Specify output path |\n| `qa-use browser get-blocks` | Get recorded interaction blocks (JSON) |\n\n### Waiting\n\n| Command | Description |\n|---------|-------------|\n| `qa-use browser wait <ms>` | Fixed wait |\n| `qa-use browser wait-for-selector \".class\"` | Wait for selector |\n| `qa-use browser wait-for-load` | Wait for page load |\n\n### Variable Overrides\n\nUse `--var` to override app config variables at runtime. Common variables:\n\n| Variable | Description |\n|----------|-------------|\n| `base_url` | Base URL for the app (e.g., preview deployment URL) |\n| `login_url` | Login page URL |\n| `login_username` | Username/email for authentication |\n| `login_password` | Password for authentication |\n\nExample with ephemeral preview URL:\n```bash\nqa-use browser create --after-test-id <login-test-uuid> \\\n  --var base_url=https://preview-123.example.com \\\n  --var login_url=https://preview-123.example.com/auth/login\n```\n\n## Common Patterns\n\n### Pattern 1: Feature Verification\n\n**CLI Workflow:**\n```bash\n# 1. Search for existing test\nqa-use test list | grep \"login\"\n\n# 2. Run test with autofix\nqa-use test run login --autofix\n\n# 3. Debug failures\nqa-use browser logs console\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:verify \"login works with valid credentials\"\n```\n(Wraps the above CLI workflow with AI-powered test discovery and analysis)\n\n### Pattern 2: Record & Generate Test\n\n**CLI Workflow:**\n```bash\n# 1. Create session\nqa-use browser create --tunnel --no-headless\n\n# 2. Navigate and interact\nqa-use browser goto https://example.com\nqa-use browser snapshot\nqa-use browser click e1\nqa-use browser fill e5 \"test\"\n\n# 3. Generate test from blocks\nqa-use browser get-blocks\nqa-use browser generate-test -n \"my_test\"\n\n# 4. Run test\nqa-use test run my_test\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record start my_test\n# ... perform interactions ...\n/qa-use:record stop\n```\n\n### Pattern 3: Authenticated Exploration\n\n**CLI Workflow:**\n```bash\n# Create session that runs login test first\nqa-use browser create --after-test-id <login-test-uuid>\n\n# Session now authenticated, explore\nqa-use browser goto /dashboard\nqa-use browser snapshot\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:explore /dashboard\n```\n(Automatically handles auth detection and session creation)\n\n### Pattern 4: Edit Existing Test\n\n**CLI Workflow:**\n```bash\n# 1. Open test file in editor\nvim qa-tests/login.yaml\n\n# 2. Validate syntax\nqa-use test validate login\n\n# 3. Run to verify\nqa-use test run login\n```\n\n**Plugin Shortcut:**\n```\n/qa-use:record edit login\n```\n(AI-assisted editing with validation)\n\n### Pattern 5: Using Snapshot Diff to Avoid Unnecessary Snapshots\n\n**CLI Workflow:**\n```bash\n# Create session and navigate\nqa-use browser create --tunnel --no-headless\nqa-use browser goto https://evals.desplega.ai/checkboxes\n\n# goto shows diff \u2014 initial page load shows all elements:\n# Changes: 45 elements added\n# + [e18] checkbox \"I agree to the terms and conditions\"\n# + [e19] generic \"I agree to the terms and conditions\"\n\n# \u2705 Use ref from diff directly \u2014 no snapshot needed!\nqa-use browser click e18\n\n# Diff shows what changed:\n# Changes: 5 elements added, 1 element modified\n# + [e54] generic \"Thanks for agreeing!\"\n# + [e55] link \"Terms and Conditions\"\n# ~ [e18] checkbox \"I agree to the terms and conditions\"\n#     +attrs: active, checked\n\n# \u2705 Can click e55 directly from diff output \u2014 no snapshot needed!\nqa-use browser click e55\n\n# \u274C Need to find an element NOT in the diff? Now run snapshot:\nqa-use browser snapshot\n```\n\n**Key principle:** Use diff output as your primary source of element refs after actions. Only fall back to `snapshot` when you need to find elements that weren't in the diff.\n\n**Benefits:**\n- Fewer API calls = faster automation\n- Diff refs are always fresh (just returned from the server)\n- Instantly see what changed (new elements, attribute changes, removals)\n\n**No Plugin Shortcut** - Automatic feature in all browser commands\n\n## CI/CD Integration\n\n### Running Tests in CI\n\n**Environment Variables:**\n```bash\nexport QA_USE_API_KEY=\"your-api-key\"\nexport QA_USE_REGION=\"us\"  # Optional: \"us\" or \"auto\"\n```\n\n**Basic Test Execution:**\n```bash\n# Run all tests\nqa-use test run --all\n\n# Run specific tag\nqa-use test run --tag smoke\n\n# Exit codes: 0 = pass, 1 = fail\n```\n\n### GitHub Actions Example\n\n```yaml\nname: QA Tests\non: [push, pull_request]\n\njobs:\n  test:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v3\n      - uses: actions/setup-node@v3\n        with:\n          node-version: '20'\n      - name: Install qa-use\n        run: npm install -g @desplega.ai/qa-use\n      - name: Run tests\n        run: qa-use test run --all\n        env:\n          QA_USE_API_KEY: ${{ secrets.QA_USE_API_KEY }}\n```\n\n### Test Artifacts\n\n**Screenshots:**\n- Automatically saved on failure\n- Location: `/tmp/qa-use/downloads/` (local) or cloud (remote)\n\n**Logs:**\n- Console logs: `qa-use browser logs console -s <session-id>`\n- Network logs: `qa-use browser logs network -s <session-id>`\n\n## Advanced Topics\n\n### Localhost Testing (Tunnel Mode)\n\n**When to use tunnel mode:**\n\n```\nTesting localhost (http://localhost:3000)?\n  \u251C\u2500 YES \u2192 Use --tunnel\n  \u2502   \u2514\u2500 qa-use browser create --tunnel [--no-headless]\n  \u2502       (Starts local Playwright, creates localtunnel, keeps running)\n  \u2502\n  \u2514\u2500 NO (Public URL) \u2192 Use remote browser (default)\n      \u2514\u2500 qa-use browser create\n          (Uses desplega.ai cloud browser via WebSocket)\n```\n\n**The `--tunnel` flag is a binary choice:**\n- **Local tunnel mode**: Playwright on your machine + localtunnel\n- **Remote mode**: WebSocket URL to cloud-hosted browser\n\n**For test execution:**\n```bash\n# Local app\nqa-use test run my_test --tunnel [--headful]\n\n# Public app\nqa-use test run my_test\n```\n\n**Plugin shortcuts handle tunnel detection automatically:**\n```\n/qa-use:explore http://localhost:3000\n/qa-use:record start local_test\n```\n\nSee [references/localhost-testing.md](references/localhost-testing.md) for troubleshooting.\n\n### Session Persistence\n\nSessions are stored in `~/.qa-use.json` and have:\n- **TTL**: 30 minutes (default)\n- **Auto-resolve**: One active session = no `-s` flag needed\n- **Cleanup**: Automatic on timeout or explicit `browser close`\n\n### Block Limitations\n\n**What's captured:**\n- goto, click, fill, type, check, uncheck, select, hover\n- scroll, scroll-into-view, drag, upload, press\n\n**What's NOT captured:**\n- Assertions (must be added manually)\n- Waits (inferred from timing, may need adjustment)\n- Complex interactions (multi-drag, hover sequences)\n\n**Manual editing:** Edit generated YAML to add assertions and refine selectors.\n\n### WebSocket Sessions\n\n**Sharing sessions across processes:**\n```bash\n# Process 1: Create session\nqa-use browser create --tunnel\n# Output: ws://localhost:12345/browser/abc123\n\n# Process 2: Connect to session\nqa-use browser goto https://example.com --ws-url ws://localhost:12345/browser/abc123\n```\n\n## Deep-Dive References\n\nAccess any reference at runtime via the CLI: `qa-use docs <topic>`\n\n| Topic | CLI Command | Description |\n|-------|-------------|-------------|\n| [browser-commands.md](references/browser-commands.md) | `qa-use docs browser-commands` | Complete browser CLI reference with all flags |\n| [test-format.md](references/test-format.md) | `qa-use docs test-format` | Full test YAML specification |\n| [localhost-testing.md](references/localhost-testing.md) | `qa-use docs localhost-testing` | Tunnel setup for local development |\n| [failure-debugging.md](references/failure-debugging.md) | `qa-use docs failure-debugging` | Failure classification and diagnostics |\n| [ci.md](references/ci.md) | `qa-use docs ci` | CI/CD integration patterns and examples |\n\nUse `qa-use docs --list` to discover all available topics and templates.\n\n## Templates\n\n| Template | Description |\n|----------|-------------|\n| [basic-test.yaml](templates/basic-test.yaml) | Simple navigation and assertion |\n| [auth-flow.yaml](templates/auth-flow.yaml) | Login flow with credentials |\n| [form-test.yaml](templates/form-test.yaml) | Form submission with validation |\n\n## Test Format Overview\n\n```yaml\nname: Login Test\ndescription: Validates login functionality with valid credentials\ntags:\n  - smoke\n  - auth\napp_config: <app-config-id>\nvariables:\n  email: test@example.com\n  password: secret123\ndepends_on: setup-test  # Optional\nsteps:\n  - action: goto\n    url: /login\n  - action: fill\n    target: email input\n    value: $email\n  - action: click\n    target: login button\n  - action: to_be_visible\n    target: dashboard\n```\n\nSee [references/test-format.md](references/test-format.md) for complete specification.\n\n## Common Mistakes\n\n| \u274C Wrong | \u2705 Correct |\n|---------|-----------|\n| `browser navigate <url>` | `browser goto <url>` |\n| `browser destroy` | `browser close` |\n| `browser close <session-id>` | `browser close` |\n| Guessing element refs | Use refs from diff output or `snapshot` |\n| Running `snapshot` after every action | Use diff output; only `snapshot` when needed |\n| Testing localhost without `--tunnel` | Use `--tunnel` flag |\n| `test sync --pull` | `test sync pull` (subcommand, not flag) |\n| `test sync --push` | `test sync push` (subcommand, not flag) |\n\n## Troubleshooting\n\nWhen stuck or encountering unexpected errors, use the built-in documentation:\n\n```bash\n# Check configuration state\nqa-use setup\n\n# Browse main documentation\nqa-use docs\n\n# List all available topics\nqa-use docs --list\n\n# Access specific topic\nqa-use docs <topic>\n```\n\n| Situation | Command |\n|-----------|---------|\n| Auth / API key errors | `qa-use setup` then `qa-use docs` |\n| Unknown browser command | `qa-use docs browser-commands` |\n| Test failures | `qa-use docs failure-debugging` |\n| Localhost / tunnel issues | `qa-use docs localhost-testing` |\n| Test YAML syntax | `qa-use docs test-format` |\n| CI/CD setup | `qa-use docs ci` |\n\n**Key rules:**\n- ALWAYS consult `qa-use docs` before improvising workarounds\n- NEVER fabricate API keys, tokens, URLs, or credentials\n- If `qa-use setup` shows no config, report it \u2014 don't guess\n\n## npx Alternative\n\nAll commands use `qa-use` assuming global install. For one-off use:\n```bash\nnpx @desplega.ai/qa-use browser <command>\n```\n";
 export declare const REFERENCE_DOCS: Record<string, {
     title: string;
     content: string;

package/dist/src/cli/generated/docs-content.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,s6tBA0rBpB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAuoD7E,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiIxE,CAAC"}
+{"version":3,"file":"docs-content.d.ts","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,eAAO,MAAM,QAAQ,2/wBAqtBpB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA8oD7E,CAAC;AAEF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAiIxE,CAAC"}

package/dist/src/cli/generated/docs-content.js

@@ -155,6 +155,9 @@ qa-use test run login
 # Run with autofix (AI self-healing)
 qa-use test run login --autofix
 
+# Run and save the (non-synced) local test to cloud
+qa-use test run login --persist
+
 # Validate syntax
 qa-use test validate login
 
@@ -191,6 +194,23 @@ qa-use test sync push --force
 qa-use test diff login.yaml
 \`\`\`
 
+**Persist vs Sync:**
+
+A local test is **synced** when its YAML has both an \`id:\` and a \`version_hash:\`
+(these are written back by \`test sync push\`/\`pull\`). \`--persist\` on \`test run\`
+and \`qa-use test sync\` are related but not the same:
+
+| Local file state | \`persist\` | What happens at run time |
+|---|---|---|
+| Non-synced | \`false\` (default) | Runs locally; nothing saved to cloud. Re-run with \`--persist\` or use \`test sync push\` to persist. |
+| Non-synced | \`true\` | Test is uploaded as a **new** cloud entry after the run. Re-running like this creates **duplicates** — prefer \`test sync push\` once the file tracks the cloud id. |
+| Synced | \`false\` | Runs against the cloud-tracked definition; no extra write. |
+| Synced | \`true\` | Cloud definition is **upserted** (may overwrite newer cloud edits). Use \`test sync push\`/\`pull\` for explicit version control. |
+
+Rule of thumb: \`test sync push\`/\`pull\` is the deliberate path. Reserve \`--persist\`
+(or \`defaults.persist: true\` in \`.qa-use.json\`) for one-off uploads of brand-new
+local tests.
+
 **No Plugin Shortcut** - Use CLI commands directly
 
 ## Essential Commands
@@ -293,9 +313,16 @@ Use diff output to interact with newly appeared elements directly, without runni
 
 | Command | Description |
 |---------|-------------|
+| \`qa-use api\` | Show help and available subcommands |
 | \`qa-use api ls\` | List available \`/api/v1/*\` routes from OpenAPI |
 | \`qa-use api ls --refresh\` | Force refresh OpenAPI cache |
 | \`qa-use api ls --offline\` | Use cached OpenAPI metadata only |
+| \`qa-use api info /api/v1/<route>\` | Show route details: parameters, request body, responses |
+| \`qa-use api info /api/v1/<route> -X POST\` | Show info for specific HTTP method |
+| \`qa-use api info /api/v1/<route> --json\` | Route info as JSON |
+| \`qa-use api examples\` | Show usage examples |
+| \`qa-use api openapi\` | Print OpenAPI spec URL |
+| \`qa-use api openapi --raw\` | Dump full OpenAPI spec as JSON |
 | \`qa-use api /api/v1/tests\` | Call endpoint (method inferred when possible) |
 | \`qa-use api -X GET /api/v1/test-runs -f limit=5\` | GET with query fields |
 | \`qa-use api -X POST /api/v1/tests-actions/run --input body.json\` | POST with JSON body file |
@@ -1653,8 +1680,15 @@ qa-use test run my-test --autofix --update-local
 
 # 3. Check what changed
 git diff qa-tests/my-test.yaml
+
+# 4. If the test is synced to cloud, push the fix up too
+qa-use test sync push --id <uuid>
 \`\`\`
 
+> \`--update-local\` writes the AI-fixed YAML to the local file only. It does not
+> push to cloud. For synced tests, follow up with \`test sync push\` (or run with
+> \`--persist\`) so the cloud definition matches what you just committed locally.
+
 ### Suggested Actions
 
 - **Update target description** to match current UI

package/dist/src/cli/generated/docs-content.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs-content.js","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"docs-content.js","sourceRoot":"","sources":["../../../../src/cli/generated/docs-content.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/index.js

@@ -5,14 +5,21 @@
 import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { apiCommand } from './commands/api/index.js';
+import { appConfigCommand } from './commands/app-config/index.js';
+import { appContextCommand } from './commands/app-context/index.js';
 import { browserCommand } from './commands/browser/index.js';
+import { dataAssetCommand } from './commands/data-asset/index.js';
 import { docsCommand } from './commands/docs.js';
 import { infoCommand } from './commands/info.js';
 import { installDepsCommand } from './commands/install-deps.js';
+import { issuesCommand } from './commands/issues/index.js';
 import { mcpCommand } from './commands/mcp.js';
+import { personaCommand } from './commands/persona/index.js';
 import { setupCommand } from './commands/setup.js';
+import { suiteCommand } from './commands/suite/index.js';
 import { testCommand } from './commands/test/index.js';
 import { updateCommand } from './commands/update.js';
+import { usageCommand } from './commands/usage.js';
 import { checkForUpdateAsync, getUpdateHintForHelp, shouldSkipCheck, showUpdateHintIfAvailable, } from './lib/update-check.js';
 // Get version from package.json
 const require = createRequire(import.meta.url);
@@ -27,11 +34,18 @@ program.addCommand(setupCommand);
 program.addCommand(infoCommand);
 program.addCommand(docsCommand);
 program.addCommand(testCommand);
+program.addCommand(suiteCommand);
 program.addCommand(mcpCommand);
 program.addCommand(browserCommand);
 program.addCommand(installDepsCommand);
 program.addCommand(updateCommand);
 program.addCommand(apiCommand);
+program.addCommand(appConfigCommand);
+program.addCommand(appContextCommand);
+program.addCommand(personaCommand);
+program.addCommand(dataAssetCommand);
+program.addCommand(issuesCommand);
+program.addCommand(usageCommand);
 // Auto-update hint (reads from cache, fires async fetch — never blocks)
 if (!shouldSkipCheck(process.argv)) {
     showUpdateHintIfAvailable(version);
@@ -53,9 +67,18 @@ program.addHelpText('after', () => {
 Command Groups:
   Setup:     setup, info, install-deps, update
   Testing:   test run, test list, test validate, test init
+  Runs:      test runs list, test runs info, test runs steps
+  Suites:    suite list, suite create, suite run
+  Issues:    issues list, issues info, issues occurrences
   Browser:   browser create, browser goto, browser snapshot, browser click
+  Config:    app-config list, app-config create
+  Context:   app-context list, app-context create
+  Personas:  persona list, persona create
+  Assets:    data-asset list, data-asset upload
+  Usage:     usage, usage --detailed
+  API:       api ls, api info, api examples, api openapi
   Docs:      docs, docs <topic>, docs --list
-  Advanced:  mcp, api
+  Advanced:  mcp
 
 Common Workflows:
   # Verify a feature in the browser
@@ -68,12 +91,31 @@ Common Workflows:
   qa-use test init
   qa-use test run example-test
 
+  # Explore and call API endpoints
+  qa-use api ls
+  qa-use api info /api/v1/tests
+  qa-use api /api/v1/tests -f limit=5
+
   # Record a flow and generate a test
   qa-use browser create
   qa-use browser goto https://your-app.com
   qa-use browser click <ref>
   qa-use browser generate-test my-test
 
+  # Manage test suites
+  qa-use suite create -F name="Smoke Tests"
+  qa-use suite list
+  qa-use suite run <suite-id>
+
+  # Review test run results
+  qa-use test runs list --limit 5
+  qa-use test runs info <run-id>
+  qa-use test runs steps <run-id>
+
+  # Check issues and usage
+  qa-use issues list --limit 10
+  qa-use usage --detailed
+
   # Get help on writing tests
   qa-use docs test-format
 ${updateHint}`;

package/dist/src/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;GAEG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAChE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,yBAAyB,GAC1B,MAAM,uBAAuB,CAAC;AAE/B,gCAAgC;AAChC,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAElD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,QAAQ,CAAC;KACd,WAAW,CAAC,uDAAuD,CAAC;KACpE,OAAO,CAAC,OAAO,CAAC,CAAC;AAEpB,oBAAoB;AACpB,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AACjC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAChC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAC/B,OAAO,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;AACnC,OAAO,CAAC,UAAU,CAAC,kBAAkB,CAAC,CAAC;AACvC,OAAO,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC;AAClC,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;AAE/B,wEAAwE;AACxE,IAAI,CAAC,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;IACnC,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACnC,mBAAmB,EAAE,CAAC;AACxB,CAAC;AAED,iDAAiD;AACjD,OAAO,CAAC,WAAW,CACjB,QAAQ,EACR;;;;;;;CAOD,CACA,CAAC;AAEF,iEAAiE;AACjE,OAAO,CAAC,WAAW,CAAC,OAAO,EAAE,GAAG,EAAE;IAChC,MAAM,UAAU,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACjD,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;EA2BP,UAAU,EAAE,CAAC;AACf,CAAC,CAAC,CAAC;AAEH,+BAA+B;AAC/B,OAAO,CAAC,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/cli/index.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/lib/api-helpers.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Shared API request helpers for CLI commands.
+ *
+ * Config-aware wrapper around executeApiRequest (from api/lib/http.ts)
+ * so individual CLI commands don't repeat boilerplate.
+ */
+import type { CliConfig } from './config.js';
+/**
+ * Validates that the config contains an API key.
+ * Exits the process with a helpful message when missing.
+ */
+export declare function requireApiKey(config: CliConfig): asserts config is CliConfig & {
+    api_key: string;
+};
+export interface ApiCallOptions {
+    query?: Record<string, string>;
+    body?: unknown;
+    headers?: Record<string, string>;
+}
+/**
+ * Makes an authenticated API request using the CLI config.
+ * Throws on HTTP errors (status >= 400) with a human-readable message.
+ */
+export declare function apiCall(config: CliConfig, method: string, path: string, options?: ApiCallOptions): Promise<unknown>;
+/**
+ * Builds pagination query params from common CLI options.
+ * Only includes keys whose values are defined.
+ */
+export declare function paginationQuery(options: {
+    limit?: string;
+    offset?: string;
+}): Record<string, string>;
+/**
+ * Collector for Commander's repeatable `-F`/`--field` option.
+ *
+ * Usage with Commander:
+ * ```
+ * .option('-F, --field <key=value>', 'Set field', collectFields, [])
+ * ```
+ */
+export declare function collectFields(value: string, previous: string[]): string[];
+/**
+ * Reads body from `--input` file and/or `-F` fields and merges them.
+ * Values that parse as valid JSON are treated as JSON
+ * (e.g. `-F test_ids='["id1","id2"]'`).
+ *
+ * Stdin (piped) is intentionally **not** read here — that would complicate
+ * interactive commands. Add it later if needed.
+ */
+export declare function parseResourceInput(options: {
+    input?: string;
+    field?: string[];
+}): Promise<Record<string, unknown>>;
+/**
+ * Confirmation prompt for destructive operations.
+ * Returns `true` when the user types y/yes (case-insensitive).
+ */
+export declare function confirmAction(message: string): Promise<boolean>;
+//# sourceMappingURL=api-helpers.d.ts.map

package/dist/src/cli/lib/api-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-helpers.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/api-helpers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,MAAM,IAAI,SAAS,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAMnD;AAMD,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAC3B,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAKzB;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGzE;AAMD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA4CnC;AAMD;;;GAGG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAYrE"}

package/dist/src/cli/lib/api-helpers.js

@@ -0,0 +1,149 @@
+/**
+ * Shared API request helpers for CLI commands.
+ *
+ * Config-aware wrapper around executeApiRequest (from api/lib/http.ts)
+ * so individual CLI commands don't repeat boilerplate.
+ */
+import * as fs from 'node:fs/promises';
+import * as readline from 'node:readline/promises';
+import { executeApiRequest, formatApiResponseError } from '../commands/api/lib/http.js';
+// ---------------------------------------------------------------------------
+// requireApiKey
+// ---------------------------------------------------------------------------
+/**
+ * Validates that the config contains an API key.
+ * Exits the process with a helpful message when missing.
+ */
+export function requireApiKey(config) {
+    if (!config.api_key) {
+        console.log('\x1b[31m✗\x1b[0m API key not configured');
+        console.log('  Run `qa-use setup` to configure');
+        process.exit(1);
+    }
+}
+/**
+ * Makes an authenticated API request using the CLI config.
+ * Throws on HTTP errors (status >= 400) with a human-readable message.
+ */
+export async function apiCall(config, method, path, options = {}) {
+    requireApiKey(config);
+    const apiUrl = config.api_url || 'https://api.desplega.ai';
+    const response = await executeApiRequest({
+        apiUrl,
+        apiKey: config.api_key,
+        method,
+        path,
+        headers: { ...config.headers, ...options.headers },
+        query: options.query,
+        body: options.body,
+    });
+    if (response.status >= 400) {
+        throw new Error(formatApiResponseError(response.status, response.statusText, response.data));
+    }
+    return response.data;
+}
+// ---------------------------------------------------------------------------
+// paginationQuery
+// ---------------------------------------------------------------------------
+/**
+ * Builds pagination query params from common CLI options.
+ * Only includes keys whose values are defined.
+ */
+export function paginationQuery(options) {
+    const query = {};
+    if (options.limit !== undefined)
+        query.limit = options.limit;
+    if (options.offset !== undefined)
+        query.offset = options.offset;
+    return query;
+}
+// ---------------------------------------------------------------------------
+// collectFields
+// ---------------------------------------------------------------------------
+/**
+ * Collector for Commander's repeatable `-F`/`--field` option.
+ *
+ * Usage with Commander:
+ * ```
+ * .option('-F, --field <key=value>', 'Set field', collectFields, [])
+ * ```
+ */
+export function collectFields(value, previous) {
+    previous.push(value);
+    return previous;
+}
+// ---------------------------------------------------------------------------
+// parseResourceInput
+// ---------------------------------------------------------------------------
+/**
+ * Reads body from `--input` file and/or `-F` fields and merges them.
+ * Values that parse as valid JSON are treated as JSON
+ * (e.g. `-F test_ids='["id1","id2"]'`).
+ *
+ * Stdin (piped) is intentionally **not** read here — that would complicate
+ * interactive commands. Add it later if needed.
+ */
+export async function parseResourceInput(options) {
+    let base = {};
+    // 1. --input file
+    if (options.input) {
+        const raw = await fs.readFile(options.input, 'utf-8');
+        try {
+            const parsed = JSON.parse(raw);
+            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                base = parsed;
+            }
+            else {
+                throw new Error(`Input file must contain a JSON object, got ${typeof parsed}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof SyntaxError) {
+                throw new Error(`Failed to parse JSON input file: ${options.input}`);
+            }
+            throw err;
+        }
+    }
+    // 2. -F fields (override --input values)
+    if (options.field) {
+        for (const entry of options.field) {
+            const idx = entry.indexOf('=');
+            if (idx <= 0) {
+                throw new Error(`Invalid field \`${entry}\`. Expected format key=value`);
+            }
+            const key = entry.slice(0, idx).trim();
+            const rawValue = entry.slice(idx + 1).trim();
+            // Try to parse as JSON (arrays, objects, numbers, booleans)
+            let value = rawValue;
+            try {
+                value = JSON.parse(rawValue);
+            }
+            catch {
+                // Not valid JSON — keep as string
+            }
+            base[key] = value;
+        }
+    }
+    return base;
+}
+// ---------------------------------------------------------------------------
+// confirmAction
+// ---------------------------------------------------------------------------
+/**
+ * Confirmation prompt for destructive operations.
+ * Returns `true` when the user types y/yes (case-insensitive).
+ */
+export async function confirmAction(message) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stderr,
+    });
+    try {
+        const answer = await rl.question(`${message} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+//# sourceMappingURL=api-helpers.js.map

package/dist/src/cli/lib/api-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-helpers.js","sourceRoot":"","sources":["../../../../src/cli/lib/api-helpers.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/lib/config.d.ts

@@ -1,12 +1,15 @@
 /**
  * Configuration file management for .qa-use.json
  */
+import { BrowserApiClient } from '../../../lib/api/browser.js';
+import { ApiClient } from '../../../lib/api/index.js';
 export interface CliConfig {
     env?: Record<string, string>;
     api_key?: string;
     api_url?: string;
     default_app_config_id?: string;
     test_directory?: string;
+    headers?: Record<string, string>;
     defaults?: {
         headless?: boolean;
         persist?: boolean;
@@ -37,4 +40,12 @@ export declare function saveConfig(config: CliConfig): Promise<void>;
  * Check if config file exists
  */
 export declare function configExists(): Promise<boolean>;
+/**
+ * Create a BrowserApiClient pre-configured with API key and custom headers from config.
+ */
+export declare function createBrowserClient(config: CliConfig): BrowserApiClient;
+/**
+ * Create an ApiClient pre-configured with API key and custom headers from config.
+ */
+export declare function createApiClient(config: CliConfig): ApiClient;
 //# sourceMappingURL=config.d.ts.map

package/dist/src/cli/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAqCD;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAU7D;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CA+CrD;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjE;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAErD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../src/cli/lib/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAEtD,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,QAAQ,CAAC,EAAE;QACT,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,OAAO,CAAC;KACrB,CAAC;CACH;AAqCD;;;GAGG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAU7D;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAsErD;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAIjE;AAED;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAErD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,gBAAgB,CAKvE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAK5D"}

package/dist/src/cli/lib/config.js

@@ -4,6 +4,8 @@
 import * as fs from 'node:fs/promises';
 import { homedir } from 'node:os';
 import * as path from 'node:path';
+import { BrowserApiClient } from '../../../lib/api/browser.js';
+import { ApiClient } from '../../../lib/api/index.js';
 const CONFIG_FILENAME = '.qa-use.json';
 const LEGACY_CONFIG_FILENAME = '.qa-use-tests.json';
 const legacyWarningShown = new Set();
@@ -97,6 +99,26 @@ export async function loadConfig() {
     if (process.env.QA_USE_DEFAULT_APP_CONFIG_ID) {
         config.default_app_config_id = process.env.QA_USE_DEFAULT_APP_CONFIG_ID;
     }
+    // Resolve custom headers: config file headers + QA_USE_HEADERS env var (env wins)
+    const resolvedHeaders = {};
+    if (config.headers) {
+        Object.assign(resolvedHeaders, config.headers);
+    }
+    const envHeaders = process.env.QA_USE_HEADERS;
+    if (envHeaders) {
+        try {
+            const parsed = JSON.parse(envHeaders);
+            if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                Object.assign(resolvedHeaders, parsed);
+            }
+        }
+        catch {
+            console.error('Warning: QA_USE_HEADERS is not valid JSON, ignoring');
+        }
+    }
+    if (Object.keys(resolvedHeaders).length > 0) {
+        config.headers = resolvedHeaders;
+    }
     return config;
 }
 /**
@@ -113,4 +135,26 @@ export async function saveConfig(config) {
 export async function configExists() {
     return (await findConfigFile()) !== null;
 }
+/**
+ * Create a BrowserApiClient pre-configured with API key and custom headers from config.
+ */
+export function createBrowserClient(config) {
+    const client = new BrowserApiClient(config.api_url);
+    if (config.api_key)
+        client.setApiKey(config.api_key);
+    if (config.headers)
+        client.setCustomHeaders(config.headers);
+    return client;
+}
+/**
+ * Create an ApiClient pre-configured with API key and custom headers from config.
+ */
+export function createApiClient(config) {
+    const client = new ApiClient(config.api_url);
+    if (config.api_key)
+        client.setApiKey(config.api_key);
+    if (config.headers)
+        client.setCustomHeaders(config.headers);
+    return client;
+}
 //# sourceMappingURL=config.js.map