Configuring Flutter CLI

Learn how to configure Flutter CLI to seamlessly work with your private Game Framework registry alongside public packages from pub.dev.

Overview

Flutter's pub tool can be configured to use custom package registries in several ways:

Global Configuration - All packages default to your registry
Per-Package Configuration - Specify registry per package in pubspec.yaml
Environment Variables - Dynamic registry selection
Credentials File - Secure authentication token storage

Method 1: Global Configuration (Recommended for Teams)

Set your private registry as the default for all package operations.

Using PUB_HOSTED_URL

The simplest approach is setting the PUB_HOSTED_URL environment variable:

# Add to your shell profile (~/.bashrc, ~/.zshrc, ~/.bash_profile)
export PUB_HOSTED_URL="https://registry.yourcompany.com"

# Reload your shell
source ~/.zshrc  # or ~/.bashrc

Important: With this configuration, ALL packages default to your private registry. You must explicitly specify hosted for pub.dev packages.

Usage with Mixed Dependencies

When using both private and public packages:

dependencies:
  flutter:
    sdk: flutter
  
  # Private package (uses PUB_HOSTED_URL)
  my_private_package: ^1.0.0
  
  # Public package (explicitly from pub.dev)
  http:
    hosted:
      name: http
      url: https://pub.dev
    version: ^1.1.0

Setting Up Authentication

Create ~/.pub-cache/pub-tokens.json:

{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    },
    {
      "url": "https://pub.dev",
      "token": null
    }
  ]
}

Set your authentication token:

export GF_PUB_TOKEN="your_game_framework_token_here"

Best Practice: Store tokens in environment variables, not directly in files.

Method 2: Per-Package Configuration

Specify the registry for each package individually in pubspec.yaml.

Basic Configuration

name: my_app
description: My Flutter application
version: 1.0.0

environment:
  sdk: '>=3.0.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter
  
  # Private package from Game Framework
  my_auth_package:
    hosted:
      name: my_auth_package
      url: https://registry.yourcompany.com
    version: ^2.1.0
  
  # Another private package
  my_ui_components:
    hosted:
      name: my_ui_components
      url: https://registry.yourcompany.com
    version: ^1.5.0
  
  # Public packages from pub.dev (default)
  http: ^1.1.0
  provider: ^6.1.0

With Authentication

Create ~/.pub-cache/pub-tokens.json:

{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "gf_live_your_token_here"
    }
  ]
}

Advantage: This method gives you fine-grained control and works well for mixed public/private dependencies without environment variables.

Method 3: Environment-Based Configuration

Use environment variables for dynamic registry selection (useful for multi-environment setups).

Setup

# Development environment
export GF_REGISTRY_URL="https://dev-registry.yourcompany.com"
export GF_PUB_TOKEN="dev_token_here"

# Production environment
export GF_REGISTRY_URL="https://registry.yourcompany.com"
export GF_PUB_TOKEN="prod_token_here"

Dynamic pubspec.yaml

While pubspec.yaml doesn't support environment variables directly, you can use build scripts:

# generate_pubspec.sh
#!/bin/bash

cat > pubspec.yaml << EOF
name: my_app
version: 1.0.0

dependencies:
  my_private_package:
    hosted:
      name: my_private_package
      url: ${GF_REGISTRY_URL:-https://registry.yourcompany.com}
    version: ^1.0.0
EOF

Method 4: Credentials File Configuration

For advanced use cases with multiple registries and authentication.

Complete Credentials Setup

Create ~/.pub-cache/credentials.json:

{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "Bearer gf_live_your_token_here",
      "env": "GF_PUB_TOKEN"
    },
    {
      "url": "https://staging-registry.yourcompany.com",
      "token": "Bearer gf_staging_your_token_here",
      "env": "GF_STAGING_TOKEN"
    },
    {
      "url": "https://pub.dev",
      "token": null
    }
  ]
}

Set environment variables:

export GF_PUB_TOKEN="gf_live_your_token_here"
export GF_STAGING_TOKEN="gf_staging_your_token_here"

Authentication Methods

User Tokens

Generated from your Game Framework account:

# Login via API
curl -X POST https://registry.yourcompany.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"your_password"}' \
  | jq -r '.token'

API Keys (Recommended for CI/CD)

Create long-lived API keys for automation:

curl -X POST https://registry.yourcompany.com/v1/workspaces/ws_YOUR_ID/api-keys \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "permissions": ["packages.read", "packages.create"],
    "expires_at": "2026-12-31T23:59:59Z"
  }'

Recommendation: Use user tokens for local development and API keys for CI/CD pipelines.

Team Configuration Best Practices

1. Shared Configuration File

Create a team configuration script:

#!/bin/bash
# setup_registry.sh

REGISTRY_URL="https://registry.yourcompany.com"

# Create pub-tokens.json
mkdir -p ~/.pub-cache
cat > ~/.pub-cache/pub-tokens.json << EOF
{
  "version": 1,
  "hosted": [
    {
      "url": "${REGISTRY_URL}",
      "token": "\${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    }
  ]
}
EOF

# Add to shell profile
if ! grep -q "GF_REGISTRY" ~/.zshrc; then
  echo "export GF_REGISTRY=${REGISTRY_URL}" >> ~/.zshrc
  echo "# Set your token: export GF_PUB_TOKEN=your_token_here" >> ~/.zshrc
fi

echo "✓ Game Framework registry configured!"
echo "⚠️  Remember to set GF_PUB_TOKEN environment variable"

Usage:

chmod +x setup_registry.sh
./setup_registry.sh
export GF_PUB_TOKEN="your_token_here"

2. Project .env File

For team consistency, use a .env file (not committed):

# .env
GF_REGISTRY_URL=https://registry.yourcompany.com
GF_PUB_TOKEN=your_token_here

Load it in your shell:

# Add to your shell startup
if [ -f ".env" ]; then
  export $(cat .env | xargs)
fi

3. VS Code Configuration

Add to .vscode/settings.json:

{
  "dart.flutterSdkPath": "/path/to/flutter",
  "terminal.integrated.env.osx": {
    "PUB_HOSTED_URL": "https://registry.yourcompany.com",
    "GF_PUB_TOKEN": "${env:GF_PUB_TOKEN}"
  },
  "terminal.integrated.env.linux": {
    "PUB_HOSTED_URL": "https://registry.yourcompany.com",
    "GF_PUB_TOKEN": "${env:GF_PUB_TOKEN}"
  },
  "terminal.integrated.env.windows": {
    "PUB_HOSTED_URL": "https://registry.yourcompany.com",
    "GF_PUB_TOKEN": "${env:GF_PUB_TOKEN}"
  }
}

Verification

Test your configuration:

# Check Flutter can reach the registry
flutter pub get

# Verbose output to debug issues
flutter pub get --verbose

# Check specific package
flutter pub outdated

Verify Authentication

# Test with curl
curl -H "Authorization: Bearer $GF_PUB_TOKEN" \
  https://registry.yourcompany.com/v1/packages

Troubleshooting

"Failed to resolve package"

Check registry URL is correct
Verify authentication token
Ensure package exists in workspace

# Test registry connection
curl -I https://registry.yourcompany.com/health

# Test authentication
curl -H "Authorization: Bearer $GF_PUB_TOKEN" \
  https://registry.yourcompany.com/v1/me

"Unauthorized" Error

Token expired or invalid
Token not set in environment
Wrong registry URL

# Check token is set
echo $GF_PUB_TOKEN

# Verify token format
# Should start with: gf_live_ or gf_test_

Mixed Registry Issues

If you have issues with mixed public/private packages:

# Explicit configuration for all dependencies
dependency_overrides:
  my_private_package:
    hosted:
      name: my_private_package
      url: https://registry.yourcompany.com
    version: ^1.0.0

Platform-Specific Configuration

# ~/.zshrc or ~/.bashrc
export PUB_HOSTED_URL="https://registry.yourcompany.com"
export GF_PUB_TOKEN="your_token_here"

# Create pub-tokens.json
mkdir -p ~/.pub-cache
cat > ~/.pub-cache/pub-tokens.json << 'EOF'
{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    }
  ]
}
EOF

# PowerShell Profile
$env:PUB_HOSTED_URL = "https://registry.yourcompany.com"
$env:GF_PUB_TOKEN = "your_token_here"

# Create pub-tokens.json
$pubCache = "$env:APPDATA\Pub\Cache"
New-Item -ItemType Directory -Force -Path $pubCache

@"
{
  "version": 1,
  "hosted": [
    {
      "url": "https://registry.yourcompany.com",
      "token": "`${GF_PUB_TOKEN}",
      "env": "GF_PUB_TOKEN"
    }
  ]
}
"@ | Out-File -FilePath "$pubCache\pub-tokens.json" -Encoding UTF8

FROM cirrusci/flutter:stable

# Set registry
ENV PUB_HOSTED_URL=https://registry.yourcompany.com
ENV GF_PUB_TOKEN=${GF_PUB_TOKEN}

# Create pub-tokens.json
RUN mkdir -p /root/.pub-cache && \
    echo '{"version":1,"hosted":[{"url":"https://registry.yourcompany.com","token":"${GF_PUB_TOKEN}","env":"GF_PUB_TOKEN"}]}' \
    > /root/.pub-cache/pub-tokens.json

WORKDIR /app
COPY pubspec.* ./
RUN flutter pub get

COPY . .
RUN flutter build apk

Next Steps

Publishing Packages - Learn how to publish to your registry
CI/CD Integration - Automate with CI/CD
Pubspec Configuration - Advanced pubspec.yaml options

Need help? Check our troubleshooting guide or contact support.

On this page