Getting started with the CLI
KUMODeck is a flat backend for vibe coding — web apps, games and more: hosting, your own server code and database, user logins, cloud saves, multiplayer rooms — behind one SDK and one CLI, and all of it can be set up by your AI agent. This page walks through one example, a small game from a starter template (the steps are the same for a web app), from nothing to a deployed game that remembers each player's best score, shared on X — every step is one command in your terminal.
Tip New here, or not using a terminal? Start here shows only the steps for where you use AI (an AI that runs commands, or Claude, ChatGPT and Muse).
kumodeck signup2Add creditkumodeck billing topup3Createkumodeck create · init4Ruleskumodeck config push5Call the SDKKumo.init()6Deploykumodeck deploy7Share on Xkumodeck share on1. Install the CLI and create your account#
# or run any command without installing: npx kumodeck <command>
npm install -g kumodeck
# email + password (add --invite <code> if you have one); you are signed in right away
kumodeck signupThe CLI has zero dependencies and needs Node 22 or newer. signup creates your developer account and signs you in.
Anyone can sign up. An invite code is optional (--invite <code>, or the invite code box on the dashboard's
sign-up page, also when you sign up with Google or GitHub): it adds credit to your balance. Without one,
your balance starts at $0, and once your email is confirmed you can create and publish on the free usage
(codes later too: Billing on the dashboard, or kumodeck billing redeem <code>).
Confirm your email next: paste the link from the confirmation email into kumodeck verify <link> (no email?
kumodeck verify --resend). Adding prepaid credit, secret keys and AI agent (MCP) connections wait for it. Already have an account? kumodeck login. Your session is stored in
~/.kumo/credentials.json (file mode 0600). Point the CLI at a different server with --api <url> or KUMO_API_URL.
Tip Using an AI agent such as Claude Code, Codex or Cursor? Type
kumodeck signupyourself (the password never goes through the assistant), then ask the assistant to do everything below. For the deposit, the assistant runskumodeck billing topupand shows you the payment URL; you pay on that page. Each command prints the next command to run. See Use from an AI agent.
Tip Running the server yourself?
pnpm install && pnpm devin the repository starts everything onhttp://localhost:4000with an embedded Postgres — no Docker. Every step on this page works against it.
2. Add prepaid credit (when you need it)#
# default $5; prints a Stripe payment page, opens it, and waits until you have paid
kumodeck billing topup
# Added $5.00 to your prepaid balance; your card was charged $5.34 (card fee $0.34)You can start for free: static sites and games are free to publish (up to 10 million file requests and 1 GB stored a
month), and the rest of what your project uses (API requests, saves, multiplayer, card images, Functions) gets $2 of free usage each month.
Anything past the free usage is taken at cost from a prepaid balance, like an AI provider's API credits. Add funds
when you need them — $5 lasts a small app or game a long time (see the examples).
You pay on Stripe's page yourself; the CLI never sees your card. kumodeck billing shows the balance any time, and the
dashboard (Money → Prepaid) does the same with automatic top-up and a low-balance email.
While the balance is $0 or less and nothing else covers it (the month's free usage, or an automatic top-up that has not
failed), the user-facing side of your projects pauses (your users see a neutral message; static sites and games stay up) and,
while you owe usage, new projects and deploys are refused with 402 — the error prints kumodeck billing topup. Without funds,
the free usage comes back on the 1st of next month. kumodeck billing and kumodeck whoami say plainly whether you are
paused. Your dashboard, config pushes and top-ups keep working, and everything resumes on its own as soon as funds arrive.
Details: Prepaid balance.
3. Create a project from a template#
# a playable game (template: vanilla-canvas)
kumodeck create my-game && cd my-game
# creates the project and writes your keys into public/kumo-config.js
kumodeck initcreate copies a starter template — it works offline and does not touch the server. Pick another
one with --template phaser (also pixi, three, multiplayer-starter, functions-starter). Building a web app
instead? Start from the web-app template. An app or game you already have (one HTML file, Vite or another build)?
Skip create and ask your AI agent, in that app's folder, to add KUMODeck to it: it follows the start Skill's
"Already have an app?" steps (two small files next to your page, one <script> block in its <head>, then
kumodeck init). Nothing is rebuilt or moved, and the app's own code, saves and sign-in keep working. The rest of this
page works the same; publish the folder your page is in (kumodeck test-deploy ., or your build output such as dist/).
init creates the project with two environments (development and production), saves kumo.json
(including deployDir: "public", so kumodeck deploy needs no folder) and writes the two publishable keys into
public/kumo-config.js for you. The page picks the development key on the --dev URL and on localhost, and the
production key everywhere else. The secret keys are returned once: init saves them to .kumo/secrets.env (only you can read it; git ignores it)
instead of printing them, so they stay out of your terminal history and out of your conversation with an AI assistant. Use them for CI,
never put them in the browser.
If the URL name (my-game) is already taken, init uses a free one KUMODeck suggests (my-game-2) and tells you.
4. Declare your project's rules#
Which features are on, prices, products and multiplayer modes live in kumo.config.json. The server owns these rules;
a modified client cannot change a price.
{
"features": { "hosting": true, "saves": true }
}kumodeck config push --env developmentEvery feature is off until you turn it on — the features line above opens exactly what this example uses (hosting and
cloud saves). Anything else answers 403 feature_disabled, so nobody can run up your bill on features you do not use.
kumodeck features lists them all; see the config reference.
A mistake in the file (a typo in a feature name, a mode with more minPlayers than maxPlayers) is rejected with the
exact path, so you find it at push time instead of in production.
5. Call the SDK#
The SDK is served by your API at /sdk.js (global Kumo) and /sdk.mjs (ES module). init signs a guest in
automatically, so the page works immediately; guests can link an email later without losing their data.
<script src="https://api.kumodeck.com/sdk.js"></script>
<script type="module">
const kumo = await Kumo.init({ projectKey: 'pk_dev_…' }); // guest sign-in happens here
const saved = await kumo.saves.get('best'); // null on the first visit
const score = 61;
if (score > (saved?.data.score ?? 0)) await kumo.saves.set('best', { score }); // follows the user to every device
</script>The templates already do this for you in public/kumo-boot.js — this is what to add to an app of your own.
That is the whole integration. See Cloud saves for slots and conflict-safe writes.
6. Deploy#
kumodeck deploy --env development
# Deployed v1 to development: 5 files (22.3 KB)
# https://api.kumodeck.com/play/my-game--dev/deploy uploads the deployDir saved by init (public/ for a template; otherwise ./dist, or pass a folder).
Uploads are content-addressed: only files the server has never seen are sent, so a redeploy of a 50 MB site
that changed one script uploads one script. Production is the default environment for deploy. If hosting is off in that
environment, deploy turns it on in kumo.config.json, pushes it there and tells you in one line — nothing else is switched on for you.
kumodeck config push --env production
# → https://my-game.kumodeck.app/
kumodeck deploy --env production
# instant: switch the live version back to v3
kumodeck rollback 37. Share it on X#
# X card image + share links + traffic per post, both environments; prints the card tags
kumodeck share on
# optional: a tracked URL for your own post
kumodeck share link "first post"share on turns on three tools in kumo.config.json, pushes it and prints the card tags: put them in the <head> of
index.html (or ask your AI agent to) and deploy again. The page then shows a large card on X; post its URL. The template's Share on X button posts the player's score as a challenge, and
people who open that link see "Challenge: beat N!". Sign in with X stays off. Details: Sharing on X.
Next steps#
- Concepts — projects, environments, keys, players (your users) and master data
- Leaderboards with a Skill — ask your AI agent; the Skill builds one in your own database and Functions
- Play online together — for games: ask your AI agent "make it playable online"
- Multiplayer rooms — for games: quick match, room codes, shared state
- Sharing on X — cards, challenges and traffic per post (off until you turn them on)
- Functions — your own server code and SQL database
- Pricing — 0% fee, free to start, everything past the free usage at cost
- Security model — what the publishable key can and cannot do