Skip to main content
Manage authentication for the HopX CLI using the auth command. Authenticate via OAuth, manage API keys, and verify authentication status.

​
Command Syntax

hopx auth <subcommand> [options]

​
Subcommands

​
login

Authenticate with HopX via browser OAuth. Syntax: 
hopx auth login [OPTIONS]
Options:
  • --provider TEXT - OAuth provider: GoogleOAuth, GitHubOAuth (default: GoogleOAuth)
  • --no-browser - Headless mode: manually paste callback URL (for servers without browsers)
Examples: 
# OAuth login with Google (default)
hopx auth login

# OAuth login with GitHub
hopx auth login --provider GitHubOAuth

# Headless mode (for servers/containers without browsers)
hopx auth login --no-browser
Expected Output: 
✓ Authentication successful
✓ You can now create API keys with 'hopx auth keys create'
Exit Codes:
  • 0 - Success
  • 1 - Authentication failed
  • 5 - Timeout

​
logout

Log out and clear stored credentials. Syntax: 
hopx auth logout [OPTIONS]
Examples: 
# Log out
hopx auth logout
Expected Output: 
✓ Logged out successfully
Exit Codes:
  • 0 - Success

​
status

Check authentication status. Syntax: 
hopx auth status [OPTIONS]
Examples: 
# Check authentication status
hopx auth status
Expected Output: 
✓ Authenticated
✓ API key: hopx_live_... (configured)
Exit Codes:
  • 0 - Authenticated
  • 3 - Not authenticated

​
validate

Validate current API key. Syntax: 
hopx auth validate [OPTIONS]
Examples: 
# Validate API key
hopx auth validate
Expected Output: 
✓ API key is valid
Exit Codes:
  • 0 - Valid
  • 3 - Invalid or missing

​
refresh

Refresh OAuth token. Syntax: 
hopx auth refresh [OPTIONS]
Examples: 
# Refresh OAuth token
hopx auth refresh
Expected Output: 
✓ Token refreshed successfully
Exit Codes:
  • 0 - Success
  • 3 - Authentication error

​
keys

Manage API keys.

​
keys list

List all API keys. Syntax: 
hopx auth keys list [OPTIONS]
Examples: 
# List API keys
hopx auth keys list
Expected Output: 
┌──────────────┬─────────────────────┬──────────────┐
│ Name         │ Created             │ Last Used    │
├──────────────┼─────────────────────┼──────────────┤
│ my-key       │ 2025-01-27 10:00:00 │ 2025-01-27   │
│ production   │ 2025-01-26 09:00:00 │ 2025-01-27   │
└──────────────┴─────────────────────┴──────────────┘

​
keys create

Create a new API key. Syntax: 
hopx auth keys create [OPTIONS]
Options:
  • --name TEXT - API key name (auto-generated if not provided)
Examples: 
# Create API key with name
hopx auth keys create --name "my-key"

# Create with auto-generated name
hopx auth keys create
Expected Output: 
✓ API key created: hopx_live_...
✓ Key stored securely
Exit Codes:
  • 0 - Success
  • 3 - Authentication error

​
keys revoke

Revoke an API key. Syntax: 
hopx auth keys revoke KEY_ID [OPTIONS]
Arguments:
  • KEY_ID - API key ID to revoke (required)
Examples: 
# Revoke API key
hopx auth keys revoke key_abc123
Expected Output: 
✓ API key revoked: key_abc123
Exit Codes:
  • 0 - Success
  • 3 - Authentication error
  • 4 - Key not found

​
keys info

Get information about an API key. Syntax: 
hopx auth keys info KEY_ID [OPTIONS]
Arguments:
  • KEY_ID - API key ID (required)
Examples: 
# Get API key info
hopx auth keys info key_abc123
Expected Output: 
┌─────────────┬─────────────────────────────────────┐
│ Property    │ Value                               │
├─────────────┼─────────────────────────────────────┤
│ Name        │ my-key                               │
│ Created     │ 2025-01-27 10:00:00                 │
│ Last Used   │ 2025-01-27 12:00:00                 │
└─────────────┴─────────────────────────────────────┘

​
Authentication Methods

# Login with browser
hopx auth login

# Create API key
hopx auth keys create --name "my-key"

​
Method 2: Environment Variable

# Set API key
export HOPX_API_KEY="hopx_live_..."

# Verify
hopx auth status

​
Method 3: Config File

API keys are automatically stored in ~/.hopx/credentials.yaml after creation.

​
Shell Scripting Examples

​
Check Authentication Before Running Commands

#!/bin/bash

# Check authentication
if ! hopx auth status > /dev/null 2>&1; then
    echo "Not authenticated. Please run 'hopx auth login'"
    exit 1
fi

# Proceed with commands
hopx sandbox create --template python

​
Create and Use API Key

#!/bin/bash

# Create API key
KEY_NAME="ci-$(date +%s)"
hopx auth keys create --name "$KEY_NAME"

# Use in script
export HOPX_API_KEY=$(hopx auth keys info "$KEY_NAME" --output json | jq -r '.key')

​
Next Steps