Skip to main content
troqcloud This page documents the current CLI surface exactly at the level exposed by troq --help.
It is intentionally detailed about operator-facing behavior, but does not yet go into per-subcommand internals.

Primary Operational Model

Troq CLI should be read as:
  1. Global operator context is declared once.
  2. A domain command executes one operation.
  3. Output shape is selected for human or automation usage.
  4. Confirmation and permission checks gate sensitive writes.
This makes the CLI usable both as an interactive operator tool and an automation contract in CI/CD pipelines.

Command Families Exposed in Help

  • auth: identity, session, and access control entrypoint.
  • apps: application lifecycle and app-scoped metadata surface.
  • addons: managed add-on lifecycle operations.
  • ship: source-to-build-to-deploy unified operator flow.
  • logs: deployment/runtime log retrieval and streaming.
  • secrets: secret value lifecycle and policy controls.
  • routes: route/proxy policy and lifecycle controls.
  • audit: compliance and investigative query surface.
  • rbac: role/permission/member management. See the dedicated Access Control page for full operator guidance.
  • checks: summarized readiness checks.
  • workspace: workspace lifecycle and ownership operations.
  • doctor: local operator diagnostics.
  • config: local CLI profile/context management.
  • whoami: top-level identity check alias.

Global Flag Semantics

Output and contract shape

  • --output <table|json|jsonl>
    • table: concise operator-readable output.
    • json: deterministic structured payload.
    • jsonl: stream-friendly single-line JSON output.

Execution context

  • --profile <PROFILE> selects credential/profile scope.
  • --workspace <WORKSPACE> sets target workspace context.
  • --app <APP> sets target app context.
  • --locale <LOCALE> sets locale preferences when supported.
Environment is now resolved by command inputs and project-local context instead of a public root --environment flag.

Traceability

  • --request-id <REQUEST_ID> sets request identity for tracing.
  • --correlation-id <CORRELATION_ID> links related operations together.

Runtime behavior

  • --timeout-secs <TIMEOUT_SECS> controls request timeout behavior.
  • --retries <RETRIES> controls retry attempts for transient failures.
  • --detach enables asynchronous behavior where supported.
  • --watch enables watch/stream loops where supported.
  • --verbose increases diagnostic output.

Write confirmation model

  • --yes is the non-interactive confirmation mechanism for sensitive write paths.
  • Without non-interactive confirmation, sensitive operations should require explicit interactive acknowledgement.

Operator Security Posture

  • Prefer troq auth login interactive credential handling over passing secrets in shell history.
  • Use request and correlation IDs for incident timelines and forensic reconstruction.
  • Treat json/jsonl output as automation contracts and sanitize downstream logs.
  • Keep write operations explicitly scoped by workspace/app/environment context.

Current Help Snapshot Examples

Config Command Simplification

The config surface has been simplified to reduce noisy and risky operations for most users. troq config show now prints only the information an operator actually needs for day-to-day usage: active profile and workspace name. It intentionally hides API internals, token state markers, and non-essential toggles. troq config set is now minimal and user-facing only for locale. Internal implementation knobs like API base URL, API version, telemetry toggles, and non-persisted placeholder flags are intentionally hidden from help output. Inside troq config profile, the public command set is now limited to show, use, and list. Advanced profile lifecycle commands (create, delete, export, import) were removed from public CLI flow to keep profile handling simple and safer for operators. troq config context show now resolves the project workspace to a human-readable workspace name when available, while still showing app and environment from project context. If name resolution is temporarily unavailable, it safely falls back to the workspace identifier.

Ship Reliability Update

troq ship now handles long-running build/deploy sessions more safely by re-authenticating when a token expires during polling. This avoids failing a live rollout with a mid-run 401 and lets the command continue through build and deployment status loops. The waiting line output is also colorized and paced so status text remains readable during long operations.

Audit UX and Security Update

troq audit table output is now operator-readable by default. It renders human action labels (for example Read build logs, Start deploy, List workspace members) and hides raw internal route values in table mode. Timestamps are shown in DD/MM/YYYY HH:MM format. Action filtering also accepts these readable labels directly:
When a friendly label is passed, the CLI resolves it to backend route/method filters automatically. For security, --principal-id is workspace-scoped. The queried principal must be a member of the active workspace; otherwise the request is denied. Use this command to discover valid workspace user IDs:
The public audit surface is intentionally simplified. Advanced debug-oriented flags (route-prefix, method, offset, csv) are hidden from normal help output to keep routine usage safe and focused. Last Updated: 2026-05-11