troq --help) and global flags that apply across command groups. The goal is to explain how the CLI actually behaves in operator workflows, not just restate flag names.
Root Command Contract
Every CLI operation follows one stable contract:<COMMAND> is missing, execution fails by design. This strict shape is intentional because it keeps command intent explicit and script-safe.
Top-Level Help
Use the root help as the source of truth for currently supported top-level surfaces:auth, apps, addons, logs, secrets, routes, audit, rbac, checks, workspace, doctor, config, whoami, and ship. Version output is intentionally centralized and available only through:
Global Flags
--output <table|json|jsonl>
This flag controls output serialization for all command groups. table is human-oriented terminal output, json is a structured payload for deterministic parsing, and jsonl is a line-delimited stream contract for pipelines or tail-like consumers. In production automation, json or jsonl should be treated as the stable interface.
Typical usage:
--color
There is no public --color flag in the current CLI surface. Color is automatic in table mode and is intentionally absent from machine formats. This keeps root usage minimal and avoids adding one more toggle that operators and scripts would have to reason about.
--profile <PROFILE>
This flag selects which local profile is used for credentials and API configuration. Profile definitions are persisted in local CLI config, the active profile can be switched with troq config profile use <name>, and an explicit --profile always applies to the current invocation only. In other words, this flag is the safest way to force profile isolation per command.
Examples:
--workspace <WORKSPACE>
This flag overrides workspace context for one command execution. It should be used aggressively for any sensitive read or write path because it reduces accidental cross-workspace actions. When omitted, some commands can resolve workspace from project context or profile defaults, but explicit operator intent is always safer than implicit resolution.
Example:
--app <APP>
This flag overrides app context for one command execution. It is most useful when working in mixed repositories or when running scripts against multiple app IDs in one session.
Example:
ship) and through project context in troq.toml, which keeps root usage smaller and clearer for operators.
Timeout and Retry Controls
--timeout-secs <TIMEOUT_SECS>
This sets a global request timeout budget per command path, with a default of 30. Lower values are useful for fail-fast CI signals, while higher values are reasonable for unstable networks or heavy control-plane operations.
--retries <RETRIES>
This sets retry budget for transient request failures, with a default of 2. Conservative retry counts are usually right for idempotent reads, while mutation flows should be handled carefully and paired with idempotency controls where available.
Example:
Related Global Controls
Beyond context and runtime controls, several root flags affect observability and operator safety.--request-id and --correlation-id provide end-to-end traceability, --yes enables non-interactive confirmation mode, and --detach or --watch modify command lifecycle behavior when supported by a specific command path. --verbose increases diagnostics and --locale provides localization hints.
Precedence Model (What Wins)
For context and profile resolution, precedence follows a practical operator model: explicit command flags win first, project context can be used next for commands that support it, and active profile defaults are fallback behavior. The contract is simple: explicit command intent always wins.Security and Ergonomy Recommendations
In production operations, always passing explicit workspace and app context is a better security posture than relying on ambient state. For incident handling, request and correlation identifiers should be standard practice. Automation should parsejson or jsonl rather than terminal-oriented table output, and retry policies should stay conservative on write paths.