npm package: @ludeo/cli
Description: Ludeo CLI - Upload game builds and manage content on the Ludeo platform
Author: Ludeo Team
Latest version: 1.4.17

# 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

```bash
npm install -g @ludeo/cli
```

Verify the installation:
```bash
ludeo version
```

## Quick Start

### Getting Your Game ID and Access Token
Both your **Game ID** and **Access Token** are available in the [Studio Labs](https://studio.ludeo.com) 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:
```bash
ludeo auth set-token --access-token YOUR_ACCESS_TOKEN
```

You can also check if a token is saved:
```bash
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:
```bash
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):
```bash
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](https://studio.ludeo.com) for those**):

#### New Build (Complete build from scratch) - DEFAULT
```bash
# 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)
```bash
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](https://studio.ludeo.com) 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:
```bash
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:

```bash
# 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:

```bash
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
```bash
# 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:
```bash
ludeo config init
```

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

```json
{
  "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:
```bash
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

```bash
npm update -g @ludeo/cli
```

**Windows (standalone exe):** download the latest release from the [GitHub releases](https://github.com/ludeo/cli/releases) page and replace your existing executable.

## CI/CD Integration

### GitHub Actions
```yaml
- 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:
```yaml
- 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:**
```bash
npm rebuild @ludeo/cli
```

**Permission issues (macOS/Linux):**
```bash
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