---
url: /apps/reference/cli.md
description: >-
  The whole civitai CLI command tree, indexed by name and linked to the page
  that documents each command — commands, flags, examples and the global flags —
  generated from the canonical Go CLI (civitai/cli).
---

> Documentation index: https://developer.civitai.com/llms.txt — every page on this site has a markdown version at its URL + `.md`.

# CLI

The **`civitai` CLI** (Go, repo [`civitai/cli`](https://github.com/civitai/cli))
is the canonical command-line tool for Civitai — searching and downloading
models, running generations, and authoring Apps. Its `app` command group
scaffolds a correct project, validates it against the platform contract, and
packages + submits it for review.

::: warning 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;
the others need no Node toolchain:

```bash
# npm (a thin wrapper that downloads the matching prebuilt binary)
npm install -g @civitai/cli
# or, without installing:
npx @civitai/cli --help

# Homebrew (macOS only — see the note below)
brew install civitai/tap/civitai

# Go install (from source, Go 1.25+)
go install github.com/civitai/cli/cmd/civitai@latest

# Nix flake — run without installing:
nix run github:civitai/cli -- --help
# …or install into your profile:
nix profile install github:civitai/cli
```

::: warning Homebrew is macOS-only
The tap publishes a **cask**, not a formula — the CLI's release config carries
`homebrew_casks:` and no `brews:` stanza — and a cask is a macOS-only concept.
On Linux (Linuxbrew included) `brew install civitai/tap/civitai` has nothing to
install; use npm, the Nix flake, `go install`, or a prebuilt binary instead.
:::

::: tip The npm `install-scripts` warning is expected
A **successful** npm 11 install still ends with a warning that `@civitai/cli`'s
`postinstall` is "not yet covered by allowScripts". That is an advisory about a
future npm policy, not a report that the script was skipped: the postinstall
still runs. Do not re-install with an allow-scripts flag — `civitai version`
tells you whether the install worked.
:::

The repo is a [Nix flake](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html),
so `nix run` / `nix profile install` need no Go toolchain (`x86_64`/`aarch64`
Linux and macOS). To pin the CLI as a flake input — the reproducible option for
a team devShell or CI — reference it in your `flake.nix`:

```nix
{
  inputs.civitai-cli.url = "github:civitai/cli";
  # …or pin a release tag from the Releases page:
  # inputs.civitai-cli.url = "github:civitai/cli/<tag>";

  outputs = { self, nixpkgs, civitai-cli, ... }: {
    # add `civitai-cli.packages.${system}.default` to your devShell / packages
  };
}
```

Prebuilt binaries for linux/macOS/windows × amd64/arm64 are on the
[GitHub Releases](https://github.com/civitai/cli/releases) page. Verify with
`civitai version`.

## Authenticate

Most `app` commands that talk to the platform need a stored credential:

```bash
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/account
```

## The 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`**.

```bash
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 state
```

`civitai 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/`.

## Command reference

Every command is generated from the binary's own help output — the whole
`civitai` command tree, not just `app`. Alongside App authoring it covers
catalog browsing and downloads (`models`, `images`, `articles`, `collections`,
`creators`, `tags`, `users`, `model-versions`, `download`), image generation
(`generate`, `workflows` — these **spend Buzz**), account commands
(`login`, `whoami`, `buzz`, `upgrade`, `version`), `agent-setup`, which
configures your coding agent for Civitai App development, and `feedback`, which
reports a Civitai platform problem to Civitai.

The commands are documented across the pages indexed below — `civitai app`
and `civitai app listing` first, then the catalog, generation and account
commands — so that each page's `.md` copy stays small enough for an agent's
fetch tool to read whole. The index names every command; the global flags
follow it.

Two `app` commands are badged **invite-only** — they are gated during the pre-GA
beta. The `completion` command (shell-completion scripts) is deliberately not
documented here; run `civitai completion --help` for it.

64 commands across 5 pages. Each link goes to the page that documents the command; fetch that page's `.md` for the full entry.

**[civitai app — authoring commands](https://developer.civitai.com/apps/reference/cli/app.md)** — Scaffold, validate, submit and operate an App: every `civitai app` command except the listing group.

* [`civitai app`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app) — Browse, author, and ship Civitai Apps
* [`civitai app create`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-create) — Create a ready-to-build App (web components by default)
* [`civitai app init`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-init) — Scaffold a ready-to-build App project
* [`civitai app validate`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-validate) — Validate block.manifest.json against the App schema
* [`civitai app submit`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-submit) — Package and submit an App for review
* [`civitai app status`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-status) — Check the review/deploy status of your App submissions
* [`civitai app withdraw`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-withdraw) — Withdraw your own pending App submission
* [`civitai app list`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-list) — Discover published Apps in the store (GET /api/v1/apps)
* [`civitai app view`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-view) — Show one App's detail (GET /api/v1/apps/{slug})
* [`civitai app metrics`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-metrics) — Show your App's install / run / Buzz / engagement analytics
* [`civitai app dev-token`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-dev-token) — Mint a short-lived dev block token for `npm run dev:live`
* [`civitai app dev-tunnel`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-dev-tunnel) — Preview your LOCAL dev server inside the real Civitai host via a hardened tunnel
* [`civitai app pull`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-pull) — Clone or sync your app's repository from Civitai
* [`civitai app doctor`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-doctor) — Diagnose what is incomplete or blocked on your App store listings
* [`civitai app elements`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-elements) — Look up a \<civitai-\*> element's attributes, events and slots
* [`civitai app feedback`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-feedback) — Your app's inbox: read what YOUR APP'S USERS wrote (to report a platform problem: civitai feedback)
* [`civitai app feedback flag`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-feedback-flag) — Flag a feedback row as abusive, for moderator review
* [`civitai app feedback set-status`](https://developer.civitai.com/apps/reference/cli/app.md#cli-app-feedback-set-status) — Mark a feedback row acknowledged, resolved or wont\_fix

**[civitai app listing — store listing commands](https://developer.civitai.com/apps/reference/cli/app-listing.md)** — Edit an App's store listing: icon, cover, screenshots, text, source repo and revisions.

* [`civitai app listing`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing) — Manage your App store-listing media (icon, cover, screenshots)
* [`civitai app listing set-icon`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-set-icon) — Set the listing icon (png, jpeg or webp, at most 2.0 MiB)
* [`civitai app listing set-cover`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-set-cover) — Set the listing cover (png, jpeg or webp, at most 4.0 MiB)
* [`civitai app listing add-screenshot`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-add-screenshot) — Add a screenshot (up to 8) with an optional caption
* [`civitai app listing rm-screenshot`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-rm-screenshot) — Remove a screenshot by its id (see `app listing status`)
* [`civitai app listing reorder`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-reorder) — Reorder screenshots (pass ALL current screenshot ids in the new order)
* [`civitai app listing status`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-status) — Show attached media and what's missing vs the publish floor
* [`civitai app listing set-source-repo`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-set-source-repo) — Set (or clear) the public source-repository link on your listing
* [`civitai app listing set-text`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-set-text) — Set your listing's tagline, description or category
* [`civitai app listing submit-revision`](https://developer.civitai.com/apps/reference/cli/app-listing.md#cli-app-listing-submit-revision) — Submit your live listing's open revision for moderator review

**[Catalog and download commands](https://developer.civitai.com/apps/reference/cli/catalog.md)** — Browse and search the public catalog, and download model files.

* [`civitai articles`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-articles) — Search and inspect articles on Civitai
* [`civitai articles get`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-articles-get) — Get an article by id (GET /api/v1/articles/{id})
* [`civitai articles search`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-articles-search) — Search articles (GET /api/v1/articles)
* [`civitai collections`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-collections) — Search and inspect collections on Civitai
* [`civitai collections get`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-collections-get) — Get a collection by id (GET /api/v1/collections/{id})
* [`civitai collections search`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-collections-search) — Search collections (GET /api/v1/collections)
* [`civitai creators`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-creators) — Search creators on Civitai
* [`civitai creators search`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-creators-search) — Search creators (GET /api/v1/creators)
* [`civitai download`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-download) — Download a model version's file(s)
* [`civitai images`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-images) — Search images on Civitai
* [`civitai images get`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-images-get) — Get a single image by id (GET /api/v1/images?imageId=\<id>)
* [`civitai images search`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-images-search) — Search images (GET /api/v1/images)
* [`civitai model-versions`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-model-versions) — Inspect model versions on Civitai
* [`civitai model-versions by-hash`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-model-versions-by-hash) — Get a model version by file hash (GET /api/v1/model-versions/by-hash/{hash})
* [`civitai model-versions get`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-model-versions-get) — Get a model version by id (GET /api/v1/model-versions/{id})
* [`civitai models`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-models) — Search and inspect models on Civitai
* [`civitai models get`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-models-get) — Get a model by id (GET /api/v1/models/{id})
* [`civitai models search`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-models-search) — Search models (GET /api/v1/models)
* [`civitai tags`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-tags) — Search model tags on Civitai
* [`civitai tags search`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-tags-search) — Search tags (GET /api/v1/tags)
* [`civitai users`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-users) — Look up users on Civitai
* [`civitai users get`](https://developer.civitai.com/apps/reference/cli/catalog.md#cli-users-get) — Look up a user by username or id (public search: GET /api/v1/users)

**[Generation commands](https://developer.civitai.com/apps/reference/cli/generation.md)** — Run generations and manage workflows. These spend Buzz.

* [`civitai generate`](https://developer.civitai.com/apps/reference/cli/generation.md#cli-generate) — Generate images from a text prompt (SPENDS BUZZ)
* [`civitai workflows`](https://developer.civitai.com/apps/reference/cli/generation.md#cli-workflows) — List, inspect and cancel generation workflows
* [`civitai workflows cancel`](https://developer.civitai.com/apps/reference/cli/generation.md#cli-workflows-cancel) — Cancel a running generation workflow (you are billed for what it delivered)
* [`civitai workflows get`](https://developer.civitai.com/apps/reference/cli/generation.md#cli-workflows-get) — Show one generation workflow and its outputs
* [`civitai workflows list`](https://developer.civitai.com/apps/reference/cli/generation.md#cli-workflows-list) — List the generation workflows you have submitted

**[Account, setup and utility commands](https://developer.civitai.com/apps/reference/cli/account-and-setup.md)** — Sign in, inspect your account and Buzz, configure your coding agent, and update the CLI.

* [`civitai agent-setup`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-agent-setup) — Set up your coding agent (Claude Code, Cursor, Codex, …) to build Civitai Apps
* [`civitai buzz`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-buzz) — Show your spendable Buzz balance
* [`civitai feedback`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-feedback) — Report Civitai developer-platform problems TO Civitai (not your app's user feedback)
* [`civitai feedback send`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-feedback-send) — Send one report about the developer platform to Civitai
* [`civitai feedback status`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-feedback-status) — Check whether Civitai has acknowledged or fixed a report you sent
* [`civitai login`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-login) — Authenticate with Civitai
* [`civitai upgrade`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-upgrade) — Update the civitai CLI to the latest release
* [`civitai version`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-version) — Print the CLI version, commit, and build date
* [`civitai whoami`](https://developer.civitai.com/apps/reference/cli/account-and-setup.md#cli-whoami) — Verify your stored API token and its capabilities

**Global flags**

Accepted by every `civitai` command, in addition to the flags listed with it.

| Flag | Description | Default |
|---|---|---|
| `--color` | force colored output even when stdout is not a TTY (also via CLICOLOR\_FORCE) | — |
| `--no-color` | disable colored/styled output (also via NO\_COLOR or CIVITAI\_NO\_COLOR) | — |
| `--no-update-check` | skip the background check for a newer release (also via CIVITAI\_NO\_UPDATE\_CHECK) | — |
| `-v, --version` | version for civitai | — |

## 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 for
  `npm run dev:live` (real backend). Real generation that spends Buzz needs a
  full-scope personal API key.
* **`civitai app dev-tunnel`** previews 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](https://developer.civitai.com/apps/guide/quickstart.md) for the end-to-end flow.