Deploy with the CLI

kotao storefront publish packages your committed source and hands it to the platform, which installs the @kotao/* packages from npm, builds the theme server-side, and activates it on your storefront site. You never ship a prebuilt bundle.

Prerequisites

• Your theme is a git repository with everything committed — publish uploads committed files only, and the build needs bun.lock and kotao.theme.json in the commit.
• bun install has run in the project (the kotao CLI is a local dev dependency).

Publish

bun x kotao auth login --device
bun x kotao workspace select
bun x kotao storefront select
bun run publish

auth login --device opens a browser approval at accounts.kotao.com. Approve within about ten minutes; the CLI keeps polling until you do. The session is stored globally (~/.config/kotao/cli-session.json), so you log in once per machine.

workspace select and storefront select pick the workspace and the storefront site the publish targets. Both remember your choice — reselect any time to switch targets.

bun run publish uploads, builds, and activates. The CLI streams the build status and exits when the deployment is live.

Caution

Publish replaces the site’s active theme. Point it at a test or draft site while you iterate — pick the right target in kotao storefront select before publishing to a live shop.

Troubleshooting

• “needs a git repository” — run git init && git add -A && git commit first; publish reads the committed tree.
• The kotao command behaves oddly outside the project — run bun install first and invoke it as bun x kotao inside the project, so it resolves your local @kotao/cli dev dependency.
• Device login timed out — run bun x kotao auth login --device again and approve the browser prompt within the ten-minute window.