# Vibeforge CLI

A comprehensive command-line tool for developing and publishing HTML5 games to the Venus platform.

## What You Need

- **Node.js 18 or newer** - Download from [nodejs.org](https://nodejs.org)
- A computer running Windows, Mac, or Linux

## Installation

### Install from npm (Recommended)

```bash
npm install -g @series-inc/vibeforge-cli
```

That's it! The CLI will be available globally as `vf` or `vibeforge`.

### Alternative: Use without installing

You can also run the CLI without installing it globally using npx:

```bash
npx @series-inc/vibeforge-cli help
```

## Docs

Docs are built-in to the commands. For example, running `vf`, `vf --help` or `vf -h` will print out the basic details on vf.

If you want the docs for a specific command `vf [command] --help` or `vf [command] -h` will print out the docs associated with that command.

## Using the CLI

Once installed, you can use these commands:

### Authentication Commands

```bash
vf login          # Authenticate via Firebase OAuth (opens browser)
vf logout         # Clear authentication session
vf whoami         # Display current user session information
```

### Game Development

```bash
vf init           # Initialize existing HTML5 game with Venus SDK and Vibeforge configuration
```

### Game Publishing

```bash
vf upload --name "Game Name" --description "Description" [options]
                  # Upload a new game to the Vibeforge platform
vf update <patch|minor|major> [--changelog "Release notes"]
                  # Update an existing game with a new version
vf publish [--version-tag <version>]
                  # Publish a game instance to Venus platform (visible in Explore tab)
```

### Game Management

```bash
vf status         # Show comprehensive game project information (local config + remote data)
```

### Utility Commands

```bash
vf upgrade [--check-only]
                  # Upgrade Vibeforge CLI to latest version
vf --version      # Show current version and check for updates
vf help           # Display comprehensive usage information
```

### Developer Commands

```bash
vf env            # Manage API environment configurations (for development/testing)
vf env set <name> # Set active environment
vf env add <name> --url <url> --api-key <key>
                  # Add custom environment
vf env list       # List all configured environments
```

## Command Details

### Upload Command

Upload a new game to the platform:

```bash
vf upload --name "My Game" --description "A fun HTML5 game"
vf upload --name "Space Adventure" --description "Epic space game" --category "action" --tags "space,adventure,arcade"
```

**Required Options:**

- `--name "Game Name"` - Display name for the game
- `--description "Description"` - Game description

**Optional Options:**

- `--category "category"` - Game category (defaults to 'arcade')
- `--tags "tag1,tag2,tag3"` - Comma-separated tags

### Update Command

Update an existing game with a new version:

```bash
vf update patch --changelog "Fixed collision detection bug"
vf update minor --changelog "Added new power-ups and levels"
vf update major --changelog "Complete gameplay overhaul"
```

**Version Types:**

- `patch` - Bug fixes (1.0.0 → 1.0.1)
- `minor` - New features (1.0.0 → 1.1.0)
- `major` - Breaking changes (1.0.0 → 2.0.0)

### Publish Command

Publish your game to make it visible in the Venus Explore tab:

```bash
vf publish                    # Publish latest version
vf publish --version-tag 1.2.0  # Publish specific version
```

### Important Build Requirements

Vibeforge automatically handles your build process:

1. **Existing Build Directory**: Looks for `/dist`, `/build`, or `/output` directories first
2. **Package.json Build Script**: If no build directory exists, runs `npm run build`
3. **Upload Built Files Only**: Never uploads development files like `src/`, `node_modules/`

**Always run upload/update commands from your project root directory, not from build directories.**

## Prerequisites for Commands

### Authentication Required

Most commands require authentication. Run `vf login` first:

- `vf upload` - Upload new games
- `vf update` - Update existing games  
- `vf publish` - Publish games to Venus
- `vf status` - Check game status
- `vf init` - Initialize projects

### Project Directory Requirements

- `vf upload` and `vf update` - Run from project root directory (not build directory)
- `vf status` - Run from directory containing `.vibeforge` configuration file
- `vf publish` - Run from directory containing `.vibeforge` configuration file

## Updating

Use the built-in upgrade command (recommended):

```bash
vf upgrade              # Upgrade to latest version
vf upgrade --check-only # Check for updates without installing
```

Or update manually via npm:

```bash
npm update -g @series-inc/vibeforge-cli
```

## Uninstalling

To remove the Vibeforge CLI:

```bash
npm uninstall -g @series-inc/vibeforge-cli
```

Note: This will remove the CLI but preserve your login data and game configurations.

## Troubleshooting

### "Command not found" Error

If `vf` command doesn't work after installation:

- Make sure the installation completed successfully
- Restart your terminal/command prompt
- Check that Node.js is properly installed: `node --version`
- Verify the package is installed: `npm list -g @series-inc/vibeforge-cli`

### Permission Issues

If you get permission errors during installation:

- On macOS/Linux: Use `sudo npm install -g @series-inc/vibeforge-cli`
- Or use a Node version manager like [nvm](https://github.com/nvm-sh/nvm) (recommended)

### Build Issues

If upload/update commands fail:

- Ensure you're in the project root directory (not in `/dist`, `/build`, etc.)
- Check that you have a build directory (`/dist`, `/build`, `/output`) or `package.json` with build script
- Verify build directory doesn't contain development files (`src/`, `node_modules/`)

### Authentication Issues

If you get authentication errors:

- Run `vf whoami` to check login status
- Run `vf login` to re-authenticate
- Ensure you're using an interactive terminal (not through Cursor/IDE)