CLI

@gtkx/cli installs the gtkx command. Scaffolded projects call it from their package scripts, so npm run dev runs gtkx dev. Outside a script, run it from the project with npx gtkx <command>.

gtkx --help lists the commands, gtkx <command> --help lists a command's options, and gtkx --version prints the installed version. Each section below links to the guide page that explains the workflow. In the tables, an option shown with a placeholder such as <dir> takes a value, and one without is a boolean flag.

A command stops with an error on an option it does not define. Boolean options also take a --no- form, as in --no-read-only. Only gtkx dev and gtkx storybook pass arguments to the application; put them after --, as described in Command-line apps.

gtkx create

Creates a project, as npm create gtkx does, from a directory that already has @gtkx/cli installed, such as a workspace gaining another app. It takes the same arguments and options, listed with their defaults in Scaffold Options.

gtkx dev

Runs the app from source and watches the project. Fast Refresh applies most edits to the open window. See the dev loop.

gtkx dev [entry] [options] [-- application arguments]

Option	Default	Description
[entry]	The first of src/index.tsx, .jsx, .ts, .js	Application entry module
--cwd <dir>	Current directory	Project root
--config <file>	gtkx.config.*	Configuration file, relative to the project root. See Selecting another configuration
--headless	false	Run on an isolated headless Wayland display. See Headless development
--size <WxH>	1024x768	Headless display size, such as 1280x720. Requires --headless

gtkx build

Bundles the app for production into dist/bundle.mjs. See Production build output.

gtkx build [entry] [options]

Option	Default	Description
[entry]	The first of src/index.tsx, .jsx, .ts, .js	Application entry module
--cwd <dir>	Current directory	Project root
--config <file>	gtkx.config.*	Configuration file, relative to the project root
--out <dir>	dist	Output directory below the project root

gtkx deploy

Builds the app and packages it for distribution. See Deploying.

gtkx deploy [entry] [options]

Option	Default	Description
[entry]	The first of src/index.tsx, .jsx, .ts, .js	Application entry module
--cwd <dir>	Current directory	Project root
--config <file>	gtkx.config.*	Configuration file, relative to the project root
--target <list>	deploy.targets, otherwise flatpak	Comma-separated package formats: appimage, deb, flatpak, rpm
--arch <list>	deploy.architectures, otherwise the host	Comma-separated architectures: arm64, x64
--out <dir>	deploy.outDir, otherwise build	Deployment directory below the project root
--print-manifests	false	Write the generated manifests and metadata, then stop without packaging
--skip-build	false	Package the existing dist/ instead of building

gtkx codegen

Generates the project's bindings, translation catalogs and TypeScript declarations. gtkx dev, gtkx build and the Vitest plugin also generate them when they are missing or out of date. See What codegen emits.

gtkx codegen [options]

Option	Default	Description
--cwd <dir>	Current directory	Project root
--config <file>	gtkx.config.*	Configuration file, relative to the project root
--force	false	Delete the generated store and regenerate it, for example to recover a corrupted one
--lock-timeout <ms>	600000	Longest wait for each generated-store lock, in milliseconds

gtkx docs

Writes Markdown reference pages for the JSX elements of the libraries in gtkx.config.ts. See Generating element reference docs.

gtkx docs [options]

Option	Default	Description
--cwd <dir>	Current directory	Project root
--out <dir>	docs/reference	Output directory below the project root. It must be empty or hold an earlier gtkx docs run
--base-path <path>	/reference	URL base path of the links between the generated pages
--force	false	Regenerate even when the pages are up to date

gtkx storybook

Opens the native Storybook explorer for the project's stories, with hot reload. See Storybook.

gtkx storybook [options] [-- application arguments]

Option	Default	Description
--cwd <dir>	Current directory	Project root
--config <file>	gtkx.config.*	Configuration file, relative to the project root
--storybook-config <file>	.storybook/main.*	Story configuration file, relative to the project root
--headless	false	Run on an isolated headless Wayland display
--size <WxH>	1024x768	Headless display size. Requires --headless

gtkx mcp

Runs the MCP server that exposes the running app and the generated API reference to an agent. MCP clients start it. See App Inspection (MCP).

gtkx mcp [options]

Option	Default	Description
--cwd <dir>	Current directory	Project root
--tools <list>	mcp.tools, otherwise all	Comma-separated tool name patterns. See Choose the available tools
--read-only	mcp.readOnly	Register only the tools that read state, leaving out the ones that drive the app

gtkx mcp init

Adds the gtkx server to an MCP client's project configuration file. See Setup.

gtkx mcp init --client <name> [options]

Option	Default	Description
--client <name>	Required	The client to configure: claude, cursor, vscode, opencode or codex
--cwd <dir>	Current directory	Project root

gtkx upgrade

Moves every GTKX package in the project or its workspace to one version and installs it. See Updating GTKX.

gtkx upgrade [version] [options]

Option	Default	Description
[version]	The newest release on the project's dist-tag	Version or dist-tag to move to
--cwd <dir>	Current directory	Project root

gtkx cleanup

Removes headless runtime directories and compile caches left by interrupted runs. They belong to your user account rather than a project, so the command ignores --cwd. See Headless development.

gtkx cleanup [options]

Option	Default	Description
--dry-run	false	List the stale directories without removing them