Ludeo CLI

The official Ludeo CLI tool for uploading game builds to the Ludeo platform. Install via npm for easy setup and automatic updates.

Installation

npm install -g @ludeo/cli

Verify the installation:

ludeo version

Quick Start

Getting Your Game ID and Access Token

Both your Game ID and Access Token are available in the Studio Labs under Environments.

• Access Token: In Environments, click Create Token, name it, then copy and save the token (you won't be able to see it again).
• Game ID: In Environments, it's shown at the top of the page next to the API key.

Windows note: All commands below work in Command Prompt, PowerShell, and terminal emulators. For multi-line commands, replace \ with ^ in Command Prompt.

1. Authentication

Save your access token:

ludeo auth set-token --access-token YOUR_ACCESS_TOKEN

You can also check if a token is saved:

ludeo auth status

2. Upload Your Build

Interactive Mode (Recommended for First-Time Users)

Simply run the upload command without flags to start the interactive wizard:

ludeo builds upload

The interactive mode will guide you through:

1. Game ID - Enter your game's unique identifier
2. Build Creation Type - Choose between new or sdkFree
3. Build Type - Select major or minor (with warning for major builds)
4. Major Version Selection - If creating a minor build, select from existing major versions
5. Game Version - Enter the version number (e.g., 1.2.3)
6. SDK Version - Enter the Ludeo SDK version (not required for sdkFree)
7. Executable Path - Path to your game executable relative to build directory
8. Local Directory - Path to your build files
9. Changes Description - Optional description of what changed

Before uploading, you'll see a summary of all options and the equivalent CLI command for future use in scripts or CI/CD pipelines.

To disable interactive mode (for CI/CD or scripts):

ludeo builds upload --no-interactive [flags...]

Command-Line Mode

Upload your game build with a simple command. The CLI supports two build creation types (modification builds are not supported from the CLI—use Studio Labs for those):

New Build (Complete build from scratch) - DEFAULT

# With explicit build-creation-type
ludeo builds upload \
  --game-id YOUR_GAME_ID \
  --exec-path game.exe \
  --local-directory ./builds \
  --build-creation-type new \
  --build-type major \
  --game-version "1.2.3" \
  --sdk-version "2.0.0" \
  --changes-description "Bug fixes and performance improvements"

# Or simply omit --build-creation-type (defaults to "new")
ludeo builds upload \
  --game-id YOUR_GAME_ID \
  --exec-path game.exe \
  --local-directory ./builds \
  --build-type major \
  --game-version "1.2.3" \
  --sdk-version "2.0.0"

SDK Free Build (Performance testing without Ludeo SDK)

ludeo builds upload \
  --game-id YOUR_GAME_ID \
  --exec-path game.exe \
  --local-directory ./builds \
  --build-creation-type sdkFree \
  --build-type major \
  --game-version "1.2.3" \
  --changes-description "Performance testing build"

3. Build Types and Requirements

Build Creation Types (CLI):

• new: Complete build from scratch (requires game-version, sdk-version, build-type) [DEFAULT]
• sdkFree: Performance testing without Ludeo SDK (requires game-version, build-type; sdk-version not required)

Note: Modification builds (builds based on an existing build) are not supported from the CLI. Create modification builds from Studio Labs only.

Build Types:

• major: Major version build
• minor: Minor version build (requires major-build-id)

Additional Flags:

• --request-id: Optional request ID for tracking
• --no-interactive: Disable interactive prompts (for CI/CD or scripts)
• --dry-run: Preview the upload without making any changes
• --poll: After upload completes, poll build status until it leaves pending state
• --interval N: Polling interval in seconds when using --poll (default: 10)
• --skip-file-registration: Skip registering individual build files; only the executable is registered

Dry-Run Mode

Preview what would be uploaded without making any changes:

ludeo builds upload --dry-run \
  --game-id YOUR_GAME_ID \
  --exec-path game.exe \
  --local-directory ./builds \
  --build-type major \
  --game-version "1.2.3" \
  --sdk-version "2.0.0"

Dry-run will:

• Validate all parameters and directory structure
• Scan and display all files that would be uploaded
• Show total file count and size
• NOT create any build metadata or upload files

4. Check Build Status

After uploading you can check whether the platform has finished processing a build:

# Single check — prints current status and exits
ludeo builds status --game-id YOUR_GAME_ID --build-id BUILD_ID

# Poll until the build leaves the pending state (useful in CI/CD)
ludeo builds status --game-id YOUR_GAME_ID --build-id BUILD_ID --poll

# Poll with a custom interval (default is 10 s)
ludeo builds status --game-id YOUR_GAME_ID --build-id BUILD_ID --poll --interval 5

--poll continues while the status is pending and exits as soon as it changes:

• Exit 0 — status is ready, success, or complete
• Exit 1 — any other status (e.g. failed)

You can also trigger polling automatically right after an upload:

ludeo builds upload \
  --game-id YOUR_GAME_ID \
  --exec-path game.exe \
  --local-directory ./builds \
  --build-type major \
  --game-version "1.2.3" \
  --sdk-version "2.0.0" \
  --poll

5. Manage Builds

# List your builds
ludeo builds list --game-id YOUR_GAME_ID

# List builds with detailed info (versions, SDK, environment, changes)
ludeo builds list --game-id YOUR_GAME_ID --verbose

# Get build details
ludeo builds get --game-id YOUR_GAME_ID --build-id BUILD_ID

# Check if token is saved
ludeo auth status

# Remove saved token when done
ludeo auth logout

Project Config (ludeo.json)

To avoid repeating the same flags on every command, you can store per-project defaults in a ludeo.json file in your project directory (or any ancestor directory up to $HOME).

Scaffold a template:

ludeo config init

This creates a ludeo.json with all supported fields. Fill in the values you want to persist:

{
  "game_id": "YOUR_GAME_ID",
  "exec_path": "game.exe",
  "local_directory": "./builds",
  "build_type": "major",
  "sdk_version": "2.0.0",
  "skip_file_registration": false
}

Once the file is in place, you can upload with just:

ludeo builds upload --game-version "1.2.3"

Flag values always override the project config, which overrides global defaults.

Features

• Interactive Mode: Guided wizard for easy build uploads - just run ludeo builds upload and follow the prompts
• Easy Upload: Upload complete game builds with a single command
• Build Status Polling: Check and poll build processing status with builds status --poll; also available directly on builds upload --poll
• Project Config: Store per-project defaults in ludeo.json via ludeo config init — no more repeating the same flags
• Large File Support: Automatically handles large files and multiple files
• Progress Tracking: Real-time progress updates during uploads
• Dry-Run Mode: Preview uploads without making changes using --dry-run
• Cross-Platform: Works on Windows, macOS, and Linux
• Automatic Updates: Keep your CLI up to date with npm

Updating

npm update -g @ludeo/cli

Windows (standalone exe): download the latest release from the GitHub releases page and replace your existing executable.

CI/CD Integration

GitHub Actions

- name: Install Ludeo CLI
  run: npm install -g @ludeo/cli

- name: Upload Build and Wait for Processing
  run: |
    ludeo auth set-token --access-token ${{ secrets.LUDEO_ACCESS_TOKEN }}
    ludeo builds upload \
      --game-id ${{ env.GAME_ID }} \
      --exec-path game.exe \
      --local-directory ./builds \
      --build-creation-type new \
      --build-type major \
      --game-version ${{ env.GAME_VERSION }} \
      --sdk-version ${{ env.SDK_VERSION }} \
      --poll

If you prefer to separate the upload and status-check steps:

- name: Upload Build
  id: upload
  run: |
    ludeo auth set-token --access-token ${{ secrets.LUDEO_ACCESS_TOKEN }}
    ludeo builds upload \
      --game-id ${{ env.GAME_ID }} \
      --exec-path game.exe \
      --local-directory ./builds \
      --build-type major \
      --game-version ${{ env.GAME_VERSION }} \
      --sdk-version ${{ env.SDK_VERSION }}

- name: Wait for Build to Be Ready
  run: |
    ludeo builds status \
      --game-id ${{ env.GAME_ID }} \
      --build-id ${{ env.BUILD_ID }} \
      --poll --interval 15

Troubleshooting

Installation Issues

Binary not found error:

npm rebuild @ludeo/cli

Permission issues (macOS/Linux):

sudo npm install -g @ludeo/cli

Windows (npm):

• Run PowerShell as Administrator
• Ensure Node.js is properly installed

Windows (standalone exe):

• "ludeo is not recognized" — Add the folder containing ludeo.exe to your PATH.
• "Access denied" / "Permission denied" — Right-click the executable → Properties → Unblock → OK, or run Command Prompt as Administrator.
• Antivirus blocking — Add an exception for the executable in your antivirus software.

Common Issues

Authentication errors:

• Verify your access token is valid
• Check if token is saved with ludeo auth status
• Make sure you've saved your token with ludeo auth set-token

Upload failures:

• Ensure your build directory exists and is readable
• Check your internet connection
• Verify file paths are correct

Large files:

• Large files may take time to upload
• Ensure stable internet connection

Support

Need help? Here's how to get support:

1. Check this README and troubleshooting section
2. npm: run npm rebuild @ludeo/cli if you encounter issues. Windows (standalone): ensure ludeo.exe is in your PATH and see the troubleshooting section above.
3. Contact the Ludeo platform team for additional assistance