Skip to main content

Build your own theme

Getting started

Install the kotao CLI, sign in, scaffold your first theme, develop it locally, and push it live.

You need a Kotao workspace and Node 22+ on your machine.

1. Install the CLI

npm install -g @kotao/cli

Or with bun:

bun add -g @kotao/cli

Verify:

kotao --version

2. Sign in

kotao login

The CLI prints a URL and an 8-character code. Open the URL in any browser, sign in to Kotao if you’re not already, and confirm the code. The CLI’s spinner picks up the approval within a few seconds and saves your credentials to ~/.config/kotao/credentials.json (mode 600).

You can verify your session with:

kotao whoami

3. Scaffold a theme

kotao theme init my-theme
cd my-theme
bun install

The scaffold drops a working starter theme into ./my-theme/ — theme.json, a package.json pinning @kotao/sites-theme-sdk, an astro.config.ts with the Cloudflare adapter pre-wired, a hero section example, and a layout. See theme anatomy for what each file does.

4. Develop locally

kotao theme dev

Astro dev fires on http://127.0.0.1:4321 rendering your theme through the storefront runtime. Edits to your sections, layouts, or styles hot-reload immediately. Ctrl-C cleanly restores the runtime back to its default.

5. Push live

Bump theme.json.version (semver), then:

kotao theme push

The CLI packages your source, uploads it to Kotao’s R2, kicks off a sandboxed k8s build, and polls until the version is ready. On success it prints the slug you can apply to any site you own.

Next

  • Theme anatomy — what every file in the scaffold does
  • Dev workflow — the hot-reload loop, restoring after ctrl-c
  • Publishing — semver, build failures, how the pipeline actually runs

Next →

Theme anatomy