Primary Commands - troqcloud

troqcloud This page documents how to use the primary troq command surface effectively before deep-diving into command-specific internals.

Core Invocation Pattern

Every operation follows the same shape:

troq [GLOBAL_OPTIONS] <COMMAND> [SUBCOMMAND/ARGS]

Global options set context and runtime behavior.
<COMMAND> defines the domain operation to execute.

Current Primary Top-Level Commands

auth
apps
addons
logs
secrets
routes
audit
rbac
checks
workspace
doctor
config
whoami
ship
help

Version is exposed as global flags:

troq -V
troq --version

Global Context Flags (Most Important)

`--profile`

Selects which local CLI profile is used for credentials and API config.

troq --profile default whoami
troq --profile prod ship --source-path .

`--workspace`

Sets workspace scope for the current call.
Use this to avoid accidental cross-workspace operations.

troq --workspace ws_123 apps list
troq --workspace ws_123 ship --source-path .

`--app`

Sets default app target for commands that support app context.

troq --workspace ws_123 --app app_123 logs --tail

Environment is no longer exposed as a public root/global flag. In the simplified flow, environment is resolved from command-level inputs and project context (troq.toml) so that root usage stays minimal.

Other High-Value Global Flags

--output <table|json|jsonl>: choose human or machine output contract.
--timeout-secs <n>: request timeout control.
--retries <n>: transient retry budget.
--request-id <id> and --correlation-id <id>: traceability and incident correlation.
--yes: non-interactive confirmation for sensitive write paths.

Output Strategy

table: default for human operation sessions.
json: deterministic payload for scripts and debugging.
jsonl: streaming automation and log pipelines.

Examples:

troq --output table whoami
troq --output jsonl logs --tail

Common Operator Mistakes

1) Passing only a global flag without a command

This is invalid:

troq --profile default

You must still provide a command:

troq --profile default whoami

2) Expecting global option previews

This is invalid:

troq --workspace

Provide a value and command:

troq --workspace ws_123 apps list

3) Confusing identity failures with command syntax

If syntax is correct but whoami fails, it is usually session/token state and requires:

troq auth login

Practical Baseline Command Set

Use this baseline to validate your local CLI context quickly:

troq -V
troq --profile default whoami
troq --workspace ws_123 apps list
troq ship --source-path .

Last Updated: 2026-05-11