Skip to content
BeamUpbeamup docs

CLI Login And Logout

The CLI uses WorkOS AuthKit’s device authorization flow for human login and a BeamUp bearer token for API calls. The provider token is exchanged once and is not stored by BeamUp or the CLI.

Login

Section titled “Login”
Terminal window
beamup login

beamup login:

  • Checks whether the OS keychain already has a valid BeamUp token.
  • If a valid stored token exists, prints the current identity and does not replace it.
  • Starts a WorkOS device-code flow when no valid stored login exists.
  • Displays the login URL and user code.
  • Tries to open the browser unless --no-browser is set.
  • Stores only the BeamUp token in the OS keychain after provider exchange.
  • Calls whoami before reporting success.

Headless login:

Terminal window
beamup login --no-browser

The headless mode prints the URL and code without opening a browser. There is no local callback port. Complete the browser step on another device or browser, then leave the CLI running until it succeeds or expires.

If the device code expires, is denied, or times out, rerun beamup login. BeamUp waits at most 15 minutes for the provider flow.

Identity Check

Section titled “Identity Check”
Terminal window
beamup whoami

JSON:

Terminal window
beamup --json whoami

Plain output prints:

Signed in as <email-or-display-name-or-user-id>

Credential Precedence

Section titled “Credential Precedence”

For normal authenticated commands, credentials are resolved in this order:

  1. --token <TOKEN>
  2. BEAMUP_TOKEN
  3. OS keychain login created by beamup login

--token and BEAMUP_TOKEN are one-off, non-persisted credential paths. They are the supported path for scripts, CI, and headless agents.

Do not write BeamUp tokens to plaintext token files. Avoid pasting tokens into shared terminals, shell history, issue comments, or logs. If a keychain is not available, use a secure secret manager to provide BEAMUP_TOKEN to the process.

API URL Precedence

Section titled “API URL Precedence”

API URLs are resolved in this order:

  1. --api-url <URL>
  2. BEAMUP_API_URL
  3. http://127.0.0.1:3000 for local development

Non-local API URLs must use HTTPS.

JSON And Non-Interactive Use

Section titled “JSON And Non-Interactive Use”

--json emits one machine-readable result or error and never opens the TUI.

Examples:

Terminal window
beamup --json whoami
beamup --json --app hello-gleam status
beamup --json --app hello-gleam logs --no-follow

Logout

Section titled “Logout”
Terminal window
beamup logout

beamup logout reads the stored OS-keychain login directly. It does not use normal token precedence. It attempts to revoke the stored token on BeamUp, then removes the local keychain entry.

No stored entry is an idempotent success:

Already logged out.

If the remote token is already invalid or revoked, BeamUp removes the local entry and reports that the stored login was already invalid.

If BeamUp cannot confirm server-side revocation, the local entry is still removed, the command exits non-zero, and the remote token may remain active until it expires.

beamup logout rejects --token because explicit tokens are not stored login sessions. If BEAMUP_TOKEN is set, logout warns that future commands will keep using it until it is unset.

Switching Accounts

Section titled “Switching Accounts”

Run:

Terminal window
beamup logout
beamup login

If BEAMUP_TOKEN is set, unset it before switching accounts.