CLI
The civitai CLI (Go, repo civitai/cli) is the canonical tool for authoring Civitai Apps. Its app command group scaffolds a correct project, validates it against the platform contract, and packages + submits it for review.
This replaces the deprecated @civitai/blocks-cli
The old npm @civitai/blocks-cli (with init / dev / deploy) is deprecated. Install the civitai binary instead — its authoring commands below are the source of truth.
Install
Pick whichever fits — npm is the most convenient if you already have Node (App authors usually do); the others need no Node toolchain:
# npm (a thin wrapper that downloads the matching prebuilt binary)
npm install -g @civitai/cli
# or, without installing:
npx @civitai/cli --help
# Homebrew (macOS / Linux)
brew install civitai/tap/civitai
# Go install (from source, Go 1.25+)
go install github.com/civitai/cli/cmd/civitai@latestPrebuilt binaries for linux/macOS/windows × amd64/arm64 are on the GitHub Releases page. Verify with civitai version.
Authenticate
Most app commands that talk to the platform need a stored credential:
civitai login # browser device login
# or a full-scope personal API key (needed for real Buzz-spend in dev:live):
civitai login --token <key> # create the key at civitai.com/user/accountThe App lifecycle
The authoring flow is create → validate → submit, then review on civitai.com. The platform rebuilds your app from source — there is no client-side deploy.
civitai app create my-app # scaffold a ready-to-build App
cd my-app
npm install && npm run dev:harness # iterate locally against the mock host
civitai app validate # local pre-check of block.manifest.json
civitai app submit # package the SOURCE tree + submit for review
civitai app status # track review / deploy statecivitai app submit enters your app into moderator review — it is not published immediately. On approval the platform builds + deploys it and serves it at https://<blockId>.civit.ai/.
The commands and flags below are generated from the civitai app --help command tree.
civitai app create[name] [dir]
Create a ready-to-build App (batteries-included, SDK money-path)
| Flag | Description | Default |
|---|---|---|
--dir string | output directory (default ./<slug>) | — |
--from string | fork from an existing published app slug (not yet wired) | — |
--name string | display name (default derived from the name argument) | — |
-t, --template string | project template: static | page-vite | page-money | page-money |
-y, --yes | non-interactive: never prompt (use flags/defaults; fail if a name is missing) | — |
civitai app init[name] [dir]
Scaffold a ready-to-build App project
| Flag | Description | Default |
|---|---|---|
--dir string | output directory (default ./<slug>) | — |
--from string | fork from an existing published app slug (not yet wired) | — |
--name string | display name (default derived from the name argument) | — |
-t, --template string | project template: static | page-vite | page-money | static |
-y, --yes | non-interactive: never prompt (use flags/defaults; fail if a name is missing) | — |
civitai app validate[dir]
Validate block.manifest.json against the App schema
| Flag | Description | Default |
|---|---|---|
--json | emit the validation result as JSON (scriptable) | — |
--strict | treat warnings as failures (non-zero exit) | — |
civitai app submit[dir]
Package and submit an App for review
| Flag | Description | Default |
|---|---|---|
-o, --out string | output .zip path (default: <blockId>-<version>.zip) | — |
--package-only | only write the .zip; do not attempt submission | — |
--skip-validate | skip manifest validation before packaging | — |
-y, --yes | skip the confirmation prompt and submit (for scripts/CI) | — |
civitai app status[blockId]
Check the review/deploy status of your App submissions
| Flag | Description | Default |
|---|---|---|
--id string | look up a single submission by publish-request id (pubreq_...) | — |
--json | emit raw JSON (scriptable) | — |
civitai app withdraw[pubreq-id]
Withdraw your own pending App submission
| Flag | Description | Default |
|---|---|---|
--id string | the publish-request id to withdraw (pubreq_...) | — |
-y, --yes | accepted for symmetry with 'app submit' (withdraw is non-interactive; no-op) | — |
civitai app listing
Manage your App store-listing media (icon, cover, screenshots)
civitai app listing set-icon<file>
Set the listing icon (a square-ish image)
| Flag | Description | Default |
|---|---|---|
--changelog string | changelog for the moderator review (used only when the listing is already live) | — |
--dir string | app directory holding block.manifest.json (when --slug is not given) | . |
--slug string | app slug (defaults to block.manifest.json's blockId) | — |
-y, --yes | skip the live-listing revision confirmation | — |
civitai app listing set-cover<file>
Set the listing cover (a landscape hero image)
| Flag | Description | Default |
|---|---|---|
--changelog string | changelog for the moderator review (used only when the listing is already live) | — |
--dir string | app directory holding block.manifest.json (when --slug is not given) | . |
--slug string | app slug (defaults to block.manifest.json's blockId) | — |
-y, --yes | skip the live-listing revision confirmation | — |
civitai app listing add-screenshot<file>
Add a screenshot (up to 8) with an optional caption
| Flag | Description | Default |
|---|---|---|
--caption string | optional one-line caption for the screenshot | — |
--changelog string | changelog for the moderator review (used only when the listing is already live) | — |
--dir string | app directory holding block.manifest.json (when --slug is not given) | . |
--slug string | app slug (defaults to block.manifest.json's blockId) | — |
-y, --yes | skip the live-listing revision confirmation | — |
civitai app listing rm-screenshot<screenshotId>
Remove a screenshot by its id (see `app listing status`)
| Flag | Description | Default |
|---|---|---|
--dir string | app directory holding block.manifest.json (when --slug is not given) | . |
--slug string | app slug (defaults to block.manifest.json's blockId) | — |
civitai app listing reorder<screenshotId...>
Reorder screenshots (pass ALL current screenshot ids in the new order)
| Flag | Description | Default |
|---|---|---|
--dir string | app directory holding block.manifest.json (when --slug is not given) | . |
--slug string | app slug (defaults to block.manifest.json's blockId) | — |
civitai app listing status
Show attached media and what's missing vs the publish floor
| Flag | Description | Default |
|---|---|---|
--dir string | app directory holding block.manifest.json (when --slug is not given) | . |
--slug string | app slug (defaults to block.manifest.json's blockId) | — |
civitai app list
Discover published Apps in the store (GET /api/v1/apps)
| Flag | Description | Default |
|---|---|---|
--category string | filter by marketplace category (generation, games, utility, discovery, moderation, analytics, other) | — |
--cursor string | pagination cursor from a previous response | — |
--json | print the raw API JSON response (for scripting) | — |
--kind string | filter by kind (all, onsite, offsite) | — |
--limit int | results per page (1-50) | — |
--sort string | sort order (top-rated, popular, newest, name) | — |
civitai app view<slug>
Show one App's detail (GET /api/v1/apps/{slug})
| Flag | Description | Default |
|---|---|---|
--json | print the raw API JSON response (for scripting) | — |
civitai app dev-token<slug>invite-only
Mint a short-lived dev block token for `npm run dev:live`
| Flag | Description | Default |
|---|---|---|
--env | print VITE_LIVE_BLOCK_TOKEN=<token> (paste-ready into .env.development.local) | — |
civitai app dev-tunnel[blockId]invite-only
Preview your LOCAL dev server inside the real Civitai host via a hardened tunnel
| Flag | Description | Default |
|---|---|---|
--block string | the blockId (app slug) to tunnel (or pass it positionally; defaults to the blockId in block.manifest.json in the CWD) | — |
--idle-timeout duration | tear the tunnel down after this much inactivity | 30m0s |
--local-host localhost | host your local dev server is bound to. Default localhost (loopback) — the scaffold's `dev:tunnel` binds localhost, so most users need nothing. Set this for a dev server NOT on the CLI's loopback: a container/pod (e.g. --local-host 10.42.0.100), a VM, or a specific bound interface | localhost |
--no-wait | skip the readiness wait and print the URL immediately (it may 404/NXDOMAIN for ~1–2 min while DNS/route propagate) | — |
--port int | local dev-server port to tunnel (matches the scaffold's dev:tunnel) | 5186 |
--ready-timeout duration | cap the wait for the public host to start serving (0 = wait indefinitely until ready or Ctrl-C; a positive value warns + prints the URL anyway on expiry) | — |
--tunnel-endpoint string | sish SSH endpoint host:port (default sish.civitai.com:2224, or $CIVITAI_DEV_TUNNEL_ENDPOINT) | — |
civitai app pull[dir]
Clone or sync your app's repository from Civitai
| Flag | Description | Default |
|---|---|---|
--app string | the app slug (repo name) or appBlockId to pull (required) | — |
Local dev against the real backend
The scaffold ships npm scripts for the inner dev loop (npm run dev:harness for the mock host, npm run dev:live for the real backend). Two app subcommands support the live loop and are invite-gated during the pre-GA beta:
civitai app dev-token <slug>mints a short-lived dev block token fornpm run dev:live(real backend). Real generation that spends Buzz needs a full-scope personal API key.civitai app dev-tunnelpreviews your local dev server rendered inside the real Civitai host (real session, real pickers, real Buzz) via a hardened reverse SSH tunnel.
See the Quickstart for the end-to-end flow.