CLI launch and scan setup
The CLI launch path turns a user command into a validated scan context. It selects the command surface, loads settings, checks the local runtime and model access, resolves targets, and assembles the sources and instructions that the scan engine receives. The broader command journey is described in Command-line scan experience, while the interactive screens and viewer are described in Interactive terminal and viewer interfaces.
Launch routing
The launch router separates scan setup from commands that do not run a scan. Help, viewer, authentication, shell-completion, and managed-cloud commands exit through their own paths before target validation or scan setup. Scan commands warm imports, parse their arguments, start an update check, and then prepare the runtime.
The main scan path follows different timing for interactive and non-interactive use:
flowchart TD
A["strix command"] --> B{"Command type"}
B -->|help| C["Show CLI and subcommand help"]
B -->|view| D["Select run and start local viewer"]
B -->|auth| E["Sign in, show status, or sign out"]
B -->|completion| F["Generate shell completion"]
B -->|cloud| G["Use managed Strix platform"]
B -->|scan| H["Warm imports and parse flags"]
H --> I["Start cached update check"]
I --> J{"Interactive?"}
J -->|Yes| K["Offer update, then check Docker"]
J -->|No| L["Check Docker and prepare sandbox image"]
K --> M{"Target supplied?"}
M -->|No| N["Open setup interface"]
M -->|Yes| O["Open setup interface after environment check"]
L --> P["Validate environment and model route"]
P --> Q["Prepare run and start telemetry"]
N --> R["Collect scan inputs"]
O --> R
R --> S["Prepare run, check model route, and start telemetry"]
Q --> T["Pass scan configuration to execution"]
S --> T
Interactive launch can open a setup screen without a target. The user can then provide a target or a bare instruction before model preflight and run preparation start. A non-interactive launch must have a target or target list unless it resumes an earlier run. References: strix/…/main.py• L391-475, strix/…/cli_args.py• L283-372, strix/…/interactive.py• L20-33
Command parsing
The parser creates one shared argument model for the CLI and the terminal setup flow. It carries target inputs, scan behavior, instructions, resource limits, scope choices, resume state, and prepared values so both interfaces hand the same kind of context to the scan engine.
Scan options
The parser accepts repeated --target and --target-list inputs. A target list contains one target per non-empty, non-comment line, and its entries combine with command-line targets. Instructions can come inline or from one file. Workspace files can also be named for placement in the sandbox before the scan begins. References: strix/…/cli_args.py• L53-167, strix/…/utils.py• L1228-1251, strix/…/utils.py• L1739-1772
Scan mode, scope mode, diff base, budget, turn limits, and MCP connection selection shape the later preparation and execution policy. The parser rejects values outside the supported modes and rejects conflicting instruction sources before any scan work starts. References: strix/…/cli_args.py• L169-281
Configuration precedence
Settings come from the selected JSON config file, environment variables, and field defaults. Environment values take precedence over the file. --config changes the JSON source for the current process, while MCP flags set per-run connection filters for the later MCP loader. References: strix/…/loader.py• L24-125, strix/…/cli_args.py• L292-307, strix/…/settings.py• L22-26
The settings model groups launch policy into model access, dedupe, sandbox runtime, context limits, telemetry, external integrations, and viewer behavior. The model group selects the Responses or Chat Completions route and controls request behavior such as reasoning effort, streaming, timeouts, prompt caching, headers, and per-turn tool-call limits. These values shape both model preflight and later execution. References: strix/…/settings.py• L29-105, strix/…/settings.py• L107-150, strix/…/settings.py• L154-229, strix/…/models.py• L520-545, strix/…/models.py• L620-640
Environment-backed enum values are normalized without regard to letter case. The API route accepts responses or chat_completions, while the model and dedupe settings keep their own request limits and credentials. This lets deployment settings use stable names while still producing typed launch policy. References: strix/…/settings.py• L11-19, strix/…/settings.py• L29-36, strix/…/settings.py• L101-104, strix/…/settings.py• L107-131
The parser keeps the user's instruction separate from the prepared instruction. This lets later scope guidance be added to the scan task without changing the text that represents the user's original request. References: strix/…/cli_args.py• L317-336
Environment preparation
Environment preparation makes sure the host can start a scan and that the sandbox image is ready. The check runs before scan execution and gives a direct setup error when a required service or setting is missing.
Runtime checks
The launch path checks for the Docker command, connects to the Docker service, and pulls the configured sandbox image when it is not already present. Interactive and non-interactive scans both require this runtime because scan work runs in the sandbox. References: strix/…/main.py• L468-469, strix/…/environment.py• L22-46, strix/…/environment.py• L144-217
The model setting is required for ordinary API-key routes. A ChatGPT subscription route instead requires a stored sign-in. Optional search and endpoint settings do not block launch when they are absent. References: strix/…/environment.py• L28-52, strix/…/settings.py• L29-62, strix/…/settings.py• L177-208
Model preflight
Before a non-interactive scan starts, the CLI sends a small model request to confirm that the configured route works. It also checks a separately configured dedupe model when one exists. Interactive setup performs this check after the user starts the scan, so the setup interface can appear without waiting on a model round trip. References: strix/…/scan_setup.py• L53-97, strix/…/main.py• L137-257, strix/…/runtime.py• L107-168
The launch path warns about unknown bare model names and about models that are not recommended for security scans. When a provider dependency is missing or a ChatGPT subscription cannot use the selected model, the error includes a route-specific setup hint. The preflight uses the selected API path and model settings, so an endpoint that needs a forced route can fail before target work begins if its settings do not match. References: strix/…/main.py• L91-134, strix/…/main.py• L151-214, strix/…/main.py• L358-377, strix/…/models.py• L807-819
Authentication
The auth command manages the optional ChatGPT subscription route outside the scan setup path. Sign-in stores OAuth credentials separately from the general CLI configuration, and a model name with the chatgpt/ prefix selects that route for inference.
Subscription sign-in
strix auth login chatgpt starts a browser sign-in with a local callback when possible. The user can use manual redirect paste when the callback server cannot start or times out. The flow checks the OAuth state on loopback callbacks and saves a token record only after the code exchange succeeds. References: strix/…/auth_cli.py• L44-179, strix/…/auth_cli.py• L182-237
The sign-in record contains the account identity and refresh data in a protected file. Requests refresh near-expiry tokens under a process-safe guard, so a long scan can keep using the subscription route. status reports whether the account is signed in, while logout removes the stored record. References: strix/…/codex.py• L57-105, strix/…/codex.py• L318-388, strix/…/auth_cli.py• L245-265
Update checks
The CLI checks for newer releases without delaying normal startup more than needed. A background check refreshes a cached result at most once per day, and it is disabled in CI or when the user sets STRIX_NO_UPDATE_CHECK.
Interactive launches may ask the user to update before Docker and scan setup. A binary can replace itself, while package installs receive the matching package-manager command. The explicit strix --update path exits after attempting the update and does not start a scan. References: strix/…/update_check.py• L38-78, strix/…/update_check.py• L146-205, strix/…/update_check.py• L238-264, strix/…/cli_args.py• L111-117, strix/…/main.py• L456-467
Standalone binary updates download a platform release and verify its published SHA-256 digest when one is available before replacing the current binary. The restart path clears bootloader state so the new process uses the updated binary. References: strix/…/update_check.py• L119-143, strix/…/update_check.py• L267-294, strix/…/update_check.py• L315-376
Target selection
Target selection converts user text into typed scan targets. The typed form preserves the original display value and adds the details needed to prepare each target for the sandbox.
Target types
The selector recognizes web applications, repositories, local code directories, IP addresses, and API specifications. It also accepts a Postman collection reference that can include an environment identifier. Ambiguous HTTP targets are checked for repository behavior before they are treated as web targets. References: strix/…/utils.py• L1132-1225
Target lists are read before type inference. Invalid paths, malformed target values, unreadable list files, and unsupported API inputs stop setup with a user-facing error rather than reaching execution. References: strix/…/scan_setup.py• L100-162, strix/…/utils.py• L1228-1251
Target isolation
Local code targets are checked before they are mounted. The guard rejects system, home, and credential directories so a target mount represents a project rather than a host secret area. Duplicate local paths are reduced to one target. References: strix/…/utils.py• L1340-1453
Each local source receives a distinct workspace name. Localhost URLs and loopback IP targets are rewritten to the host gateway name so a sandbox can reach services running on the host. These changes affect sandbox access, not the user-facing target identity. References: strix/…/utils.py• L1283-1305, strix/…/utils.py• L1312-1337, strix/…/utils.py• L1456-1495
API specification resolution
API specifications are parsed during setup so syntax and declared base URLs are known before execution. A Postman collection reference is fetched on the host and written to a local staging file, which keeps the Postman API key out of the sandbox. References: strix/…/scan_setup.py• L136-162, strix/…/utils.py• L1497-1512
Run preparation
Run preparation turns typed targets into a named, persistent scan context. It runs after the host and model checks on the non-interactive path, or after the user confirms settings in the interactive path.
Source preparation
Preparation generates a run name, clones repository targets, collects local source trees, and stages API specifications. It then resolves the requested diff scope and adds its review guidance to the scan instruction when that scope is active. References: strix/…/scan_setup.py• L164-200, strix/…/utils.py• L1515-1597
Diff scope is most useful for code review runs. auto enables it for non-interactive CI or pull-request contexts when a suitable repository is present. diff requires a usable Git history and base reference. full leaves the source scope unrestricted. References: strix/…/utils.py• L943-965, strix/…/utils.py• L1036-1118
Workspace context
A workspace mount is working context rather than an authorized target. It is added after diff-scope resolution, so it does not widen the reviewed source scope. Extra workspace files are copied as read-only inputs under /workspace and are kept outside target directories. References: strix/…/scan_setup.py• L202-223, strix/…/utils.py• L1709-1786
Scan input assembly
The final scan configuration combines the typed targets with source mounts, staged files, instructions, scope metadata, scan mode, and execution limits. The CLI passes this configuration to the scan engine, while the interactive runtime builds the same shape after setup confirmation.
The main input groups are:
| Input group | Purpose |
|---|---|
| Targets | Defines what the scan is authorized to test and how each target is reached. |
| Local sources | Supplies local code, cloned repositories, staged API specs, and any approved workspace mount. |
| Workspace files | Adds read-only host files such as wordlists, notes, or API data. |
| Instructions | Carries user intent and any generated diff-scope guidance. |
| Scan policy | Selects scan mode, scope mode, diff base, budget, and turn limits. |
Task context
The root task presents authorized targets by type and keeps working directories separate from targets. Workspace files are named as read-only data, not as instructions or assets to assess. The user's instruction is added after this context so it can guide work without changing the verified scope. References: strix/…/inputs.py• L39-190
Scope authorization
A separate scope context gives downstream tools a canonical target value and the sandbox path for each authorized item. API specification base URLs are added as authorized web targets, which lets the scan cover declared operations without treating that access as an unverified scope expansion. References: strix/…/inputs.py• L193-244
Model request settings
The input layer also converts model policy into request settings for the selected route. It carries request limits, retry behavior, reasoning choice, provider headers, and supported prompt-cache options so the execution layer receives a model request that matches the configured provider. The route can use Responses or Chat Completions, and launch settings can bound streaming gaps, disable streaming for a non-streaming gateway, and limit tool calls in one turn. References: strix/…/inputs.py• L247-335, strix/…/settings.py• L29-105, strix/…/models.py• L245-359
The run record persists these inputs with the run identity and authentication mode. This record supports later inspection and gives resume a stable source for restoring the original target and workspace context. References: strix/…/cli.py• L86-106, strix/…/runtime.py• L75-96, strix/…/scan_setup.py• L239-267
Resume behavior
Resume continues a stored run instead of creating a new target set. It rejects new target arguments, restores the saved instruction and source context, and requires both the run record and the first agent snapshot to exist. A prior target-less run can resume when it has a saved working directory or user instruction.
Resume revalidates local directories, cloned repositories, workspace mounts, and saved workspace-file destinations. A missing workspace file is dropped as optional context, but a missing workspace mount or cloned repository stops the resume because the original scan context cannot be rebuilt safely. References: strix/…/cli_args.py• L338-458
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the target type records aligned with source collection, workspace naming, API staging, scope authorization, and canonical target values.
- Keep
--scope-mode, diff metadata, the generated instruction block, and the persisted user instruction aligned so the agent sees the same scope that the run record reports. - Keep subscription model naming, stored OAuth records, environment validation, and model-provider selection aligned.
- Keep the selected API type, endpoint defaults, extra headers, and model route resolution aligned for both model preflight and later requests.
- Keep model request controls such as route selection, reasoning effort, prompt caching, streaming fallback, timeouts, and per-turn tool-call limits aligned with the execution loop.
- Keep
--mcp-config,STRIX_MCP_CONFIG, and the per-run MCP include and exclude selections aligned with the MCP loader. - Keep persisted workspace-file paths constrained to
/workspaceso fresh runs and resumes enforce the same boundary. - Keep interactive and non-interactive preparation paths equivalent when adding a new scan input or policy setting.
- Keep standalone release asset names, digest lookup, binary replacement, and restart environment handling aligned when changing self-update behavior.
- Keep scan-only startup checks separate from viewer, authentication, completion, and cloud command paths so commands without a scan do not require scan inputs or Docker.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
STRIX_LLM is missing for an API-key route | Startup stops before scan preparation. | Environment validation requires a model and prints setup guidance. |
| Docker is missing, stopped, or cannot pull the sandbox image | No scan can start. | The CLI checks the command, daemon, and configured image before launch. |
| Model preflight cannot reach the selected route or dedupe model | Non-interactive startup exits and interactive setup reports a preparation error. | A bounded model check runs before the scan. |
| A model uses an unknown bare name or lacks its optional provider dependency | The scan may stop before its first model request. | Model validation warns on unknown names and reports install hints for known provider failures. |
| The configured API type does not match the selected endpoint | Model preflight or the first model request fails. | Set the API type explicitly when an endpoint needs a non-default request path. |
| A streaming gateway cannot provide events or stays idle | A model turn fails or waits until its limit instead of completing. | Use the non-streaming fallback for gateways without streaming and set first-event, idle, or total stream timeouts for streamed routes. |
| A model response contains too many tool calls | Calls past the per-turn limit are dropped. | The configured per-turn tool-call limit bounds the response before execution. |
| A target is invalid or a local path is a protected system or credential directory | Target preparation stops before mounting or cloning. | Type inference and mount validation reject the input. |
| Forced diff scope has no usable Git history or base reference | Scan preparation fails instead of claiming a changed-file review. | Diff resolution checks repository state and base reachability. |
| A standalone update has a checksum mismatch or unsupported platform | The current binary is not replaced. | The updater verifies the release digest when published and checks the platform target before replacement. |
| Resume lacks its run record, agent snapshot, or required source mount | Resume cannot reconstruct the earlier run and exits with an actionable error. | Resume validates persisted state and current paths. |
| A scan-only command is sent through a non-scan command path | The command exits without scan setup, or the requested scan never starts. | Early routing handles viewer, auth, completion, and cloud commands before scan parsing. |
Key files
| File | Why to read it |
|---|---|
| strix/…/main.py | Shows command routing and the order of update, runtime, model, preparation, and interface steps. |
| strix/…/cli_args.py | Defines the user-facing scan inputs, MCP selection, and resume rules. |
| strix/…/scan_setup.py | Connects target resolution, model preflight, source preparation, persistence, and telemetry. |
| strix/…/utils.py | Defines target classification, local-source handling, diff scope, API staging, and workspace-file boundaries. |
| strix/…/inputs.py | Shows how verified targets, workspace context, instructions, scope data, and model policy become scan inputs. |
| strix/…/settings.py | Defines environment-backed model, runtime, context, integration, viewer, and request policy settings used during launch. |
| strix/…/models.py | Shows how the selected model route and request safeguards are applied before model execution. |
| strix/…/environment.py | Shows host and sandbox readiness checks. |
| strix/…/auth_cli.py and strix/…/codex.py | Explain subscription sign-in and how credentials support model access. |
| strix/…/update_check.py | Explains cached release checks, update choices, and standalone binary replacement. |
| strix/…/runtime.py | Shows how interactive setup reuses the shared preparation path. |