Skip to main content
troqcloud This page documents the current authentication surface exposed by:

Auth Surface Overview

The current public auth surface includes troq auth login, troq auth logout, troq auth whoami, troq auth refresh, and troq auth sessions. Inside sessions management, the active commands are list, revoke, and revoke-all. Some future auth paths exist in the codebase but are intentionally hidden or disabled right now to keep the operator interface narrow and safer.

troq auth login

troq auth login is an interactive browser-based login that stores access and refresh tokens in the selected CLI profile. The CLI generates a login URL with a nonce and localhost callback, opens the browser, receives the callback token payload, validates tokens against the API, and only then saves profile auth state. Command:
Help:
In normal operation the terminal shows a login URL, waits for callback completion, then prints a success summary for the target profile. In development, login client URL and API base URL are intentionally separate concerns and should stay decoupled.

troq auth whoami

troq auth whoami is the fastest validity check for the current session state and identity resolution. Command:
Or top-level alias:
In table mode it prints profile and identity fields such as name or email when present in /me response data. If the session is unauthorized, it returns a clear login guidance error.

troq auth refresh

troq auth refresh rotates an expired access token using the stored refresh token, without a full browser login loop. Command:
This is the right command when access tokens expire but refresh token state is still valid. If refresh state is missing, expired, or rejected by API policy, fallback is a clean browser login:

troq auth logout

troq auth logout clears local token material for the active profile. Command:
After logout, whoami should return unauthorized and privileged command paths should fail until a new login is completed.

troq auth sessions

troq auth sessions is used to inspect and control active sessions for the authenticated principal.

troq auth sessions list

troq auth sessions list returns the current session set.
Table output includes item count, session identifiers, and human-readable timestamps in DD/MM/YYYY HH:MM:SS UTC format.

troq auth sessions revoke

troq auth sessions revoke revokes one target session by ID.

troq auth sessions revoke-all

troq auth sessions revoke-all revokes all sessions for the current principal except the active one, depending on server policy.

Output Modes in Auth

All auth commands support --output table, --output json, and --output jsonl, so you can use the same auth workflows in interactive terminals and automation environments. Examples:

Profile and Context Interaction

Auth is profile-scoped, so selecting profile explicitly is the most reliable way to avoid context mistakes:
In practice, --profile on the command line wins over active profile defaults from local config.

Security Guidance

Use browser login as the default operator path, treat local profile token storage as sensitive material, and revoke sessions aggressively on shared machines. In incident workflows, pass request and correlation IDs and avoid any terminal habits that leak token values into shell history.

Fast Verification Checklist

This short sequence validates end-to-end auth behavior:
Last Updated: 2026-05-11