Skip to main content
troqcloud Secrets in troqcloud are encrypted key-value pairs scoped to an application. They are stored server-side, versioned on every write, and injected into your app’s runtime environment at deploy time. The troq secrets command group covers the full lifecycle: setting values, listing what exists, inspecting version history, rolling back to a previous version, and rotating a secret when it has been compromised or expired. Secrets are not applied to a running app instantly. After any write operation (set, unset, rollback, or rotate), you need to redeploy the app for the new values to take effect in the runtime environment:
The CLI will remind you of this after every write.

Setting Secrets

troq secrets set is the primary write command. It accepts one or more KEY=VALUE pairs in a single call, setting your full environment in one command is cleaner, faster, and produces a better audit trail than running set once per variable.
When you pass multiple pairs, the CLI routes the request through bulk upsert automatically, no different command needed. The output confirms how many secrets were written and which key was processed last. If any pair is malformed (missing =, empty key, empty value), the entire batch is rejected before anything is sent to the server. Setting a secret that already exists replaces its value and increments the version number. The previous value is retained in version history and can be restored with rollback. A practical habit is to keep a local .env file for development and mirror the production values through set when they change. Never pass secrets as inline shell arguments in shared scripts or CI logs, use environment variables or secret injection mechanisms in your CI provider to feed values to troq secrets set.

Listing Secrets

troq secrets list returns the current set of secrets for the app, showing the key name, current version number, and last updated timestamp. Secret values are never included in list output.
The app context is resolved from troq.toml in the current directory, or from --app if passed explicitly. If neither is present, the CLI will prompt for selection.

Revealing a Secret Value

troq secrets reveal returns the current plaintext value of a single secret. This is a privileged operation and requires the secrets.read permission with access to the reveal path specifically.
Use this command only when you need to verify or copy a stored value. Avoid piping the output into logs or files where it could be retained in plaintext.

Version History

Every write to a secret, whether through set, rollback, or rotate, creates a new version entry. troq secrets history shows the full version history for a given secret key, including the operation type, the actor who made the change, and when it happened.
This is useful for auditing who changed a value and when, and for identifying which version number to target when rolling back.

Rolling Back a Secret

troq secrets rollback restores a secret to a specific previous version. You pass the key name and the version number you want to restore. The version number comes from troq secrets history output.
Rollback is a confirmed write operation. In non-interactive mode, pass --yes as a global flag before the secrets subcommand. In interactive mode the CLI will prompt for confirmation. After a successful rollback, the secret’s version counter increments, the restored value becomes the new current version, not a rewind of the counter. After rolling back, redeploy the app to apply the restored value to the running environment:

Rotating a Secret

troq secrets rotate marks a secret as rotated and increments its version. This is the right operation when a credential has been compromised or has expired and needs to be treated as invalid, even if the underlying value has not changed yet on the external service.
The --reason flag is optional but strongly recommended for compliance and incident records. The reason is stored in the audit trail for the rotation event. After rotating, update the actual credential on the external service, then call set with the new value, and redeploy with troq ship.

Deleting a Secret

troq secrets unset removes a secret from the app. The key and all its version history are soft-deleted. Deletion is confirmed, pass --yes as a global flag in non-interactive usage.
After unsetting, redeploy the app. If the application code depends on the deleted variable at startup, it will fail on the next deploy until the dependency is removed from the code or the secret is restored.

Non-Interactive and Automation Usage

All secrets commands work without interactive prompts when the required values are passed as flags. This is the expected pattern for CI/CD pipelines and automation scripts.
The --app global flag overrides the troq.toml context. The --workspace flag can be added when the workspace is not already resolved from profile or project context. For destructive operations in automation, always pass --yes before the secrets subcommand:

Output Formats

All secrets commands support --output table, --output json, and --output jsonl. Table mode is the default. JSON and JSONL carry the full response payload and are suitable for piping into downstream tools or storing operation records.
Note that reveal output in any format will include the plaintext secret value. Treat the output of that command with the same care as the credential itself.

Permission Requirements

Read operations (list, reveal, history) require secrets.read. Write operations (set, unset, rollback, rotate) require secrets.write. You can check your current access with:
If access is missing, ask your workspace owner to assign a role that carries the required permission. Use troq rbac roles-permissions-list to see what each role grants before requesting a change. Last Updated: 2026-05-11