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 (otherwise the interactive device flow is used)

This is the only flag. Connection settings (API/OIDC URL, client id, scopes) are baked into the binary at build time and are not configurable at runtime.

Examples

Interactive Login

# Standard interactive login (device flow)
game login

API Key Login

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

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

# Provide credentials via the environment for CI / non-interactive use.
# Authenticated commands (publish, workspace, whoami, …) read these directly —
# no `game login` step is required.
export GAME_API_KEY=gf_1234567890abcdef
# ...or a bearer token:
export GAME_TOKEN=eyJhbGciOi...

Connection settings (API/OIDC URL, client id, scopes) are baked in at build time and cannot be set via environment variables.

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: The access token and its expiry are saved locally

Benefits:

• Secure authentication without exposing credentials in the terminal
• Works on headless servers (shows URL to visit)
• An expired token simply prompts you to log in again (there is no refresh token)

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:
  workspace_id: "ws-abc123"

Configuration Priority

The CLI resolves authentication credentials in this order (highest to lowest):

1. CLI flag - --api-key
2. Environment variables - GAME_API_KEY, then GAME_TOKEN
3. Config file - ~/.game/config.yml

Connection settings (API/OIDC URL, client id, scopes) are not part of this chain — they are embedded in the binary at build time. 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:

• Check your internet connection
• Ensure the Game Framework backend is reachable
• If it persists, the binary may have been built against the wrong API URL (the URL is baked in at build time)

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