strix/docs/usage/cli.mdx

---
title: "CLI Reference"
description: "Command-line options for Strix"
---

## Basic Usage

```bash
strix (--target <target> | --target-list <path>) [options]
```

## Options

<ParamField path="--target, -t" type="string">
  Target to test. Accepts URLs, repositories, local directories, domains, IP addresses, API spec files (OpenAPI/Swagger `.json`/`.yaml`, a Postman collection export), or a live Postman collection by id (`postman://<collection-uuid>`). Can be specified multiple times. Fresh runs require at least one target source: `--target` or `--target-list`.

  When the target is an API spec, Strix copies it into the agent's workspace and authorizes the base URLs it declares (including those resolved from a Postman environment) as in-scope hosts - so the agent reads the contract and tests the full declared surface instead of discovering endpoints by crawling. Pair the spec with the deployed base URL (e.g. `--target ./openapi.yaml --target https://api.example.com`) so the agent has a reachable host to attack.

  <Note>
    A local directory is mounted into the sandbox live and **writable**, so the agent edits your real files (`.git` excepted). Commit or stash first.
  </Note>

  <Note>
    Fetching a Postman collection by id requires `POSTMAN_API_KEY`. Add `?env=<environment-uuid>` to also pull a Postman environment, which resolves `{{baseUrl}}` / token variables the collection references (e.g. `postman://<collection-uuid>?env=<environment-uid>`).
  </Note>
</ParamField>

<ParamField path="--target-list" type="string">
  Path to a file containing targets, one per non-empty, non-comment line. Lines starting with `#` are ignored. Can be specified multiple times and combined with `--target`.
</ParamField>

<ParamField path="--instruction" type="string">
  Custom instructions for the scan. Use for credentials, focus areas, or specific testing approaches.
</ParamField>

<ParamField path="--instruction-file" type="string">
  Path to a file containing detailed instructions.
</ParamField>

<ParamField path="--workspace-file" type="string">
  Path to a file on your machine to place into the sandbox workspace before the
  scan starts. Repeat the option for more files. Write `PATH:DEST` to choose the
  destination inside `/workspace`. `DEST` defaults to the file name. See
  [Workspace files](/usage/instructions#workspace-files).
</ParamField>

<ParamField path="--scan-mode, -m" type="string" default="deep">
  Scan depth: `quick`, `standard`, or `deep`.
</ParamField>

<ParamField path="--scope-mode" type="string" default="auto">
  Code scope mode: `auto` (enable PR diff-scope in CI/headless runs), `diff` (force changed-files scope), or `full` (disable diff-scope).
</ParamField>

<ParamField path="--diff-base" type="string">
  Target branch or commit to compare against (e.g., `origin/main`). Defaults to the repository's default branch.
</ParamField>

<ParamField path="--non-interactive, -n" type="boolean">
  Run in headless mode without TUI. Ideal for CI/CD.
</ParamField>

<ParamField path="--config" type="string">
  Path to a custom config file (JSON) to use instead of `~/.strix/cli-config.json`.
</ParamField>

<ParamField path="--max-budget" type="number">
  Maximum LLM spend in USD for the whole scan, counted cumulatively across the
  root agent and every child agent. The budget is checked after each model
  response.

  In non-interactive mode (`-n`), once the running cost reaches the threshold,
  the scan stops cleanly with a `stopped` status (not a failure) and the sandbox
  is torn down. Sub-agents are stopped early, at 90% of the budget, reserving
  the final slice for the root agent to wind down and produce the final report.

  In interactive mode, reaching the budget pauses the scan instead of ending
  it: every agent parks, and sending any message resumes the scan with the cap
  extended by the original budget amount. There is no sub-agent reserve in
  interactive mode.

  As the budget is approached, graduated wrap-up warnings are surfaced to
  **every** agent so they can finish their work and call their lifecycle tool
  before the hard stop. The bands sit just below each role's own stop point: the
  root is warned at **70%, 85% and 95%** (it stops at 100%), while sub-agents are
  warned at **75%, 80% and 85%** (they stop at the 90% reserve). In interactive
  mode every agent uses the **70%, 85% and 95%** bands. Percentages shown in the
  warnings are the real cumulative spend against the full budget.

  Must be greater than `0`. Omit the flag for no limit.

  **Limitations**

  - The check fires *after* a response is returned, so the final spend can
    slightly overshoot the limit by any calls already in flight when the
    threshold is crossed (most relevant with several child agents running
    concurrently).
  - Cost is a best-effort estimate derived from token usage and model pricing;
    providers that do not expose priced usage may under-count.
  - For LiteLLM-routed models, Strix enables streaming success callbacks to
    capture provider-reported cost. Message content remains excluded, but
    third-party LiteLLM callbacks configured in the same process can receive
    other streaming metadata such as model names, request IDs, and token
    counts.
</ParamField>

<ParamField path="--max-turns" type="integer" default="500">
  Maximum number of turns (one model response plus its tool round) allotted to
  **each** agent, applied per run. When an agent reaches this limit it is
  force-stopped.

  As the limit is approached, graduated wrap-up warnings (at 70%, 85% and 95%)
  are injected into that agent's next model turn so it can prioritise its
  remaining work and call its lifecycle tool (`finish_scan` for the root agent,
  `agent_finish` for sub-agents) before the hard stop.

  Must be greater than `0`.
</ParamField>

## Examples

```bash
# Basic scan
strix --target https://example.com

# Authenticated testing
strix --target https://app.com --instruction "Use credentials: user:pass"

# Focused testing
strix --target api.example.com --instruction "Focus on IDOR and auth bypass"

# CI/CD mode
strix -n --target ./ --scan-mode quick

# Cap cost and per-agent turns
strix --target https://example.com --max-budget 25 --max-turns 300

# Force diff-scope against a specific base ref
strix -n --target ./ --scan-mode quick --scope-mode diff --diff-base origin/main

# Multi-target white-box testing
strix -t https://github.com/org/app -t https://staging.example.com

# API spec + live target (OpenAPI/Swagger file or Postman collection)
strix -t ./openapi.yaml -t https://api.example.com

# Postman collection pulled live by id (+ optional environment)
strix -t "postman://<collection-uuid>?env=<environment-uuid>"

# Targets from a file
strix --target-list ./targets.txt

# Extra files placed in the sandbox workspace
strix --target ./my-project --workspace-file ./wordlist.txt
strix --target https://app.com --workspace-file ./openapi.yaml:specs/openapi.yaml
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Scan completed successfully (interactive mode always exits `0`; in headless mode, `0` means no vulnerabilities were found) |
| 1 | A fatal error occurred before or during the scan (e.g. missing environment variables, Docker unavailable, invalid config file, diff-scope resolution failure, or an unhandled error) |
| 2 | Vulnerabilities found (headless mode only) |