CLI

The kizlo CLI is the tool you run alongside your project. It scaffolds Kizlo into a new or existing app, generates the contract that types your client against your server, runs local WordPress you can build against, and runs your tests against a real, disposable WordPress.

It ships with the kizlo package, so there's nothing extra to install. Reach for it through your package runner:

npx kizlo <command>

The commands

A handful of commands cover the whole workflow, from first scaffold to a green test run:

Every command reads kizlo.config.ts to find where your server lives and how your test environment is set up.

kizlo create

create scaffolds a new project with Kizlo already wired. Reach for it when you're starting from scratch rather than adding to an app you already have. Give it a template and a directory name:

npx kizlo@latest create nextjs my-app

Both arguments are optional (kizlo create [template] [project-name]); create prompts for whichever you leave off, and the template auto-selects while nextjs is the only one. It creates my-app/, lays down a fully wired project for that template, and runs the same WordPress credential prompts as init. When it finishes, cd my-app, install dependencies, and make your first call. The Next.js quickstart walks it end to end.

kizlo init

init sets Kizlo up in an existing project. It detects your framework, package manager, src directory, and import alias, then scaffolds the server, client, route handler, and config, prompting for your WordPress credentials along the way and writing them to .env.

npx kizlo@latest init

It's the recommended path through the Installation guide, which walks the prompts in detail. Past the defaults, a few flags tune the run:

Backend URL

The plugin delivers webhook events to your Kizlo backend, so init records where it's reachable. A detected framework mounts the handler at a known path (/api/kizlo for Next.js), so init asks one question: your app's public URL. It derives the backend from it and writes it to NEXT_PUBLIC_KIZLO_BASE_URL.

The base preset has no known mount, so init asks two URLs: your public site URL (what the plugin points back at) and the backend URL where you've mounted the handler (written to KIZLO_BASE_URL).

The generated client.ts routes to that backend. Same-origin deploys default to the page origin; a backend on a different origin is inlined into createKizloClient(contract, { url }). Swap that for your bundler's own public env var (e.g. import.meta.env.VITE_KIZLO_BASE_URL) to set it per environment.

kizlo check

check compares the configured introspection.ts with the contract published by WordPress. It exits non-zero and prints a unified diff when the committed introspection is stale. It never changes the file.

npx kizlo check

Use --test after kizlo test to check against the WordPress stack built from test.fixtures. This makes the same command useful locally and in CI:

npx kizlo test
npx kizlo check --test

Pass --dir <path> when the Kizlo server lives somewhere other than the configured dir. If the check fails, the message prints the matching kizlo generate command.

kizlo generate

generate builds the contract once and exits. It's the command for builds and CI. Run it before you typecheck or bundle, so server/generated/ exists and is current when the client imports it.

npx kizlo generate

Your configured server entry must export procedures. generate reads that procedure tree and writes a JSON contract whose generated barrel is typed as typeof procedures:

export const { procedures, client, context, handler } = createKizlo({ integrations: [nextjs()] })

It exits non-zero if it can't find a Kizlo server in your entry file or if generation fails, so a stale or broken contract fails the build rather than slipping through. It accepts --dir to point at a Kizlo directory other than the one in kizlo.config.ts, --test to generate from WordPress left running by kizlo test, and --strict to refuse a partial contract.

When a plugin's routes can't be published

One plugin's broken declaration doesn't take the rest of the contract down with it. WordPress publishes everything that passed validation and reports what it had to drop, and generate writes that subset. Your routes keep regenerating while the broken plugin gets fixed.

Every exclusion is printed with the schema or route it landed on, then a count of what's missing from the generated introspection. Warnings are separate: a warning means a declaration lost a constraint, and the type it produces is still correct.

Pass --strict to refuse a partial contract instead:

npx kizlo generate --strict

Strict generation prints the same diagnostics, exits non-zero, and leaves the introspection already on disk untouched, so a build never replaces a complete introspection with one that's quietly short of routes. Reach for it in CI, where a missing route typechecks clean and ships the gap. It governs the introspection only, since contract.json is built from your own procedures and has no third-party contributors.

kizlo dev is always partial. A watcher that refused to write would leave you working against a client that can't be regenerated until someone else's plugin is fixed.

kizlo dev

kizlo dev is the command you run while developing. It watches your server and regenerates the contract on every save. A debounce collapses a burst of saves into one rebuild, and your client stays typed against the latest server without you thinking about it. A broken server entry doesn't stop it: it reports the error and keeps watching, so the next save can fix it. Only one watcher writes the contract at a time. A single-instance lock means a framework dev script and kizlo dev won't fight over the same file.

npx kizlo dev

When local is set, kizlo dev also runs local WordPress alongside the watcher: a long-lived Docker WordPress on http://localhost:8080 you build your app against. Without it (a project pointed at your own WordPress), it runs the watcher alone. What sets local WordPress apart from the test environment:

• Every file is editable. The whole install (core, themes, uploads, plugins) lives in .kizlo/local, bind-mounted into the container. Browse and edit it from your file manager, and changes are live.
• Plugins come from your local.dev.fixtures, the same fixtures the test environment uses. Each fixture installs the plugins it needs (a wp.org slug or zip source), or bind-mounts a local { path: "..." } over wp-content/plugins so plugin source edits show up live.
• Your data survives. It's never wiped on start; fixtures seed only on a fresh install.

kizlo dev runs in the foreground and stops local WordPress when you press Ctrl+C or close the terminal, like next dev, so it never outlives your session. stop and reset are escape hatches for the rare times you need to act on it outside a kizlo dev run.

Enabling local WordPress

kizlo create and kizlo init offer to set up local WordPress during onboarding. Choose it and they provision the .kizlo/local install, write the connection to .env, and set local with its dev and test stacks in kizlo.config.ts for you. There's no folder to pick: the install location is fixed.

Fresh local WordPress installs use admin for both the wp-admin username and password. Existing installs keep their current login. Run kizlo dev reset to rebuild an existing dev site with the default credentials.

kizlo dev creates a separate application password for REST access and writes it to the local .env connection. That credential is not the wp-admin password.

Its MySQL is published on 127.0.0.1:3307 (override with dev.dbPort) so you can inspect or edit tables directly, beyond what wp-admin exposes. Kizlo doesn't bundle a database UI. Point whatever client you already use (the mysql CLI, TablePlus, DBeaver, Sequel Ace) at host 127.0.0.1, that port, database wordpress, user wordpress, password wppass:

mysql -h127.0.0.1 -P3307 -uwordpress -pwppass wordpress

Local WordPress always enables PHP OPcache with dev-safe settings (it still picks up your live edits), which offsets most of the slower file I/O that a bind-mounted install costs on macOS/Windows.

On native Linux it also runs the container as your user, so the files WordPress writes into the folder are owned by you and stay editable: no sudo, no permission surprises. macOS/Windows handle that mapping already, so nothing extra happens there.

Seed with fixtures

If you want a code-defined starting point rather than a real-data snapshot, point dev.fixtures at the same fixtures your test environment uses. Each runs once over REST (and can drop to wp-cli for anything REST can't reach) on a fresh install: the first kizlo dev or after reset. Your dev environment then mirrors your test data from versioned code:

dev: { fixtures: [postFixture()] }

On reruns of an existing install, fixtures don't re-run, so your manual edits are never clobbered.

kizlo test

With local set, kizlo test runs your test suite against real WordPress, with no mocks. It boots a Docker-based WordPress (on http://localhost:8889, independent of your local dev WordPress), seeds it with your fixtures, then runs your project's own test command against it:

npx kizlo test

Local WordPress is idempotent here. The first run boots the containers and seeds them; later runs reuse the same install and skip the slow seed, so reruns are fast. After the suite finishes it's left running by default for that reason. Two flags change the lifecycle:

npx kizlo test --reset --teardown   # a clean install, torn down afterward

Under the hood test runs your package manager's test script (pnpm test, npm test, or bun run test), detected from your lockfile, or whatever you set as the test command. Its output streams straight to your terminal, and kizlo test exits with your suite's exit code. With the test stack off, kizlo test skips the Docker WordPress entirely and just runs that script.

Managing test WordPress by hand

A kizlo test run leaves WordPress up by default, so you can poke at WP Admin, debug a fixture, or point another tool at the seeded credentials between runs. To get running WordPress without invoking your suite, run kizlo test once. It seeds and stays up.

These subcommands drive that same install's lifecycle by hand:

The difference between stop and reset is the database volume: stop keeps it, reset throws it away.

Configuration

kizlo.config.ts lives at your project root (.js and .mjs work too). init writes it for you; you edit it as your project grows. Define it with defineConfig for a fully typed config:

import { defineConfig } from "kizlo/config"

export default defineConfig({
  dir: "src/lib/kizlo",
  alias: "@",
  local: {
    dev: {
      version: "latest",
      port: 8080,
      dbPort: 3307,
      fixtures: [],
    },
    test: {
      port: 8889,
    },
  },
})

Everything about generation lives under dir; everything about the local stacks lives under local. dir takes a string (the home directory Kizlo owns) or an object that sets server, contract, and introspection paths on their own. Omit server and there are no sources to watch and no contract, only the generated introspection.