game login

Authenticate with Game Framework Cloud to enable publishing packages and managing workspaces.

Usage

game login [options]

Authentication Methods

1. Interactive Login (Recommended)

Use OIDC device flow for secure authentication:

game login

This will:

1. Request a device code from the authentication server
2. Display a verification URL and user code
3. Open your browser to complete authentication
4. Poll for token until authorization is complete
5. Save the access token locally

Example output:

🌐 Initiating device authorization...

Please complete authorization in your browser:
  1. Visit: http://localhost:4000/device
  2. Enter code: WDJB-MJHT

⏳ Waiting for authorization...
✓ Authorization successful!

2. API Key Login

Use an API key for CI/CD pipelines or non-interactive environments:

game login --api-key YOUR_API_KEY

Generate an API key:

1. Log in to Game Framework Cloud
2. Navigate to Workspace Settings → API Keys
3. Click "Create API Key"
4. Copy the key (it's shown only once!)

3. Environment Variable

Set the API key as an environment variable:

export GAME_API_KEY=gf_1234567890abcdef
game login

Options

• --api-key <key> - Authenticate with an API key
• --api-url <url> - Custom API URL (default: http://localhost:4000)
• --oidc-url <url> - Custom OIDC provider URL
• --client-id <id> - OAuth client ID (default: game-cli)
• --scopes <scopes> - OAuth scopes (default: "openid profile email")

Examples

Interactive Login

# Standard interactive login
game login

# Login with custom API URL
game login --api-url https://api.gameframework.com

API Key Login

# Login with API key
game login --api-key gf_1234567890abcdef

# Login with API key and custom URL
game login --api-key gf_1234567890abcdef --api-url https://api.gameframework.com

CI/CD Usage

For automated environments like GitHub Actions:

# .github/workflows/publish.yml
- name: Login to Game Framework
  run: game login --api-key ${{ secrets.GAME_API_KEY }}

Environment Variables

# Set API key
export GAME_API_KEY=gf_1234567890abcdef

# Set custom API URL
export GAME_API_URL=https://api.gameframework.com

# Login (uses environment variables)
game login

OIDC Device Flow

The interactive login uses OAuth 2.0 Device Authorization Grant (RFC 8628):

1. Initiate Flow: CLI requests a device code and user code
2. Display Code: CLI shows verification URL and user code
3. Authorize: You open the URL in a browser and enter the code
4. Poll for Token: CLI polls the token endpoint until authorized
5. Save Token: Access token and refresh token are saved locally

Benefits:

• Secure authentication without exposing credentials in the terminal
• Works on headless servers (shows URL to visit)
• Supports token refresh for long-lived sessions

Configuration Storage

Authentication credentials are stored in ~/.game/config.yml:

auth:
  token: "eyJhbGciOiJSUzI1NiIs..."
  expires_at: "2026-01-30T12:00:00Z"
  api_key: "gf_1234567890abcdef"

defaults:
  api_url: "http://localhost:4000"
  oidc_url: "http://localhost:4000"

Configuration Priority

The CLI checks configuration in this order (highest to lowest priority):

1. CLI flags - --api-key, --api-url, --oidc-url
2. System environment variables - GAME_API_KEY, GAME_API_URL, etc.
3. .env file - Variables in .env file in the CLI directory
4. Config file - ~/.game/config.yml
5. Defaults - http://localhost:4000, game-cli, etc.

Token Expiration

Bearer tokens obtained via OIDC have an expiration time. If your token expires:

# Re-authenticate
game login

The CLI will automatically detect expired tokens and prompt you to login again.

Logout

To clear stored credentials:

game logout

This removes the authentication data from ~/.game/config.yml.

Troubleshooting

Invalid Credentials

Error: Invalid API key or Authentication failed

Solutions:

• Verify your API key is correct
• Check the API key hasn't been revoked
• Ensure the API key has necessary permissions
• Generate a new API key if needed

Token Expired

Error: Token expired

Solution: Run game login again to refresh the token.

Connection Refused

Error: Connection refused or Failed to connect to API

Solutions:

• Verify the API URL is correct
• Check your internet connection
• Ensure the Game Framework backend is running
• Try with a custom URL: game login --api-url https://api.gameframework.com

OIDC Configuration Error

Error: Failed to discover OIDC endpoints

Solutions:

• Verify the OIDC URL is correct
• Check the OIDC provider is running
• Try specifying endpoints manually with flags

Security Best Practices

1. Use API Keys for CI/CD - More secure than embedding tokens
2. Rotate Keys Regularly - Generate new API keys periodically
3. Separate Keys per Environment - Use different keys for dev/staging/production
4. Never Commit Credentials - Add .game/ to .gitignore
5. Use Environment Variables - In CI/CD, use secrets management

Related Commands

• game logout - Clear stored credentials
• game workspace - Manage workspaces
• game publish - Publish packages (requires login)

Next Steps

After logging in:

1. Select a workspace with game workspace select
2. View current workspace with game workspace current
3. Publish a package with game publish