Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / cloud-commands-and-sessions

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:

  • --json requests machine-readable output. JSON also becomes the default when standard output is not a terminal.
  • --token, --workspace-id, --app-url, and --timeout provide per-process overrides.
  • Write commands accept --data as 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:

  1. Parse and validate the target and scan options.
  2. Prepare any local source snapshot and attach its upload when requested.
  3. Send the scan creation request with an idempotency key.
  4. Return the created scan, or poll its status when --wait is present.
  5. 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:

ConditionCLI result
Successful JSON responseReturn the decoded result
Network failureReport that the result may be unknown
401 or 403Authentication exit code 4
402 or scan credit limitPayment exit code 5
Other failureGeneral 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

TriggerConsequenceGuard
Stored token and active platform have different originsThe request is refused with an authentication errorBind stored credentials to app_url and require a deliberate override for another platform
Scan launch loses its response after the request startsThe run or charge may exist even though the CLI has no resultInspect the run and retry the exact request with the same idempotency key
A signed source upload URL points outside the configured platform or approved storageSource data is not uploadedValidate the upload origin and storage path before sending the archive
Top-up wallet exits without a confirmed receiptPayment state is unknownCheck the workspace credit balance before another payment attempt
Non-interactive top-up lacks explicit approvalThe challenge is shown and no payment startsSupply --yes or use --no-pay to inspect the challenge
Remote logout cannot revoke the sessionThe local token remains and sign-out is not completedRetry logout; use --local-only only when remote revocation is intentionally deferred
Binary output is sent to a terminal without a fileThe command refuses to mix binary bytes with terminal textUse --output FILE, or redirect stdout deliberately

Key files

FileWhy to read it
strix/…/__init__.pyCloud command dispatch, default command behavior, and top-level exit handling
strix/…/arguments.pyShared usage-error contract for cloud argument parsing
strix/…/spec.pyOperation shape for resource verbs, request fields, wait paths, links, and idempotency
strix/…/runner.pyEnd-to-end command path from parsed arguments to request, wait, payment, and output
strix/…/http.pyPlatform URL, token, workspace, upload, request, response, and exit-code boundary
strix/…/billing.pyCredit top-up approval and payment outcome handling
strix/…/payment_proxy.pyToken-safe loopback boundary between the CLI and wallet client
strix/…/render.pyHuman, JSON, detail, table, and bounded output views
strix/…/session.pyRemote session inspection and scope changes
strix/…/platform_cli.pyBrowser login, workspace and scope selection, local token storage, and logout
strix/…/platform_identity.pyStable installation identity and privacy-safe device label