login & auth
Sign in with SSO, check your identity, and sign out.
tunnelctl authenticates against your organization's identity provider using OIDC. Tokens are stored locally and refreshed automatically before each API call, so you typically only log in once.
tunnelctl login
tunnelctl loginBy default (--auth-flow=auto) the CLI picks the right sign-in flow for your environment:
on a desktop with a browser it opens the identity provider directly; on a headless box
(SSH, container, CI) it falls back to the device flow.
Choosing a flow explicitly
--auth-flow | Flow | How you sign in |
|---|---|---|
auto (default) | runtime detection | TTY + browser launcher available → pkce-url-open; otherwise → device |
pkce-url-open | Authorization Code + PKCE | browser opens automatically; a local callback completes the login |
pkce-url-print | Authorization Code + PKCE | the sign-in URL is printed — open it yourself on the same machine; local callback completes the login |
device | Device Authorization Grant (RFC 8628) | prints a short code + verification URL — open it on any device; no local callback or port needed |
tunnelctl login --auth-flow=device # headless / SSH / container / CI
tunnelctl login --auth-flow=pkce-url-print # same machine, but don't auto-launch the browserThe pkce-* pair are the same flow differing only in URL delivery; device is a separate
grant that never needs a callback — ideal when the browser lives on a different machine
than the CLI.
--no-browser is deprecated (0.9)
The pre-0.9 --no-browser flag still works as an alias for
--auth-flow=pkce-url-print — it prints a deprecation warning, is hidden from
--help, and will be removed in 1.0. Combining it with --auth-flow is an error.
Note it was never the device flow: for sign-in from another device use
--auth-flow=device.
tunnelctl whoami
Show who you're signed in as and when the token expires.
tunnelctl whoami
tunnelctl whoami --verify| Flag | Description |
|---|---|
--verify | Verify the tokens work end-to-end — against the identity provider and the tunnelctl API. |
tunnelctl logout
tunnelctl logoutRemoves the locally stored tokens. Running tunnels keep their own per-tunnel connection tokens until they stop.
Token lifetime
The access token is short-lived (~5 minutes) and refreshed transparently using the refresh token. See Authentication for the full model.