Getting started

This walkthrough takes you from “no Banto installed” to “a real game running in my browser” in about five minutes. By the end you’ll know the shape of a Banto project and the three CLI commands you’ll use every day.

What you’ll need

• Node.js 18 or newer — node --version should print something like v20.x.x.
• A terminal you’re comfortable with (PowerShell, Bash, zsh — any).
• A code editor. VS Code is what we test against; the project ships a Banto extension that gives you syntax highlighting and inline error messages.

1. Install the CLI

npm install -g @banto/cli

Verify it worked:

banto --help

You should see a list of subcommands (init, build, preview, auth, publish, env).

About the -g flag. Installing globally makes banto available from any directory. If you’d rather not, install it as a dev dependency in your project (npm install --save-dev @banto/cli) and use npx banto … instead.

2. Scaffold a project

Pick a directory you don’t mind creating, then:

banto init my-game
cd my-game

You should now have a folder that looks like this:

my-game/
├── globals.banto         # globals: data sources, custom components, shared state
├── start.banto           # the first state every game enters
├── styles.banto.css      # CSS classes you can reference from your views
├── banto.config.json     # publish settings (title, description, datasets)
├── banto.preview.json    # seed values for `banto preview`
└── .gitignore

That’s a complete “empty lobby” game: the host sees a room code, each player sees a “you’re in” message, and the host can kick players. No real game yet — but enough of a shell to start adding logic to.

Open start.banto and globals.banto in your editor. Don’t worry about every line yet — we’ll come back. Just notice the shape: top-level “blocks” with a name and a { … } body.

3. Preview it

banto preview

The CLI compiles your project, uploads the result to the Banto preview backend, and opens your default browser. You should see the host lobby with a room code. Open the same URL in another tab as a player to try the join flow.

banto preview is the inner-loop command. Whenever you save a .banto file, re-run it to see your changes.

What if it fails? The most common first-run issue is a compile error. The CLI prints the error with the file, line, and a short explanation — fix it and re-run. If the browser doesn’t open at all, see Troubleshooting in the CLI reference.

4. Make your first change

Open start.banto and find the plyr default block. Change the welcome message:

plyr default {
    condition: true,
    child: cpnt.PlayerScreen({
        name: player.name,
        score: player.score,
        roomCode: var.roomCode,
        child: "Welcome — you made it in!"
    })
}

Save, then run banto preview again. The player tab updates with your new copy.

You just learned the core idea of Banto: describe what each viewer should see, declaratively, in .banto files. The runtime takes care of getting it onto their screens.

5. Where to go next

You now know enough to wander.

• The Banto language — read this next. It explains everything you saw in the starter (var, host, plyr, cpnt, the child field) plus the parts you didn’t (state transitions, listeners, actions, custom components).
• Recipes — once you have a feature in mind (“I want a text input”, “I want to advance to the next state when everyone has answered”), check here first.
• CLI reference — keep this handy. It documents every command, including banto auth and banto publish for when you’re ready to put your game on banto.tv.

Two parts of the starter you’ll touch a lot:

• banto.preview.json — seeds the preview with fake players, datasets, etc., so you can test states that aren’t reachable from the starting state. The CLI reference describes the shape.
• banto.config.json — your game’s identity on banto.tv. Title, description, default question/prompt set. Edit this before you banto publish.

Have fun. The DSL is small enough that you’ll have a feel for it within a few hours; ping the team if you get stuck on something the docs didn’t answer.