CLI Reference

Installation

Install the KidsBuild CLI globally:

Or use npx to run commands without installing:

Authentication

kb login

Authenticate with your KidsBuild account. Opens a browser window for secure login.

Opening browser for authentication...
Waiting for login...
✓ Logged in as @coolbuilder42
  Token saved to ~/.kidsbuild/credentials

kb logout

Remove stored credentials.

kb whoami

Check who you're logged in as.

Project Setup

kb init

Initialize a new KidsBuild project in the current directory.

Options:

• --template <name> - Use a starter template (game, tool, social)
• --name <name> - Set the app name
• --skip-install - Skip npm install

? What's your app name? my-cool-game
? What type of app? (Use arrow keys)
❯ Game
  Productivity Tool
  Creative Tool
  Social App
  Blank Project

Creating project...
✓ Created app.json
✓ Created src/App.tsx
✓ Installed dependencies

Your app is ready! Run 'kb dev' to start developing.

create-kidsbuild-app

Create a new project in a new directory (like create-react-app):

Development

kb dev

Start the development server with hot reloading and KidsBuild integration.

Options:

• --port <number> - Port to run on (default: 3000)
• --open - Open browser automatically
• --mock - Use mock data instead of real API

Starting development server...
✓ Compiled successfully

  Local:    http://localhost:3000
  Network:  http://192.168.1.100:3000
  
  KidsBuild API: Connected
  User: @coolbuilder42

Press Ctrl+C to stop

kb dev --mock

Run with mock data for offline development or testing without affecting real data:

In mock mode, all API calls return fake data and state is stored in memory only.

Database

kb migrations:create

Create a new database migration from your schema.json changes.

Comparing schema.json to current database...

Changes detected:
  + Add table: achievements
  + Add column: users.last_login
  ~ Modify column: scores.value (integer → bigint)

? Create migration? Yes

✓ Created migration: 20260307_add_achievements.json
  
Run 'kb migrations:apply' to apply this migration.

kb migrations:apply

Apply pending migrations to your development database.

Options:

• --dry-run - Show what would be applied without executing
• --env <name> - Target environment (dev, staging, prod)

kb migrations:status

Show the status of all migrations.

Migration Status:

  ✓ 20260301_initial_schema.json      Applied
  ✓ 20260305_add_leaderboard.json     Applied
  ○ 20260307_add_achievements.json    Pending

1 pending migration(s)

kb migrations:rollback

Rollback the last applied migration.

Publishing

kb build

Build your app for production.

Building for production...

✓ TypeScript compiled
✓ Assets optimized
✓ Bundle created (245 KB)

Build complete! Output in ./dist

Run 'kb publish' to publish to KidsBuild.

kb publish

Publish your app to KidsBuild for review.

Options:

• --draft - Publish as draft (not submitted for review)
• --message <text> - Version notes
• --skip-build - Use existing build in ./dist

Publishing my-cool-game v1.2.0...

✓ Build verified
✓ Assets uploaded
✓ Schema validated
✓ Submitted for review

Your app has been submitted for review!
Review typically takes 1-2 business days.

Track status: https://kidsbuild.com/apps/my-cool-game/status

kb publish --draft

Upload your app without submitting for review. Useful for testing before making it public.

App Management

kb apps

List all your apps.

Your Apps:

  my-cool-game       v1.2.0    Published    ★ 4.5 (127 reviews)
  study-helper       v2.0.1    In Review    —
  pixel-art-maker    v1.0.0    Draft        —

kb apps:info <app-id>

Show detailed information about an app.

kb apps:unpublish <app-id>

Remove an app from the marketplace (keeps data, just hides it).

Analytics

kb analytics

View analytics for your apps.

Options:

• --period <days> - Time period (default: 7)
• --format <type> - Output format (table, json, csv)

Configuration

kb config

Manage CLI configuration.

Using with AI Assistants

The CLI is designed to work well with AI coding assistants like Claude Code. You can ask Claude to run CLI commands for you:

Run the KidsBuild CLI to:
1. Check my login status: kb whoami
2. Start the dev server: kb dev
3. When I'm ready, build and publish: kb build && kb publish

Show me the output of each command.

Troubleshooting

Common Issues

• "Not logged in" - Run kb login to authenticate
• "App not found" - Make sure you're in the project directory with app.json
• "Build failed" - Check for TypeScript errors with npm run typecheck
• "Permission denied" - You may not own this app or have publish rights

Debug Mode

Add --debug to any command for verbose output:

Getting Help

Use --help with any command: