# CLI reference (/docs/compute/cli-reference)

> For the complete Prisma documentation index, see [llms.txt](https://www.prisma.io/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL.

Every @prisma/cli command, flag, environment variable, and error code for Prisma Compute.

Location: Compute > CLI reference

This page is the complete reference for the [`@prisma/cli`](https://github.com/prisma/prisma-cli) beta package. For a guided start, see [Get started with `@prisma/cli`](https://www.prisma.io/docs/compute/getting-started).

The package installs an executable called `prisma-cli`. Run it without installing:

  

#### bun

```bash
bunx @prisma/cli@latest <command>
```

#### pnpm

```bash
pnpm dlx @prisma/cli@latest <command>
```

#### yarn

```bash
yarn dlx @prisma/cli@latest <command>
```

#### npm

```bash
npx @prisma/cli@latest <command>
```

Requires Node.js 22.12 or newer for `npx` and `pnpm`; `bunx` also works. The command groups are `auth`, `init`, `project`, `project env`, `git`, `branch`, `database`, `app`, `build`, `agent`, and `version`. There is no `schema` or `migrate` command in the beta.

## auth [#auth]

Manage authentication.

| Command       | Description                                           |
| ------------- | ----------------------------------------------------- |
| `auth login`  | Log in to your Prisma platform account (browser flow) |
| `auth logout` | Clear stored authentication credentials               |
| `auth whoami` | Show the authenticated user and accessible workspace  |

The browser step in `auth login` needs a human. Afterwards, anything running in that environment inherits the session, including coding agents. For CI, set [`PRISMA_SERVICE_TOKEN`](#environment-variables) instead.

## init [#init]

Scaffold Compute configuration for the current directory. `init` detects your framework and writes `prisma.compute.ts` (or, with `--format json`, a dependency-free `prisma.compute.json`). The `app` commands read this file for app targets, framework, entry point, HTTP port, region, and env inputs.

| Flag                         | Description                                                                                                                              |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--framework <framework>`    | Framework override; detected when omitted                                                                                                |
| `--entry <path>`             | Source entrypoint for entrypoint frameworks (Bun, Hono)                                                                                  |
| `--http-port <port>`         | HTTP port the app listens on                                                                                                             |
| `--region <region>`          | Region used when deploy creates the app                                                                                                  |
| `--name <app-name>`          | App name                                                                                                                                 |
| `--link` / `--no-link`       | Link this directory to a project, or skip that step                                                                                      |
| `--project <id-or-name>`     | Project to link this directory to                                                                                                        |
| `--install` / `--no-install` | Install `@prisma/compute-sdk` for config types, or skip that step                                                                        |
| `--format <ts\|json>`        | `ts` (default) writes `prisma.compute.ts`; `json` writes `prisma.compute.json`; `--format ts` converts an existing `prisma.compute.json` |

## app [#app]

Manage apps and deployments for a project.

| Command                        | Description                                                                  |
| ------------------------------ | ---------------------------------------------------------------------------- |
| `app build`                    | Build the app locally into a deployable artifact                             |
| `app deploy`                   | Create a new deployment for the app                                          |
| `app show`                     | Show the app and its current deployment                                      |
| `app open`                     | Open the app's live URL                                                      |
| `app logs`                     | Stream logs for the app's current deployment                                 |
| `app list-deploys`             | List deployments for the app                                                 |
| `app show-deploy <deployment>` | Show a deployment in detail                                                  |
| `app promote <deployment>`     | Make a deployment live behind the app endpoint, starting it first if stopped |
| `app rollback`                 | Roll back production to the previous deployment, without rebuilding          |
| `app remove`                   | Remove the app from the current branch                                       |

Promote and rollback switch the live endpoint between existing deployments; nothing is rebuilt, and env vars stay as resolved when each deployment was created. Most `app` commands also accept an optional `[app]` positional argument to pick a target from `prisma.compute.ts` when the config defines multiple apps.

### app deploy options [#app-deploy-options]

| Flag                       | Description                                                                                                                                           |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--app <name>`             | Target a specific app; otherwise resolved from `PRISMA_APP_ID`, the app name in `prisma.compute.ts`, the `package.json` name, then the directory name |
| `--project <id-or-name>`   | Target a specific project                                                                                                                             |
| `--create-project <name>`  | Create and link a new project before deploying                                                                                                        |
| `--branch <name>`          | Deploy to a specific branch; otherwise your active Git branch, then `main`                                                                            |
| `--framework <name>`       | One of `nextjs`, `nuxt`, `astro`, `hono`, `nestjs`, `tanstack-start`, `custom`, `bun`                                                                 |
| `--entry <path>`           | Entry point, required for `bun` and useful when detection needs a hand                                                                                |
| `--http-port <port>`       | HTTP port your app listens on                                                                                                                         |
| `--region <region>`        | Region for a newly created app; existing apps keep their region                                                                                       |
| `--env <name=value\|file>` | Environment variable assignment or dotenv file for this deployment (repeatable); `--env` flags replace config env inputs entirely                     |
| `--prod`                   | Confirm intent to deploy to the production branch                                                                                                     |
| `--no-promote`             | Build the deployment without promoting it to live; promote later with `app promote <id>`                                                              |

After the first production deploy, every later production deploy needs `--prod`; without it the deploy fails with `PROD_DEPLOY_REQUIRES_FLAG`. With `--prod`, the CLI asks for confirmation; pass `-y` / `--yes` to accept it up front. In non-interactive mode, a `--prod` deploy without `--yes` fails with `CONFIRMATION_REQUIRED`. The first production deploy is auto-promoted and needs neither flag. A `--no-promote` deploy never replaces the live deployment, so the production gate does not apply.

### app build options [#app-build-options]

| Flag                  | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| `--entry <path>`      | Entry point for Bun apps                                                              |
| `--build-type <type>` | One of `auto`, `nextjs`, `nuxt`, `astro`, `nestjs`, `tanstack-start`, `custom`, `bun` |

### Other app options [#other-app-options]

| Flag                 | Applies to                                                                                                 | Description                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| `--app`, `--project` | most inspection and deploy commands (`app show-deploy` takes only the deployment id; `app build` is local) | Select the app or project explicitly  |
| `--deployment <id>`  | `app logs`                                                                                                 | Stream logs for a specific deployment |
| `--to <deployment>`  | `app rollback`                                                                                             | Roll back to a specific deployment    |
| `--yes`              | `app remove`, `--prod` deploys                                                                             | Accept the confirmation prompt        |

## app domain [#app-domain]

Manage custom domains for an app. All commands take a `<hostname>` argument plus `--app` / `--project` / `--branch`, and the optional `[app]` config target. Domains target the production branch; to learn more, see the [Domains docs](https://www.prisma.io/docs/compute/domains).

| Command                        | Description                                               |
| ------------------------------ | --------------------------------------------------------- |
| `app domain add <hostname>`    | Register a custom domain on the app's production branch   |
| `app domain show <hostname>`   | Show custom domain status and certificate details         |
| `app domain wait <hostname>`   | Wait until a custom domain is active or failed            |
| `app domain retry <hostname>`  | Retry custom domain DNS verification and TLS provisioning |
| `app domain remove <hostname>` | Detach a custom domain from the app                       |

`app domain wait` polls for up to 15 minutes by default; pass `--timeout <duration>` to change that, or `--timeout 0` for a single status check. In `--json` mode it streams newline-delimited status events.

## project [#project]

Manage projects and directory bindings.

| Command                     | Description                                   |
| --------------------------- | --------------------------------------------- |
| `project list`              | List all projects in your workspace           |
| `project show`              | Show this directory's project binding         |
| `project create <name>`     | Create a project and link the directory to it |
| `project link [id-or-name]` | Link the directory to an existing project     |

Linking writes `.prisma/local.json`, a gitignored local pin of the workspace and project. It is a cache, not committed config. Committed configuration lives in `prisma.compute.ts` (or `prisma.compute.json`), which [`init`](#init) writes and the `app` commands read.

## project env [#project-env]

Manage environment variables for the active project. Writes require an explicit scope: exactly one of `--role <production|preview>` or `--branch <git-name>`. To learn more, see the [Environment variables docs](https://www.prisma.io/docs/compute/environment-variables).

| Command                               | Description                                                                         |
| ------------------------------------- | ----------------------------------------------------------------------------------- |
| `project env add <KEY=value\|KEY>`    | Create a variable; pass just `KEY` to read the value from your environment          |
| `project env update <KEY=value\|KEY>` | Replace an existing variable's value; a bare `KEY` also reads from your environment |
| `project env list`                    | List variable names and metadata for a scope, never values                          |
| `project env remove <key>`            | Remove a variable from a scope (`rm` also works)                                    |

`add` and `update` also accept `--file <path>` to read `KEY=VALUE` assignments from a dotenv file, and every `project env` command takes `--project <id-or-name>`.

Values are write-only: encrypted at rest and never returned by any surface. They resolve at deploy time; redeploy to apply changes.

## branch [#branch]

Inspect platform branches for the resolved project without creating remote state. To learn more, see the [Branching docs](https://www.prisma.io/docs/compute/branching).

| Command       | Description                                     |
| ------------- | ----------------------------------------------- |
| `branch list` | List platform branches for the resolved project |

## database [#database]

Manage Prisma Postgres databases for the resolved project. Most commands take `--project <id-or-name>` and `--branch <git-name>`.

| Command                                   | Description                                                          |
| ----------------------------------------- | -------------------------------------------------------------------- |
| `database list`                           | List databases                                                       |
| `database show <database>`                | Show a database in detail                                            |
| `database create <name>`                  | Create a database; `--region` sets the Prisma Postgres region        |
| `database usage <database>`               | Show usage; `--from` / `--to` bound the period                       |
| `database restore <database>`             | Restore from a backup (`--backup`, `--source-database`, `--confirm`) |
| `database remove <database>`              | Remove a database (`--confirm <database-id>`)                        |
| `database backup list <database>`         | List backups (`--limit <n>`)                                         |
| `database connection list <database>`     | List connections                                                     |
| `database connection create <database>`   | Create a connection (`--name <name>`)                                |
| `database connection rotate <connection>` | Rotate a connection's credentials (`--confirm`)                      |
| `database connection remove <connection>` | Remove a connection (`--confirm`)                                    |

## git [#git]

Manage the GitHub repository connection. To learn more, see the [GitHub integration docs](https://www.prisma.io/docs/compute/github).

| Command                 | Description                                                                           |
| ----------------------- | ------------------------------------------------------------------------------------- |
| `git connect [git-url]` | Link the project to a GitHub repository; starts the GitHub App install flow if needed |
| `git disconnect`        | Stop push-triggered automation; keeps the project and existing branches               |

In `--json` / `--no-interactive` mode, `git connect` doesn't block: if the GitHub App isn't installed yet, it fails with `REPO_INSTALLATION_REQUIRED` and gives you the install URL.

## build [#build]

Inspect builds that run on the platform (git-push and Console deploys).

| Command                | Description                                                                                                                              |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `build logs <buildId>` | Stream logs for a platform build; `--follow` keeps streaming as the build runs, `--cursor <cursor>` resumes from a prior terminal cursor |

## agent [#agent]

Install and inspect Prisma agent skills; see [Agent skills](#agent-skills) below.

| Command         | Description                                                        |
| --------------- | ------------------------------------------------------------------ |
| `agent install` | Install Prisma skills for coding agents                            |
| `agent update`  | Update installed Prisma skills                                     |
| `agent status`  | Show installed Prisma skills; `--global` checks the user directory |

`agent install` and `agent update` take `--agent <agent>` (repeatable), `--all-agents`, `--skill <skill>` (repeatable), `--global`, `--copy`, and `--dry-run`.

## version [#version]

| Command   | Description                    |
| --------- | ------------------------------ |
| `version` | Show CLI build and environment |

## Global flags [#global-flags]

| Flag                                 | Description                                                       |
| ------------------------------------ | ----------------------------------------------------------------- |
| `--json`                             | Emit structured JSON output                                       |
| `-y`, `--yes`                        | Accept supported confirmation prompts                             |
| `-q`, `--quiet` / `-v`, `--verbose`  | Adjust output verbosity                                           |
| `--trace`                            | Show deeper diagnostics for failures                              |
| `--interactive` / `--no-interactive` | Force or disable prompts; non-interactive fails instead of asking |
| `--color` / `--no-color`             | Control colored output                                            |
| `--version`                          | Print the CLI version                                             |

## JSON output [#json-output]

In `--json` mode, every command returns an envelope you can branch on:

* `ok`: `true` or `false`.
* `result`: the command's data, when `ok` is `true`.
* `error.code`, `error.summary`, `error.why`, `error.fix`: what failed and what to do about it.
* `nextSteps` and `nextActions`: exact follow-up commands, useful for agents.

Branch on `error.code`, not the message text: codes are a stable contract, while message wording can change between releases.

## Agent skills [#agent-skills]

An agent skill teaches a coding agent the Compute deploy workflow. Install it into a repo with:

  

#### bun

```bash
bunx skills add prisma/skills --skill prisma-compute
```

#### pnpm

```bash
pnpm dlx skills add prisma/skills --skill prisma-compute
```

#### yarn

```bash
yarn dlx skills add prisma/skills --skill prisma-compute
```

#### npm

```bash
npx skills add prisma/skills --skill prisma-compute
```

This adds the `prisma-compute` skill to `.agents/skills/`, where supported agents pick it up. To install every Prisma skill at once, run `npx skills add prisma/skills`, or use the CLI's [`agent install`](#agent) command, which wraps the same flow. To learn more, see [Agent skills](https://www.prisma.io/docs/compute/getting-started#agent-skills) in the getting started guide.

## Environment variables [#environment-variables]

| Variable               | Description                                                                 |
| ---------------------- | --------------------------------------------------------------------------- |
| `PRISMA_SERVICE_TOKEN` | Authenticate without a browser (CI); takes priority over any stored session |
| `PRISMA_PROJECT_ID`    | Override the project resolved from `.prisma/local.json`                     |
| `PRISMA_APP_ID`        | Override the app resolution                                                 |

## Error codes [#error-codes]

The common codes, grouped by area:

**General**

| Code                    | Meaning                                                                                                               |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `AUTH_REQUIRED`         | No session or service token. Run `auth login` or set `PRISMA_SERVICE_TOKEN`.                                          |
| `CONFIRMATION_REQUIRED` | A confirmation prompt can't run here (e.g. a `--prod` deploy in non-interactive mode, or `app remove`). Pass `--yes`. |
| `USAGE_ERROR`           | Invalid arguments or flags. Check the command's `--help`.                                                             |
| `FEATURE_UNAVAILABLE`   | The platform can't serve this yet (e.g. logs for some deployments).                                                   |

**Projects and apps**

| Code                     | Meaning                                                      |
| ------------------------ | ------------------------------------------------------------ |
| `PROJECT_SETUP_REQUIRED` | No project resolved. Pass `--project` or `--create-project`. |
| `PROJECT_NOT_FOUND`      | The named project doesn't exist or isn't visible to you.     |
| `APP_AMBIGUOUS`          | More than one app matched. Pass `--app <name>`.              |
| `FRAMEWORK_NOT_DETECTED` | The CLI couldn't detect your framework. Pass `--framework`.  |

**Deployments**

| Code                        | Meaning                                                               |
| --------------------------- | --------------------------------------------------------------------- |
| `PROD_DEPLOY_REQUIRES_FLAG` | A production deploy is missing explicit intent. Re-run with `--prod`. |
| `BUILD_FAILED`              | The app failed to build. Check the build output.                      |
| `DEPLOY_FAILED`             | The deployment failed after the build.                                |
| `DEPLOYMENT_NOT_FOUND`      | The deployment id doesn't exist for this app.                         |
| `NO_PREVIOUS_DEPLOYMENT`    | Nothing to roll back to.                                              |

**Environment variables**

| Code                             | Meaning                                              |
| -------------------------------- | ---------------------------------------------------- |
| `ENV_VARIABLE_ALREADY_EXISTS`    | The key exists in this scope. Use `update` instead.  |
| `ENV_VARIABLE_NOT_FOUND`         | No variable with that key in this scope.             |
| `ENV_BRANCH_SCOPE_IS_PRODUCTION` | Branch overrides can't target the production branch. |

**Domains**

| Code                          | Meaning                                                            |
| ----------------------------- | ------------------------------------------------------------------ |
| `BRANCH_NOT_DEPLOYABLE`       | Domain commands targeted a non-production branch.                  |
| `DOMAIN_ALREADY_REGISTERED`   | The hostname is already registered.                                |
| `DOMAIN_DNS_NOT_CONFIGURED`   | The CNAME record isn't visible yet.                                |
| `DOMAIN_VERIFICATION_FAILED`  | DNS verification or TLS provisioning failed.                       |
| `DOMAIN_VERIFICATION_TIMEOUT` | `app domain wait` hit its timeout before the domain became active. |
| `DOMAIN_QUOTA_EXCEEDED`       | The app already has 3 custom domains.                              |
| `DOMAIN_RETRY_NOT_ELIGIBLE`   | The domain isn't in a retryable state.                             |

**GitHub**

| Code                         | Meaning                                                 |
| ---------------------------- | ------------------------------------------------------- |
| `REPO_NOT_CONNECTED`         | No repository connected. Run `git connect` first.       |
| `REPO_ALREADY_CONNECTED`     | The project is already connected to a repository.       |
| `REPO_INSTALLATION_REQUIRED` | The Prisma GitHub App isn't installed in the workspace. |
| `REPO_PROVIDER_UNSUPPORTED`  | `git connect` with a non-GitHub provider.               |

## Related [#related]

* [Get started with `@prisma/cli`](https://www.prisma.io/docs/compute/getting-started)
* [Known limitations](https://www.prisma.io/docs/compute/limitations)
* [Prisma ORM CLI reference](https://www.prisma.io/docs/cli) for the `prisma` binary

## Related pages

- [`@prisma/cli`](https://www.prisma.io/docs/compute/getting-started): Deploy your first app to Prisma Compute with the @prisma/cli beta package, then learn the variations you'll need next.
- [`Branching`](https://www.prisma.io/docs/compute/branching): Branches are isolated environments that map to your Git branches, so preview work never touches production.
- [`Configuration`](https://www.prisma.io/docs/compute/configuration): Declare your deployable app in a typed prisma.compute.ts file so deploys are reproducible and monorepos work, without re-passing flags every time.
- [`Deployments`](https://www.prisma.io/docs/compute/deployments): Build, deploy, inspect, promote, and roll back app deployments on Prisma Compute.
- [`Domains`](https://www.prisma.io/docs/compute/domains): Point a custom domain at a production app and the platform verifies DNS and provisions TLS for you.