Kubb v5.3.6

Kubb Studio ​

Kubb Studio is a browser interface for a Kubb project. You edit plugin options, trigger a generation, and watch its progress while Kubb runs on your machine against the files on disk.

Kubb reports progress and generated file paths to Studio. Your spec stays on your machine. Studio reads source from a generated file only after you grant --allow-read.

WARNING

This feature is under active development. Use it with caution and expect breaking changes.

NOTE

Studio is not a bundler integration you add to a build. It is a session you open from the CLI and close when you are done.

Connect a project ​

The Studio runtime ships with the CLI, so a project that already has kubb installed needs nothing else. Run this from the project root, next to your kubb.config.ts.

Terminal
shell
kubb studio

When the project is not approved yet, the CLI opens Studio's approval page and waits for confirmation. Once approved, the session connects and the project appears in Studio until you stop the command. Check the connected machine with kubb studio status, and disconnect it with kubb studio logout.

Choose what Studio may do ​

A session is read-only by default. Studio sees generated file paths, but not their source, and nothing on disk changes. It is safe to try on a real project.

The CLI exposes five permissions. It asks about each permission when you first connect a project, then remembers your answers.

Permission What it grants
--allow-read Studio can read the source of the files a generation produced.
--allow-write Generated files are written to disk instead of only streaming to Studio.
--allow-config-edit Studio may change plugin options in your kubb.config.ts.
--allow-input A spec sent by Studio replaces the one on disk for that generation.
--allow-exec The formatter, the linter, and output.postGenerate run as child processes.
Terminal
shell
kubb studio --allow-read --allow-write --allow-exec

Grant --allow-config-edit when you want to tune plugin options from the browser and keep the result. Studio patches the matching fields in kubb.config.ts and leaves the comments and formatting around them alone.

Run headless or self-hosted ​

kubb studio also runs on a build agent, with the agent token passed through KUBB_AGENT_TOKEN instead of an interactive approval:

Terminal
shell
KUBB_AGENT_TOKEN=your-agent-token kubb studio

Nothing is asked without a TTY, so grant what the run needs with flags on the command line. --allow-read is the one a headless run most often forgets: without it, generated files show up in the tree with no contents. Point at a self-hosted instance with --url, and set KUBB_HOME to move the CLI's Studio state out of ~/.kubb.

For a connection that outlives your terminal, the kubblabs/kubb-agent Docker image runs the same runtime and stays connected on its own. Use it when a team wants one shared agent instead of everyone connecting their own checkout.

Snapshot from CI ​

kubb studio snapshot generates a package and publishes it to Studio in one command, then exits. Use it to hand a reviewer an installable tarball on a pull or merge request, from any CI. It needs a different credential than kubb studio: an organization CI API key, not an agent token.

Terminal
shell
KUBB_TOKEN=$KUBB_TOKEN kubb studio snapshot

The command detects GitHub Actions, GitLab CI, Bitbucket Pipelines, and CircleCI on its own, and reuses one CI agent per pull or merge request instead of registering a new one on every run. On another CI, pass --id with something stable, such as the merge request number.

Use --json to read the result in a later step. It prints one JSON object with the tarball URL, the package name and version, and the integrity hash, and nothing else on stdout.

Terminal
shell
kubb studio snapshot --json | jq -r '.url'

Two providers have a page of their own:

NOTE

The tarball URL needs a registry API key to download, not the ci key that created the snapshot. Create one in Studio's settings for whichever system installs the package.

See the snapshot action reference for every flag.

See also ​