Skip to main content
Ultra Hub uses browser-based OAuth authentication for interactive sessions and deploy keys for headless/CI environments.

​
Interactive Login

Authenticate from the CLI: 
ultra login
This opens your browser to complete authentication. After logging in, your credentials are stored locally in your Ultra config file and used for subsequent commands. 
# Login to the default Hub
ultra login

# Login to a self-hosted Hub
ultra login --hub https://hub.mycompany.com

​
How It Works

  1. Ultra starts a local callback server on port 19284
  2. Your browser opens to the Hub authentication page
  3. You sign in (or create an account)
  4. Hub redirects back to the local server with an auth token
  5. The token is saved to your config file

​
Session Management

  • Tokens are stored in ~/.config/ultra/config.yaml
  • If your session expires, Ultra warns you and disables Hub sync
  • Re-run ultra login to refresh your session

​
Check Login Status

# Shows your current auth state
ultra link  # Will tell you if you're not logged in

​
Deploy Keys

For CI/CD pipelines, servers, and other headless environments where browser-based login isn’t possible, use deploy keys.

​
Setting a Deploy Key

# Via environment variable (recommended for CI)
export ULTRA_DEPLOY_KEY=dk_xxxxxxxxxxxx

# Or in config file
hub:
  deploy_key: "dk_xxxxxxxxxxxx"
Deploy keys start with the dk_ prefix. The ULTRA_DEPLOY_KEY environment variable takes priority over the config value.

​
Authentication Priority

Ultra checks for authentication in this order:
  1. ULTRA_DEPLOY_KEY environment variable
  2. deploy_key in config file
  3. OAuth access token from ultra login

​
Logging Out

# Logout and clear credentials
ultra logout

# Logout without confirmation
ultra logout --force
Logging out clears all Hub credentials and unlinks the gateway if it’s currently linked.