Skip to main content

​
Basic usage

With a config file ready and the CLI authenticated, start a run: 
npx qaos run --config ./qaos-config.json
The CLI connects to the QAOS server, launches a headless browser, and begins executing tasks. Progress is streamed to your terminal in real time.

​
Command options

npx qaos run [options]
OptionAliasDescriptionDefault
--config <path>-cPath to the config JSON file./qaos-config.json
--headed-hRun with a visible browser windowHeadless

​
Default config lookup

If no --config flag is given, QAOS looks for qaos-config.json in the current working directory: 
npx qaos run  # uses ./qaos-config.json

​
Headed mode

Use --headed (or -h) to open a visible browser window during the run. This is useful for:
  • Debugging task descriptions that aren’t producing expected behavior
  • Watching the agent navigate your application
  • Understanding how the agent interprets your pages
npx qaos run --config ./qaos-config.json --headed
Headed mode may be slightly slower than headless mode. Use headless for production CI pipelines.

​
What happens during a run

1

Connection

The CLI connects to the QAOS server over WebSocket and sends your config to initiate the run. A run ID is assigned and printed.
2

Task execution

Tasks execute sequentially. For each task:
  • The browser navigates to startUrl
  • The agent analyzes the page (DOM, screenshots, network headers, cookies, console logs)
  • Subtasks are generated for interactive tests (e.g., attempting login with weak passwords)
  • Issues are detected and reported in real time
3

Agent evaluation

At each page, the selected subagents evaluate the page against their full issue catalog — using a combination of deterministic checks (fast, code-based) and LLM evaluation (deeper, context-aware).
4

Completion

Once all tasks finish, the CLI prints a summary of detected issues and a link to the full report in the dashboard.

​
Real-time output

While the run is in progress, the CLI displays a live feed: 
✓ Connected · run_abc123
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Task 1/3 · Login page [security, quality]
  → Navigating to https://app.example.com/login
  → Analyzing page structure...
  → Running deterministic checks...
  → Running LLM evaluation...
  ✗ [HIGH]     misconfigured-security-headers
  ✗ [MEDIUM]   missing-form-labels · 1 issue

Task 2/3 · Dashboard [security, quality]
  → Navigating to https://app.example.com/dashboard
  → Testing access control...
  ✓ No issues detected

Task 3/3 · Admin panel [security]
  → Navigating to https://app.example.com/admin
  → Testing privilege escalation...
  ✗ [CRITICAL] unauthenticated-resource-access

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Run complete · 3 issues found (1 critical, 1 high, 1 medium)
Report: https://qaos.machdel.com/reports/run_abc123

​
Running in CI/CD

QAOS works well in CI pipelines. Use API token authentication and a pre-committed config file:
GitHub Actions example
- name: Run QAOS security audit
  run: |
    npx npx qaos auth --api ${{ secrets.QAOS_API_TOKEN }}
    npx npx qaos run --config ./qaos-config.json
  env:
    QAOS_API_TOKEN: ${{ secrets.QAOS_API_TOKEN }}
The CLI exits with code 0 on success and a non-zero code if the run fails or the server is unreachable.

​
Troubleshooting

Your token may have expired or been revoked. Re-authenticate:
npx qaos auth --api <your-token>
# or
npx qaos auth --ui
Check the path you provided:
ls ./qaos-config.json      # verify it exists
npx qaos run --config ./path/to/config.json
QAOS uses Playwright internally. If the browser fails to start, install the required browser binaries:
npx playwright install chromium
If your application loads slowly, consider adding descriptive context in your task config to help the agent understand the expected behavior. Each task has a generous timeout, but very slow pages may occasionally be skipped.