Command-line scan experience
Strix gives an engineer one command-line path from scan request to security results. The path accepts targets and scan guidance, prepares a safe run workspace, starts the scan in a terminal or headless mode, and keeps the run available for later viewing or resume.
Command-line entrypoints
The main strix command starts a scan. It also exposes separate paths for account sign-in, managed-platform actions, shell completion, and opening a local view of a saved run, so those actions do not require scan targets or scan setup.
| Entry point | User goal | Result |
|---|---|---|
strix | Start a fresh scan | Parses the request and starts the selected terminal experience. |
strix --resume RUN_NAME | Continue a prior scan | Restores the saved run context and continues from its saved agent state. |
strix view [RUN_NAME] | Inspect a live or finished run | Serves the run's local web view and prints an authorized link. |
strix auth ... | Manage model-subscription sign-in | Handles sign-in without Docker or scan preparation. |
strix cloud ... | Use the managed Strix platform | Runs a managed-platform action without local scan setup. |
strix completion[s] SHELL | Set up shell completion | Generates completion commands for the selected shell and exits. |
The scan command uses interactive mode by default. --non-interactive selects a headless run that prints progress and exits when the scan ends. The detailed launch and setup contract is described in CLI launch and scan setup.
Invocation routing
The command first handles help and separates viewer, authentication, completion, and managed-platform requests from scan requests. These paths exit without Docker checks or scan setup. A scan request then parses its options, checks the local run environment, and chooses either the terminal user interface or the plain command-line presenter.
This diagram shows how a command becomes either a separate command action or a running scan.
flowchart TD
A[User invokes strix] --> B{Help or subcommand}
B -->|help| C[Show command help]
B -->|view| D[Serve a saved run view]
B -->|auth| E[Manage model sign-in]
B -->|completion[s]| F[Generate shell completions]
B -->|cloud| G[Use managed platform]
B -->|scan options| H[Parse scan options]
H --> I{Interactive?}
I -->|yes| J[Offer update and open terminal user interface]
I -->|no| K[Warm up model and prepare headless scan]
J --> L[Run scan and present live state]
K --> M[Run scan and print progress]
L --> N[Save result and show follow-up commands]
M --> N
The command checks Docker and the sandbox image before a scan starts. A headless scan then checks the model connection and prepares the run before it begins. An interactive launch reaches the terminal interface early, then performs model checks and scan preparation there so the user sees the interface while startup work runs. An interactive launch can also stop before setup when the user accepts an available update.
References: strix/…/main.py• L421-480 strix/…/main.py• L482-505 strix/…/cli_args.py• L104-117 strix/…/interactive.py• L16-32 strix/…/cli.py• L31-75
Scan request and setup
Scan setup turns command-line input into one shared scan description. This description records the targets, user guidance, scan depth, code scope, run limits, and files that the scan may use. Both direct command-line launches and interactive setup use the same preparation rules.
Target forms
Strix accepts targets that describe a live system, source code, or an API contract. It classifies each value before the scan so the agent receives the right kind of access and scope.
| Target form | Scan meaning |
|---|---|
| URL or domain | Test a web application. |
| IP address | Test a network endpoint. |
| Git repository | Fetch source code for analysis and testing. |
| Local directory | Use a local source tree for source-aware testing. |
| OpenAPI, Swagger, or Postman file | Test an API described by the file. |
postman://... reference | Fetch a Postman collection on the host and stage it for the scan. |
Users can repeat --target or combine it with --target-list. Multiple targets support related views of one system, such as a source repository plus its deployed application. Invalid targets and unreadable target lists stop setup before the scan starts.
References: strix/…/cli_args.py• L119-138 strix/…/utils.py• L1132-1225 strix/…/utils.py• L1228-1251
Scan configuration
The request can add instructions and control how much work the scan performs. These choices shape the scan without changing the target authorization that comes from the target list.
| Setting | User-facing choices or purpose |
|---|---|
| Instructions | Inline text or a file with focus areas, test guidance, or credentials. |
| Scan mode | quick, standard, or deep; deep is the default. |
| Code scope | auto, diff, or full; scope can focus a code review on changed files. |
| Diff base | Branch or commit used to define changed-file scope. |
| Run limits | A positive LLM budget and a positive per-agent turn limit. |
| Workspace files | Read-only host files placed in the scan workspace, such as an API spec or wordlist. |
| MCP connections | An optional named set of model context protocol connections to include or exclude for the run. |
The setup flow validates these values, resolves target types, clones repository targets when needed, stages API specifications, and collects local source trees. In CI or headless pull-request use, automatic diff scope can narrow source analysis to the changed files. A workspace mount is different: it gives the agent a place to work, but it is not itself an authorized scan target. Run budgets and turn limits must be finite positive values, which prevents an invalid limit from reaching scan execution.
References: strix/…/cli_args.py• L139-269 strix/…/scan_setup.py• L100-199 strix/…/scan_setup.py• L202-220 strix/…/utils.py• L1312-1337 strix/…/utils.py• L1515-1551 strix/…/utils.py• L1739-1785
Run preparation and persistence
Preparation gives the scan a run name and records enough context to show progress, produce results, and resume later. The saved record includes the target description, user instruction, scope choice, scan mode, workspace inputs, and run status.
This diagram shows how command input becomes a saved run before scan work starts.
flowchart LR
A[Targets and options] --> B[Classify and validate]
B --> C[Resolve sources and API files]
C --> D[Apply code scope]
D --> E[Attach workspace inputs]
E --> F[Persist run record]
F --> G[Start scan]
A resume request uses the prior run name and saved record instead of creating a new run. It restores the original targets and instruction, rechecks that required local paths still exist, and reuses saved workspace files when the user does not provide replacements. A target-less interactive run can also resume from its saved instruction and confirmed workspace mount.
References: strix/…/scan_setup.py• L164-199 strix/…/scan_setup.py• L239-268 strix/…/cli_args.py• L332-458
Terminal scan presentation
Strix presents a running scan as a live conversation with scan state beside it. The terminal experience lets the user watch agent work, inspect findings, send guidance, stop active agents, and open the browser view without leaving the scan.
Terminal modes
Interactive and headless modes serve different operating needs. Interactive mode is for a person who may guide the scan. Headless mode is for automation that needs stable completion behavior and an exit result.
| Mode | Presentation | User control |
|---|---|---|
| Interactive | A full-screen terminal interface with setup, agent activity, events, findings, and a message composer. | Add setup input, send agent messages, stop work, open the viewer, or quit. |
| Headless | Rich terminal panels with startup, live status, findings, and a final summary. | Control comes from the original command and process signals. |
The interactive interface uses a separate terminal process connected to the Python scan service through a private, versioned message channel. The two sides agree on the channel before the terminal enters full-screen mode. This keeps scan control and scan work in the service while the terminal focuses on presentation.
References: strix/…/cli.py• L41-106 strix/…/cli.py• L143-208 strix/…/runtime.py• L347-405 strix/…/main.go• L12-32 strix/…/protocol.py• L8-20
Interactive setup
An interactive launch without a target opens the setup screen instead of failing. The user can type a target, describe the work, or use a bare prompt; target-like words become targets and the remaining text becomes scan guidance.
When the prompt has no target, Strix asks whether it may mount the current working directory for the agent. Approval gives the agent that workspace without adding it to scan scope. Declining still starts the prompt-driven run without the mount. A named target receives a model connection check before setup completes, while a bare prompt starts optimistically and reports a model error when the agent begins if the connection fails. Once the scan starts, setup fields become fixed and the composer sends guidance to the selected agent.
The setup and scan screens are described in more detail in terminal user interfaces.
References: strix/…/cli_args.py• L283-365 strix/…/setup.go• L29-74 strix/…/runtime.py• L107-148 strix/…/controller.py• L264-357 strix/…/model.go• L173-220
Live scan state
The terminal receives a bounded state view and collections for agents, events, and vulnerabilities. It uses those updates to show the selected agent's conversation, the agent tree, current findings, model usage, and scan state without loading the full history into one message.
The user can move through agents and findings, expand tool activity, scroll the trace, copy report text, and send a message to an active agent. The interface also shows clear states for preparation, running, stopped, completed, and failed scans. Agent state and report state are synchronized during the run, so an agent failure or an incomplete report can change the displayed scan state.
References: strix/…/runtime.py• L170-312 strix/…/controller.py• L156-249 strix/…/view.go• L36-123 strix/…/update.go• L11-137 strix/…/server.py• L54-92
Results and continuation
The end of a scan gives the user both a local run location and the next way to inspect or continue the work. The command-line summary reports completion status, target information, findings, usage, and the run path.
Completion paths
A completed run can be opened with strix view RUN_NAME, or with strix view to select the latest saved run. The viewer prints a token-bearing local link because the link can browse history and, for a live run, steer agents.
An interrupted or stopped run remains a saved run. The completion message shows strix --resume RUN_NAME so the user can continue when the required saved state and local inputs are available. In headless mode, detected vulnerability reports produce a non-zero exit status for automation. Model failures show a direct connection message and can include a provider-package or subscription sign-in hint. An interactive completion panel also offers the view command and shows the run output path.
References: strix/…/main.py• L260-343 strix/…/main.py• L364-395 strix/…/main.py• L397-419 strix/…/main.py• L500-533 strix/…/cli.py• L69-107 strix/…/cli_args.py• L375-458
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the
strixdispatch order aligned with the parser rules. Viewer, authentication, completion, and cloud commands must remain usable without targets. An accepted interactive update must still exit before scan setup. - Keep the fields built by
prepare_runaligned with the fields restored by--resume; a missing field can silently change the next run's scope or workspace. - Keep target classification, API-spec staging, local-source collection, and workspace-file validation consistent. Each stage changes what the agent can see.
- Keep the Python TUI protocol version and capability list aligned with the Go client before changing state or command messages.
- Keep interactive and headless scan limits and scope settings aligned so the same request does not receive different scan boundaries by mode.
- Keep target-less setup behavior aligned across argument parsing, setup controls, workspace mounting, and resume state.
- Keep completion status and headless exit behavior aligned with report state so automation can distinguish a clean run from a run with findings or failure.
- Keep model preflight and provider guidance aligned with the selected mode. Headless startup must fail before scan work when the model is unavailable, while interactive startup must show the error in the terminal experience.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
A fresh headless command has no --target or --target-list | Argument parsing stops before a scan is prepared. | Use a target, a target list, or --resume RUN_NAME. |
| A target, API spec, target list, or workspace file is invalid | Setup reports an input error and no scan starts. | Validate the input and use the accepted target and file forms. |
| A budget or turn limit is zero, negative, infinite, or not numeric | Argument parsing stops before the scan starts. | Use finite positive values. |
| The model route cannot answer its startup check | Headless mode exits with a model connection error; interactive setup shows a preparation error. | Fix model configuration or provider access before retrying. |
| A model provider package is missing or a ChatGPT subscription cannot use the selected model | The scan does not start and Strix prints a provider or sign-in hint when it can identify one. | Install the matching optional extra or sign in with a supported model. |
| Docker or the configured sandbox image is unavailable | The scan cannot start. | Install or start Docker and provide the configured image. |
| The TUI binary or its protocol handshake is unavailable | Interactive setup cannot activate. | Use a supported Strix installation and keep the Python and Go TUI versions matched. |
| A resume record lacks required state or a saved local path is gone | Resume is rejected rather than silently starting with incomplete context. | Restore the path or start a fresh run. |
| The process receives an interrupt | The run is cleaned up and marked interrupted or stopped; partial output remains available. | Resume the saved run when the task should continue. |
| The headless run has vulnerability reports | The command exits with status 2 after it saves and presents the result. | Treat the exit status as a scan result in automation. |
Key files
| File | Why to read it |
|---|---|
| strix/…/main.py | Shows the top-level routing, help and update paths, environment checks, model errors, mode choice, cleanup, completion message, and exit behavior. |
| strix/…/cli_args.py | Defines the command-line contract and the rules for fresh runs, target-less setup, and resume. |
| strix/…/scan_setup.py | Shows the shared boundary where user input becomes a prepared and persisted scan. |
| strix/…/utils.py | Explains target classification, source collection, API-spec staging, diff scope, and workspace-file validation. |
| strix/…/cli.py | Shows the headless terminal journey from startup panel to live status and final summary. |
| strix/…/runtime.py | Connects interactive setup, model checks, scan execution, live state, and terminal process supervision. |
| strix/…/controller.py | Defines the user actions available during setup and during a live scan. |
| strix/…/protocol.py | Defines the shared contract between the Python scan service and the Go terminal client. |
| strix/…/setup.go | Shows how the interactive prompt becomes targets, instructions, and a scan start request. |
| strix/…/view.go | Shows how agent events and scan states become terminal content. |
| strix/…/cli.py | Shows the separate command-line path for opening live or finished runs in the local web viewer. |