Publishing a Package

This guide walks you through publishing a Flutter game package to Game Framework Cloud from start to finish: authenticating, selecting a workspace, validating, and shipping your first version.

For the full option reference, see the game publish command page. This page is the guided, end-to-end flow.

game pub is an alias for game publish, game ws for game workspace, and game ws select accepts game ws use. Use whichever you prefer.

Prerequisites

game-cli installed
A Flutter package directory containing a valid pubspec.yaml
An account on Game Framework Cloud with access to at least one workspace

Authenticate

Run the login command from anywhere:

game login

You'll be asked how to authenticate:

Interactive Login (Device Flow) — the CLI prints a URL; open it in your browser and approve the request. The CLI polls until you confirm, then stores your token in ~/.game/config.yml.
API Key — paste a key (input is hidden). Best for CI; you can also pass it directly with game login --api-key <key>.

Confirm you're signed in:

game whoami

This prints your name, email, and current workspace.

Tokens are cached in ~/.game/config.yml. The CLI resolves credentials in this order: CLI flag → GAME_API_KEY / GAME_TOKEN environment variable → config file. An expired token is skipped automatically and you'll be prompted to log in again.

Select a workspace

List the workspaces you can publish to:

game ws ls

Then select one by its slug (the current one is marked with *):

game ws select <slug>

Verify your selection and check its plan limits (packages, storage, downloads):

game ws current

The selected workspace is saved to ~/.game/config.yml, so you only need to do this once per machine. You can still override it per-publish with game publish --workspace <id>.

Prepare your package

game publish runs from inside your package directory and requires a valid pubspec.yaml:

pubspec.yaml

name: my_game_package
version: 1.0.0
description: My awesome game package

dependencies:
  flutter:
    sdk: flutter
  gameframework: ^0.0.3
  gameframework_unity: ^0.0.3

To also upload engine artifacts (Unity/Unreal builds), add a .game.yml:

.game.yml

publish:
  # Optional — falls back to your selected workspace
  workspace_id: "ws_..."
  private: false
  exclude:
    - "*.log"
    - "build/"
    - ".dart_tool/"

engines:
  unity:
    project_path: ./unity_project
    export_path: ./unity_project/Exports
    platforms:
      android:
        enabled: true
      ios:
        enabled: true

Versions are immutable. The version in pubspec.yaml must not already exist for this package — bump it (following semantic versioning) for every publish.

Validate with a dry run

Always dry-run first. This exercises everything except the actual upload — nothing is written to the cloud:

game publish --dry-run --verbose

It validates:

Your pubspec.yaml (name + version)
Authentication and workspace access
That the version doesn't already exist
That the package archive builds correctly

--verbose (-v) logs each request and the resolved workspace, which is helpful for confirming you're pointed at the right place before going live.

Publish

When the dry run is clean, publish for real:

# Publish the package and any configured artifacts
game publish

# Publish the package only (skip Unity/Unreal artifact uploads)
game publish --skip-artifacts

# Publish artifacts for specific platforms only
game publish --platform android --platform ios

Under the hood the CLI:

Creates the package in your workspace if it doesn't exist yet.
Builds a .tar.gz archive of your package (README, CHANGELOG, LICENSE, and .game.yml are sent as metadata so the server never unpacks the archive).
Uploads and finalizes the version.
Uploads engine artifacts for each enabled platform (unless --skip-artifacts).

With --auto-export (on by default), a missing artifact triggers an export before upload. Pass --auto-export=false to skip that, or --force-rebuild to ignore the cached archive and rebuild it.

Verify

On success the CLI prints a link to your published package. Confirm it in the web dashboard, then test installing it from another project. To publish an update, bump the version in pubspec.yaml and run game publish again.

Quick reference

game login                       # authenticate (device flow or --api-key)
game whoami                      # confirm identity + current workspace
game ws ls                       # list workspaces
game ws select <slug>            # choose a workspace
cd my_package
game publish --dry-run --verbose # validate without uploading
game publish --skip-artifacts    # publish package only
game publish                     # publish package + artifacts

Troubleshooting

Error	Fix
`Authentication required`	Run `game login`.
`No workspace selected`	Run `game ws ls` then `game ws select <slug>`, or pass `--workspace <id>`.
`Version 1.0.0 already exists`	Bump the version in `pubspec.yaml`.
`pubspec.yaml not found`	Run the command from your package's root directory.

For more, see the game publish reference and the common errors guide.

On this page