CLI reference
The kotao CLI ships with your theme as a dev dependency (@kotao/cli). Run it inside the
project as bun x kotao so it resolves the local install.
Authentication
Section titled “Authentication”kotao auth login
Section titled “kotao auth login”Log in for interactive CLI publishes. Use --device for the OAuth device flow: the CLI prints
a URL, you approve in the browser (within ~10 minutes), and the session is stored globally in
~/.config/kotao/cli-session.json.
| Flag | Purpose |
|---|---|
--device |
OAuth device authorization flow (recommended) |
--no-open |
Do not auto-open the browser during device login |
--token <jwt> |
Store an already-minted API bearer token |
--accounts-token <token> |
Store an accounts session token for workspace switching |
kotao auth status / kotao auth logout
Section titled “kotao auth status / kotao auth logout”Print the saved session target, or remove the saved session.
Targets
Section titled “Targets”kotao workspace select [workspace-id]
Section titled “kotao workspace select [workspace-id]”Pick the active workspace for CLI publishing. Interactive when no id is given; the choice is remembered.
kotao storefront select [site-id]
Section titled “kotao storefront select [site-id]”Pick the storefront site publishes target. Remembered until you reselect.
The storefront toolchain
Section titled “The storefront toolchain”kotao storefront create <directory>
Section titled “kotao storefront create <directory>”Scaffold a new theme (bun create kotao-storefront calls this for you). Connection flags
(--shop-id, --site-id, --storefront-api-endpoint, --storefront-api-token, …) prefill
.dev.vars; --yes runs non-interactively.
kotao storefront dev / build / preview
Section titled “kotao storefront dev / build / preview”Local dev server with untrusted-mode parity (dev), a production-parity build (build),
and a local server for the built output (preview). --port <n> where applicable.
kotao storefront codegen
Section titled “kotao storefront codegen”Generate typed GraphQL from your #graphql documents.
| Flag | Purpose |
|---|---|
--schema-url <url> |
Introspect a running Storefront API (default: $STOREFRONT_API_ENDPOINT) |
--schema <file> |
Read the SDL from a file (offline) |
--documents <dir> |
Directory scanned for #graphql documents (default: app) |
--out <file> |
Output (default: app/graphql/storefrontapi.generated.d.ts) |
kotao storefront publish
Section titled “kotao storefront publish”Package your committed theme source and publish it through the Workspace API to the
selected site. Requires a git repository with bun.lock and kotao.theme.json committed.
| Flag | Purpose |
|---|---|
--site-id <uuid> |
Target site (default: the selected one / $KOTAO_SITE_ID) |
--deployment-id <id> |
Immutable deployment id (default: generated UUID) |
--token <token> |
Workspace API key (default: $KOTAO_API_TOKEN) |
kotao storefront deploy
Section titled “kotao storefront deploy”The CI/build-service variant of publish: hands the source directly to a build service via
--build-service-url / --shop-id / --token (or the $KOTAO_* env vars).
kotao storefront migrate shopify-theme <directory>
Section titled “kotao storefront migrate shopify-theme <directory>”Audit a Shopify Liquid or Hydrogen theme export for Kotao migration; --json for
machine-readable output, --out <dir> to emit a migration draft.