Cloud commands and sessions
The cloud CLI is the terminal interface to the managed Strix platform. It turns command arguments into authenticated API requests, starts and monitors managed security work, handles credit payment boundaries, and keeps a local record of the CLI session. For scan targets and workspace use, see Cloud source scans and workspaces; this page focuses on the command and session layer around those flows.
Command surface
The command surface gives engineers one consistent way to call managed platform operations. A command group selects a resource area, a verb selects an operation, and shared options control authentication, output, time limits, and request data.
Argument model
The CLI builds each resource command from a declarative operation description. It supports short default commands such as strix cloud scans and strix cloud billing, while two-word verbs are resolved before one-word verbs. Invalid arguments become a cloud usage error with exit code 2 instead of an unhandled parser exit.
Common command behavior includes:
--jsonrequests machine-readable output. JSON also becomes the default when standard output is not a terminal.--token,--workspace-id,--app-url, and--timeoutprovide per-process overrides.- Write commands accept
--dataas a JSON object, from a literal value, a file, or standard input. Explicit command options cannot be silently replaced by fields from--data. - Mutations that can create work support a stable idempotency key. The CLI can retry only the same request when the result is unclear.
These rules let a human use readable defaults while an agent or CI job receives stable JSON and safe retry guidance. The cloud entry point is dispatched before local scan setup, so managed commands do not need a target, Docker, or local model setup. strix/…/__init__.py• L57-118 strix/…/arguments.py• L11-18 strix/…/runner.py• L150-211
References: strix/…/__init__.py• L57-118 strix/…/arguments.py• L11-18 strix/…/runner.py• L150-211 strix/…/spec.py• L13-46
Managed-run lifecycle
Managed-run creation sends a scan request to the platform and returns an operation identifier. The request can describe domains, repositories, internal targets, uploaded source, credentials, focus, and notifications. When the caller does not set a test category, the CLI infers one from the target kind so the platform receives a complete request.
The normal lifecycle is:
- Parse and validate the target and scan options.
- Prepare any local source snapshot and attach its upload when requested.
- Send the scan creation request with an idempotency key.
- Return the created scan, or poll its status when
--waitis present. - Stop at a terminal state such as completed, failed, cancelled, or expired.
This diagram shows how a command becomes a managed run and how an uncertain launch is handled.
flowchart LR
A[Cloud scan command] --> B[Validate arguments]
B --> C{Local source?}
C -->|yes| D[Prepare and attach source]
C -->|no| E[Build request]
D --> E
E --> F[Create managed run]
F --> G{Wait requested?}
G -->|no| H[Return operation record]
G -->|yes| I[Poll status]
I --> J{Final state?}
J -->|no| I
J -->|yes| K[Return final record]
F -. unclear result .-> L[Check run before retry]
If transport fails after a mutation may have reached the platform, the CLI marks the launch as unknown and tells the caller to inspect the run before retrying. A caller-provided idempotency key gives an exact retry path; a new key can create a duplicate run or charge. The broader scan target and workspace flow is covered in Cloud source scans and workspaces. strix/…/runner.py• L276-330 strix/…/runner.py• L333-484 strix/…/runner.py• L1063-1128
References: strix/…/runner.py• L276-330 strix/…/runner.py• L333-484 strix/…/runner.py• L487-510 strix/…/runner.py• L757-849 strix/…/runner.py• L1063-1128
Platform identity
Platform identity answers two related questions: which Strix platform should receive a request, and which CLI installation is using the session. Login binds the stored credential to its platform origin and associates the token with one selected workspace.
Device identity
The CLI keeps one installation identity in the user’s Strix directory. It contains a generated installation identifier and a short device label. The identifier stays stable across logins, while --device-name can update the label shown for the session.
Login sends this identity during the browser device flow. The platform can therefore show a privacy-safe device entry without using a host name or other machine fingerprint. strix/…/platform_identity.py• L14-46 strix/…/platform_cli.py• L191-296
References: strix/…/platform_identity.py• L14-46 strix/…/platform_cli.py• L191-296
Workspace and scope identity
Login completes in the context of one workspace. If the account has more than one workspace, the CLI selects one by exact ID or name, or asks an interactive user to choose. Non-interactive use must provide --workspace when the choice is not unique.
Scopes define the actions the token may perform. The login flow supports minimal, recommended, full, or custom access within the role-based ceiling returned by the platform. The remote session can later narrow its granted scopes without exceeding that ceiling. strix/…/platform_cli.py• L381-426 strix/…/platform_cli.py• L436-549 strix/…/session.py• L93-138
References: strix/…/platform_cli.py• L381-426 strix/…/platform_cli.py• L436-549 strix/…/session.py• L93-138
Request boundary
The request layer is the trust boundary between the local CLI and the managed API. It selects the platform origin, adds the bearer token and workspace context, applies one request timeout, and converts network or HTTP outcomes into cloud exit codes.
Origin and credential binding
The CLI prefers an explicit platform URL or the configured platform URL. When it uses a stored sign-in, it checks that the stored token was issued by the active platform origin. It refuses to send that token to a different origin.
Platform URLs must use a valid HTTP or HTTPS origin form. The CLI rejects unsafe URL forms such as embedded credentials, fragments, and unexpected query data before it uses them. This binding prevents a stale sign-in from silently becoming a credential for another server. A caller can still use an explicit token for a deliberate platform override, with the workspace supplied separately when the token needs that context. strix/…/http.py• L67-163
References: strix/…/http.py• L67-163
Request and response contract
Every managed API request uses the /api/v1 boundary and carries authorization. A workspace header is added when the process has selected one. Idempotency is added only for operations that declare it, which keeps retry behavior tied to the operation contract.
Responses follow one error model:
| Condition | CLI result |
|---|---|
| Successful JSON response | Return the decoded result |
| Network failure | Report that the result may be unknown |
401 or 403 | Authentication exit code 4 |
402 or scan credit limit | Payment exit code 5 |
| Other failure | General error exit code 1 |
The client does not follow redirects. It also rejects successful non-JSON responses for normal API operations, which helps detect a wrong platform URL or an unexpected proxy response. strix/…/http.py• L165-212 strix/…/http.py• L331-373
References: strix/…/http.py• L165-212 strix/…/http.py• L331-373
Source upload boundary
Source uploads use a platform-issued signed URL and a short-lived upload token. Before sending source data, the CLI checks that the URL points to the configured platform or an approved managed storage origin. It does not follow redirects during the upload.
This keeps a source archive and its upload credential inside the storage boundary selected by the platform. An invalid or untrusted upload URL stops the upload before local source data is sent. strix/…/http.py• L214-280
References: strix/…/http.py• L214-280
Payment boundary
Billing separates a Strix credit request from payment approval. The platform first returns an HTTP 402 challenge when payment is needed, and the CLI either shows that challenge or asks an approved wallet to complete it.
Top-up authorization
Interactive top-ups ask the person to approve the purchase. Non-interactive or JSON use requires --yes; --no-pay returns the challenge without attempting payment. A browser checkout remains available for plan or credit-pack purchases when a person must complete the payment on a hosted page.
The wallet path supports two modes:
- A configured MPP wallet can pay with a supplied payment method.
- A Stripe Link wallet can sign in and approve a spend request in the Link app.
The CLI reports success only after its trusted bridge observes a valid billing receipt. A wallet process that exits without that confirmation produces an unknown outcome, so the caller must check the credit balance before retrying. strix/…/billing.py• L98-170 strix/…/billing.py• L207-284 strix/…/spec.py• L622-660
References: strix/…/billing.py• L98-170 strix/…/billing.py• L207-284 strix/…/spec.py• L622-660
Wallet bridge
The wallet bridge gives the payment client a one-run loopback URL instead of placing the Strix API token in the wallet command line. It accepts only the expected top-up body and a small number of POST requests. It forwards the request to the fixed billing endpoint while the Strix process keeps control of authorization and workspace headers.
The bridge bounds request and response sizes, blocks redirects, filters forwarded headers, and shuts down when the wallet flow ends. It reduces token exposure and limits accidental local reuse, but it is not a protection boundary against another process running as the same user. strix/…/payment_proxy.py• L1-7 strix/…/payment_proxy.py• L135-228 strix/…/payment_proxy.py• L245-286
References: strix/…/payment_proxy.py• L1-7 strix/…/payment_proxy.py• L135-228 strix/…/payment_proxy.py• L245-286
Output rendering
Rendering gives people compact views while preserving a machine contract for automation. The same API result can become JSON, a table, a narrow-terminal card view, or a bounded detail view based on output mode and the operation being displayed.
Human and machine views
JSON mode writes the API result without the human table shaping. Human mode chooses useful columns for common resources, flattens nested scan and target summaries, and adds hints for follow-up commands or pagination. Narrow terminals use cards instead of forcing a wide table.
The renderer removes internal identity fields from normal human views, sanitizes terminal text, and bounds cells and nested previews. One-time secrets and enrollment commands remain complete and copyable, with a warning that the person must store them securely. strix/…/render.py• L578-715 strix/…/render.py• L1308-1366 strix/…/render.py• L1458-1503
References: strix/…/render.py• L578-715 strix/…/render.py• L1308-1366 strix/…/render.py• L1458-1503
Binary output
Reports, SARIF, software bills of materials, and other binary operations use a separate output path. A terminal requires --output FILE; redirected standard output is reserved for deliberate byte streams. File writes use a temporary file before the final path is created, and replacement requires --force.
This keeps progress and error text from corrupting downloaded artifacts. When requested, file output can return JSON metadata such as the path, byte count, and content type instead of the binary bytes. strix/…/runner.py• L333-362 strix/…/runner.py• L908-1007
References: strix/…/runner.py• L333-362 strix/…/runner.py• L908-1007
Session lifecycle
The session lifecycle spans browser sign-in, local credential storage, remote session inspection, scope changes, and sign-out. The local record enables normal commands, while the remote session remains the authority for access and revocation.
Login lifecycle
Login starts a browser device authorization flow. The person confirms a code in the browser, chooses a workspace when needed, and approves a scope profile or custom scope set. The CLI then stores the returned token with its platform URL, workspace data, device identity, and scope preference.
The stored platform URL is part of the credential record. If storage fails after browser approval, the CLI does not claim the local sign-in is complete. A later device-aware login also attempts to revoke a replaced legacy session on the same platform. strix/…/platform_cli.py• L92-188 strix/…/platform_cli.py• L315-378 strix/…/platform_cli.py• L618-633
References: strix/…/platform_cli.py• L92-188 strix/…/platform_cli.py• L315-378 strix/…/platform_cli.py• L618-633
Session inspection
whoami reads the local record and reports account, workspace, scope summary, expiry, and platform state. session show asks the platform for the active remote CLI session, while session scopes shows the granted scopes and their maximum ceiling.
Scope changes use the remote session endpoint. When the command uses the stored sign-in, the returned scope state is written back to the local record so later commands describe the same access. Explicit token overrides do not alter the stored session. strix/…/platform_cli.py• L655-721 strix/…/session.py• L61-90 strix/…/session.py• L93-138
References: strix/…/platform_cli.py• L655-721 strix/…/session.py• L61-90 strix/…/session.py• L93-138
Logout lifecycle
Normal logout revokes the remote CLI session before removing the local token. If remote revocation fails, the local token stays in place so the person can retry safely. --local-only removes the local token without revoking the remote session, so it must not be treated as a full sign-out.
The result reports whether remote revocation occurred. A successful remote response or an already unauthorized session is treated as inactive; other responses stop the local deletion. strix/…/platform_cli.py• L588-615 strix/…/platform_cli.py• L724-798
References: strix/…/platform_cli.py• L588-615 strix/…/platform_cli.py• L724-798
Change checklist
When these files or sections are changed, remember to consider these:
- Keep command definitions, parser behavior, request-body merging, and idempotency handling aligned. A new mutation can otherwise accept a flag without gaining safe retry behavior.
- Preserve the platform-origin binding whenever token storage or URL selection changes. A stored token must not cross platform origins.
- Keep workspace selection consistent across login records, request headers, wallet forwarding, and scope updates.
- Keep signed source upload validation aligned with the platform origins that issue upload URLs. A change to storage hosts can otherwise block valid uploads or widen the upload trust boundary.
- Treat payment success as a confirmed billing receipt. Do not turn a wallet process exit code into a paid state without upstream confirmation.
- Keep human rendering and JSON rendering on separate paths. Human hints or terminal text must not enter machine-readable output or binary streams.
- Keep remote session revocation ahead of local token deletion unless the caller explicitly selects
--local-only.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Stored token and active platform have different origins | The request is refused with an authentication error | Bind stored credentials to app_url and require a deliberate override for another platform |
| Scan launch loses its response after the request starts | The run or charge may exist even though the CLI has no result | Inspect the run and retry the exact request with the same idempotency key |
| A signed source upload URL points outside the configured platform or approved storage | Source data is not uploaded | Validate the upload origin and storage path before sending the archive |
| Top-up wallet exits without a confirmed receipt | Payment state is unknown | Check the workspace credit balance before another payment attempt |
| Non-interactive top-up lacks explicit approval | The challenge is shown and no payment starts | Supply --yes or use --no-pay to inspect the challenge |
| Remote logout cannot revoke the session | The local token remains and sign-out is not completed | Retry logout; use --local-only only when remote revocation is intentionally deferred |
| Binary output is sent to a terminal without a file | The command refuses to mix binary bytes with terminal text | Use --output FILE, or redirect stdout deliberately |
Key files
| File | Why to read it |
|---|---|
| strix/…/__init__.py | Cloud command dispatch, default command behavior, and top-level exit handling |
| strix/…/arguments.py | Shared usage-error contract for cloud argument parsing |
| strix/…/spec.py | Operation shape for resource verbs, request fields, wait paths, links, and idempotency |
| strix/…/runner.py | End-to-end command path from parsed arguments to request, wait, payment, and output |
| strix/…/http.py | Platform URL, token, workspace, upload, request, response, and exit-code boundary |
| strix/…/billing.py | Credit top-up approval and payment outcome handling |
| strix/…/payment_proxy.py | Token-safe loopback boundary between the CLI and wallet client |
| strix/…/render.py | Human, JSON, detail, table, and bounded output views |
| strix/…/session.py | Remote session inspection and scope changes |
| strix/…/platform_cli.py | Browser login, workspace and scope selection, local token storage, and logout |
| strix/…/platform_identity.py | Stable installation identity and privacy-safe device label |