Commands

Reference for the workflow commands you'll run day-to-day. Setup commands — wavedash auth * and wavedash update — live with Authentication and Installation.

Initialize a project

wavedash init

Interactively scaffolds a wavedash.toml in the current directory. Detects Godot or Unity from the project files (otherwise treats the folder as a custom web build), prompts you to pick or create a team and a project, and writes the matching config. If a wavedash.toml already exists, you'll be asked whether to reinitialize.

Requires authentication — run wavedash auth login first.

Teams and projects

Most users set up their team and project interactively via wavedash init. These scripted commands are useful for CI or when you already know the IDs you want to pass around.

wavedash team create --name "My Studio"

Creates a new team and prints the team ID plus its Developer Portal URL.

wavedash team list

Lists every team you belong to. Prints a table with ID, Slug, and Name columns. Pass --json to get a JSON array instead — easier to pipe into other tools.

wavedash project create --title "My Game" --team-id <TEAM_ID>

Creates a new project under the given team and prints the project ID plus its Developer Portal URL. The project ID is what you put in wavedash.toml as game_id.

wavedash project list --team-id <TEAM_ID>

Lists every project (game) owned by the team. Prints a table with ID, Slug, and Title columns. Pass --json to get a JSON array instead.

Local development

wavedash dev

Launches the Wavedash Dev app, which runs your game inside the Wavedash sandbox so you can test the SDK, achievements, and other platform features before pushing a build. The CLI reads upload_dir from wavedash.toml, registers a temporary local build with the API, and opens the sandbox pointed at it. The first run downloads the dev app; subsequent runs reuse it.

The sandbox validates your SDK wiring locally. It does not replace a final smoke test of the uploaded build on Wavedash.

Stuck seeing old assets?

If the dev app keeps showing an old version of your game after you rebuild, hit Cmd+Shift+R (Force Reload) to reload without the cache. You can also open DevTools, go to the Network tab, and check Disable cache — that bypasses the cache for as long as DevTools is open.

Build and push

wavedash build push

Uploads everything under upload_dir and registers a new immutable build for the configured game_id. Old builds stay available for rollback.

Uploading does not publish the build — there is currently no CLI publish command. After the upload finishes, open the Developer Portal and promote the build when you're ready to make it live.

Stats

Stats are per-game counters that the SDK reports. They power stat-triggered achievements and surface as user progress on the Wavedash side.

Every stat command accepts --game-id <GAME_ID> to target a game explicitly. When omitted, the CLI reads game_id from the wavedash.toml at --config (default ./wavedash.toml). If you aren't running from a project directory, find the ID with wavedash project list --team-id <TEAM_ID> and pass --game-id directly.

wavedash stat create --identifier KILLS_TOTAL --name "Total Kills"

Creates a stat. --identifier is the stable string you reference from your game code; --name is the human-readable display name shown in the Developer Portal.

wavedash stat update --id <STAT_ID> --identifier KILLS_TOTAL --name "New Display Name"

Updates a stat's identifier and display name. Both --identifier and --name are required — the command rewrites both fields. <STAT_ID> is the document ID returned from stat create.

wavedash stat delete --id <STAT_ID> [--force]

Deletes a stat. If any user progress is attached to the stat, the command refuses to delete unless --force is passed.

Achievements

Achievements unlock either when your game calls the SDK directly (standard) or automatically when a stat crosses a threshold (stat-triggered).

Every achievement command accepts --game-id <GAME_ID> to target a game explicitly. When omitted, the CLI reads game_id from the wavedash.toml at --config (default ./wavedash.toml).

wavedash achievement create \
  --identifier FIRST_WIN \
  --title "First Win" \
  --description "Win your first match."

Creates a standard achievement. Add --triggered-by-stat-id <STAT_ID> --threshold <N> to make it stat-triggered, --secret to hide it until unlocked, and --image <PATH> to attach an icon (jpg, jpeg, png, or webp).

wavedash achievement update --id <ACHIEVEMENT_ID> [flags]

Updates only the fields you pass. Pass --triggered-by-stat-id "" (empty string) to clear an existing stat trigger and turn the achievement back into a standard one.

wavedash achievement delete --id <ACHIEVEMENT_ID> [--force]

Deletes an achievement. If any user has unlocked it, the command refuses to delete unless --force is passed.

Global options

These flags apply to every subcommand: