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
• A computer running Windows, Mac, or Linux

Installation

Install from npm (Recommended)

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:

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

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

Game Development

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

Game Publishing

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

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

Utility Commands

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

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:

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:

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:

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):

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

Or update manually via npm:

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

Uninstalling

To remove the Vibeforge CLI:

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 (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)