Commands

kubb studio

Command reference for connecting a project to Kubb Studio, managing pairing and permissions, and publishing CI snapshots.

Run kubb studio to connect a project to Kubb Studio. The CLI runs generation on your machine and sends progress and generated file paths to Studio. Grant --allow-read to view generated file contents and diffs in the browser.

Usage

Connect the current project. On the first run, approve the pairing code in Studio. The CLI then asks which permissions to grant for this project.

Terminal

kubb studio

Actions

The positional argument selects the action. It defaults to connect.

Action	Description
`connect`	Hold a foreground session open and generate on request.
`start`	Resolve pairing and permissions, then connect this project in the background.
`stop`	Stop the background worker and keep its pairing.
`login`	Pair this machine again without opening a generation session. Saved permissions reset.
`logout`	Stop the background worker and forget this project's stored token.
`status`	Show worker state, log path, pairing, and saved permissions.
`snapshot`	Generate and pack a snapshot on this machine, upload it in one request, then exit. See Publish snapshots from CI.

Background connection

Run start, status, and stop from the same project directory. start resolves pairing and permission prompts before detaching, then returns while the worker connects.

status reports starting, connected, reconnecting, authentication required, or stopped. Only one worker can own a project. Stop it before using foreground connect.

The worker survives terminal closure and retries temporary connection failures. Restart it after a crash or reboot. If its token is rejected, run kubb studio login, then kubb studio start. To change its URL or config, stop it and start it with the new flags. Flags can only add permissions. login resets the saved ones.

Credentials, worker state, and a bounded 1 MiB worker.log live under $KUBB_HOME/projects/<sha256(project-path)>/. KUBB_HOME defaults to ~/.kubb. If that folder is not writable, the CLI uses a folder in the OS temp directory. status prints the log path. stop waits for active generation cleanup. logout stops the worker before removing credentials. Interrupted jobs are not replayed.

Options

Option	Default	Description
`--config=<path>`, `-c <path>`		Path to a config file, such as `./kubb.staging.ts`.
`--url=<url>`	`https://kubb.studio`	URL for Kubb Studio. Plain `http://` works only for `localhost`, `127.0.0.1`, or `[::1]`.
`--allow-read`	`false`	Let Studio read generated file contents. Asked once per project when omitted.
`--allow-write`	`false`	Write generated files to disk. Asked once per project when omitted.
`--allow-config-edit`	`false`	Let Studio change plugin options in `kubb.config.ts`. Asked once per project.
`--allow-exec`	`false`	Run the formatter, the linter, and `output.postGenerate`. Asked once per project.
`--no-open`		Do not open the approval page in a browser.
`--log-level=<silent\|info\|verbose>`, `-l`	`info`	Set the verbosity.
`--token=<key>`		`snapshot` only: organization CI API key. Defaults to `KUBB_TOKEN`.
`--id=<id>`		`snapshot` only: stable identity for the CI agent. Auto-detected on GitHub Actions, GitLab CI, Bitbucket Pipelines and CircleCI.
`--base-id=<id>`		`snapshot` only: the `--id` of another CI agent, such as the base branch's, to also compare with. Auto-detected on GitHub pull requests and GitLab merge requests.
`--name=<name>`		`snapshot` only: package name for the tarball. Defaults to the name in the nearest `package.json` that has a name and a version.
`--package-version=<version>`		`snapshot` only: package version for the tarball. Defaults to the version in the nearest `package.json` that has a name and a version.
`--json`	`false`	`snapshot` only: print the result as one JSON object instead of a summary.

snapshot takes no --allow-* flag. It generates like kubb generate: it writes to output.path, then runs the formatter, the linter, and output.postGenerate. It refuses a tarball over 50 MB.

Without --allow-read, a session still generates and reports file paths, but Studio cannot display their contents. The CLI asks about permissions not supplied as flags and remembers answers per project directory. Without a TTY it skips the permission prompts, so pass the flags the run needs. In CI it also refuses to pair interactively and needs stored credentials or KUBB_AGENT_TOKEN.

Each action exits with code 1 when it fails.

Environment variables

Variable	Description
`KUBB_HOME`	Directory the CLI keeps its Studio state in. Defaults to `~/.kubb`.
`KUBB_AGENT_TOKEN`	Connect with an existing agent token instead of approving this machine.
`KUBB_TOKEN`	`snapshot` only: organization CI API key. Same as `--token`.
`KUBB_AGENT_MAX_GENERATIONS`	How many recent generations the agent keeps for Studio to read. Defaults to `8`.
`KUBB_AGENT_MAX_GENERATIONS_MB`	Size cap in MB for the kept generations. Defaults to `100`.
`KUBB_AGENT_MAX_SNAPSHOT_MB`	Size cap in MB for the on-disk copy kept for diffs. Defaults to `50`.

Snapshot output

--json prints one JSON object with id, name, version, integrity, url, snapshotIdUrl, expiresAt, and agentUrl. It also includes changes and branchChanges when comparisons are available. Installing a snapshot requires a separate registry API key.

JSON field	Compared with
`changes`	The previous snapshot on the same pull request or branch.
`branchChanges`	The latest snapshot of the agent named by `--base-id`, or of the base branch detected on a GitHub pull request or GitLab merge request. Its `branch` field names that agent. Its `baseFound` field distinguishes a branch with no CI agent from one with an agent that has no snapshot of this package yet.

CI agent identity

snapshot detects GitHub Actions, GitLab CI, Bitbucket Pipelines, and CircleCI. Other providers require a stable --id. Use a stable --id on the base branch and pass that identity as --base-id on pull request runs. Passing --id turns off base detection, so also pass --base-id to get branchChanges.

GitLab CI

The CI identity is gl:<project id>:<merge request iid>, read from CI_PROJECT_ID and CI_MERGE_REQUEST_IID, so every pipeline on that merge request publishes to one CI agent. A branch pipeline falls back to CI_COMMIT_REF_SLUG, so the default branch has one agent too. Pass --id to group runs your own way.

A merge request pipeline also names its target branch's agent, from CI_MERGE_REQUEST_TARGET_BRANCH_NAME. The snapshot reports which generated files changed against that branch's latest snapshot in branchChanges, and against the merge request's previous pipeline in changes. The commit it records is the source branch's head, CI_MERGE_REQUEST_SOURCE_BRANCH_SHA, when GitLab sets it.

Plugins in Studio

Studio builds its plugin list and option forms from extension manifests. When Studio connects, the agent reports the manifest of every extension it finds in config.extensions.

The agent looks at these packages and keeps each one that resolves from the project root and ships a valid kubb-extension.json:

The dependencies and devDependencies in the project's package.json.
The packages kubb.config.ts imports.
The extensions that ship with kubb: @kubb/adapter-oas, @kubb/parser-ts, @kubb/parser-md, and @kubb/plugin-barrel.

A third-party plugin works in Studio once it is installed in the project and ships a manifest with kind: "plugin". It needs no registry entry. Install it with kubb add or your package manager, then reconnect so Studio sees it.

The agent imports a plugin package only when it is a @kubb/plugin-* package, or an installed package whose manifest has kind: "plugin". It calls the factory the manifest names in export. The agent refuses any other package name before it imports anything, and config edits follow the same rule.

Agent	Plugins it can run
`kubb studio` on your machine	`@kubb/plugin-*` packages and plugins installed in the project that ship a manifest.
Docker agent and hosted sandbox	Only the packages installed in their image. They install nothing at runtime.

Studio also lists plugins from the kubb.dev registry. A plugin that the agent cannot run shows as not installed, with a kubb add <id> hint to install it.