Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt

Use this file to discover all available pages before exploring further.

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