---
title: "Playstack CLI"
description: "Capability adoption, artifact synchronization, drift detection, merge orchestration, and authenticated application controls."
tags: ["package","cli","tooling","adoption","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@playstack/cli` installs explicit capability recipes, synchronizes package-owned artifacts, detects drift, and operates configured application controls without hiding generated files or application ownership.

## CLI guides

| Guide                                                          | Use it to                                                                                                            |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| [Configuration](/docs/cli/configuration)                       | Understand `playstack.json`, project survey, paths, and package selection.                                           |
| [Artifact synchronization](/docs/cli/artifact-synchronization) | Preview, write, and verify package-owned database-schema, email, content, and translation artifacts.                 |
| [Existing schema adoption](/docs/cli/existing-schema-adoption) | Compare a mature Prisma schema, declare satisfied artifacts, and choose an application adapter when storage differs. |
| [Integration planning](/docs/cli/integration-planning)         | Inspect package-authored routes, environment, framework, health, test, and ejectable wiring requirements.            |
| [Using Playstack with Megamono](/docs/megamono)                | Let Megamono own repository placement while Playstack owns capability package and artifact correctness.              |
| [Ejection and merging](/docs/cli/ejection-merging)             | Transfer ownership of an ejectable artifact and reconcile later upstream changes.                                    |
| [Lint and Skills](/docs/cli/lint-skills)                       | Install deterministic checks and repository-local agent guidance.                                                    |
| [Updates and CI](/docs/cli/updates-ci)                         | Update fixed package versions and generate the scheduled review workflow.                                            |

Each guide documents one ownership boundary. Start here for the complete command surface, then follow the focused guide when you are configuring that workflow.

## Install as tooling

```sh
npm install --save-dev @playstack/cli
```

Keep every installed `@playstack/*` package on the same fixed version. Commit `playstack.json`, managed output, and `.playstack` state so builds do not depend on running a generator first.

Inspect the executable and compatibility contracts independently:

```sh
playstack --version
playstack version
playstack version --json
```

`--version` and `-V` print the installed CLI package version. `version` also reports the supported `playstack.json` schema, artifact-manifest schema, Node range, source revision, source dirty state, and content-derived build ID; JSON output is stable for other tools and distinguishes republished prerelease builds.

## Initialize and synchronize

```sh
npx playstack init --survey
npx playstack init
npx playstack database compatibility --database=primary
npx playstack database sync --dry-run
npx playstack database sync
npx playstack lint init --diff
npx playstack skills sync --diff
npx playstack doctor --check
```

`init --survey` reports recognized project markers, installed packages, and proposed destinations without writing. Interactive `init` confirms targets and writes configuration only; it does not install packages or run a sync.

## Configuration

```json
{
  "$schema": "./node_modules/@playstack/cli/playstack.schema.json",
  "databases": {
    "primary": {
      "adapter": "prisma",
      "target": "prisma/playstack",
      "packages": {
        "@playstack/accounts": { "scope": "account" },
        "@playstack/events-prisma": {}
      }
    }
  },
  "emails": {
    "target": "src/emails/playstack",
    "packages": ["@playstack/auth"]
  },
  "content": { "target": "content/playstack" },
  "i18n": { "target": "src/i18n/playstack" },
  "lint": {
    "target": "eslint.playstack.config.mjs",
    "recommended": true,
    "chakra": {
      "files": ["src/**/*.{ts,tsx}"],
      "tokens": ["fg.default", "bg.canvas", "border.default"]
    }
  },
  "skills": {
    "targets": [".agents/skills"],
    "overrides": {
      "event-design": ".playstack-overrides/event-design"
    }
  },
  "updates": {
    "gitHost": "github",
    "schedule": "0 9 * * 1",
    "requiredCheck": "test",
    "autoMerge": false
  }
}
```

| Property                    | Type                                            | Purpose                                                                    |
| --------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------- |
| `$schema`                   | `string?`                                       | Points editors to the published JSON Schema.                               |
| `databases.<name>.adapter`  | `prisma \| drizzle`                             | Selects the schema representation accepted by this named target.           |
| `databases.<name>.dialect`  | `postgresql?`                                   | Required for Drizzle targets and omitted for Prisma targets.               |
| `databases.<name>.target`   | Relative path                                   | Destination for composed database-schema artifacts.                        |
| `databases.<name>.packages` | Package array or package-to-options map         | Selects emitters and optional package variants.                            |
| `emails`, `content`, `i18n` | `{ target, packages? }`                         | Selects an artifact kind, destination, and optional emitter allowlist.     |
| `lint`                      | `{ target, recommended?, extension?, chakra? }` | Configures the managed flat ESLint fragment and explicitly scoped presets. |
| `skills.targets`            | `string[]`                                      | Selects repository-relative destinations for the Skills corpus.            |
| `skills.overrides`          | `Record<skillId, path>?`                        | Shadows a packaged skill with a user-owned repository directory.           |
| `updates.gitHost`           | `github`                                        | Pull-request host used by managed updates.                                 |
| `updates.schedule`          | Cron string                                     | Schedule written by `playstack ci init`.                                   |
| `updates.requiredCheck`     | `string`                                        | Existing workflow job required before managed merge.                       |
| `updates.autoMerge`         | `boolean`                                       | Opt-in policy for managed minor and patch updates.                         |

Every target must remain inside the project. Unknown keys warn; invalid types and unsafe paths fail before writing.

## Artifact bridge

Packages that emit application files publish `playstack.artifacts.json`. Each artifact declares:

| Property            | Meaning                                                         |
| ------------------- | --------------------------------------------------------------- |
| `id`                | Stable identifier within the package.                           |
| `kind`              | `database-schema`, `content`, `emails`, `i18n`, or `source`.    |
| `format`            | Required database-schema representation: `prisma` or `drizzle`. |
| `dialect`           | Required for Drizzle schema artifacts; currently `postgresql`.  |
| `source` / `target` | Package-relative source and default application destination.    |
| `variant`           | Optional selectable schema or output variant.                   |
| `ejectable`         | Whether ownership may move to the application.                  |
| `securityCritical`  | Prevents ejection and requires package-managed updates.         |
| `hash`              | SHA-256 integrity check for the published source.               |

Managed files reject local drift. Ejected files record their original base under `.playstack/base` and use `git merge-file` for later three-way updates; conflicts do not overwrite the application file.

## Lint and Skills

The CLI can adopt the separately installed `@playstack/lint` and `@playstack/skills` packages without making either one a CLI runtime dependency.

```sh
npm install --save-dev @playstack/lint @playstack/skills
npx playstack lint init --diff
npx playstack lint init
npx playstack skills sync --diff
npx playstack skills sync
```

`lint init` emits a managed flat ESLint fragment. The recommended preset starts as warnings so a repository can ratchet adoption deliberately. Extension and Chakra rules require explicit file globs; Chakra may additionally restrict the semantic tokens available at that boundary.

`skills sync` installs the declared Markdown corpus into each configured target and records its state in `.playstack/skills.json`. Package content is hash-verified, local edits are reported as unsafe, and an explicit override can shadow one stable skill ID without changing its managed source. See the [Skills overview](/skills) and [`@playstack/skills` reference](/docs/packages/foundation/skills) for the full corpus.

## Complete command surface

| Command                                      | Purpose                                                                                                |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `--version`, `-V`                            | Print the installed executable package version.                                                        |
| `version [--json]`                           | Report CLI, configuration-schema, artifact-schema, and Node compatibility versions.                    |
| `help [command]`, `[command] --help`         | Explain command usage, arguments, flags, defaults, and examples without requiring a project.           |
| `init [--survey]`                            | Inspect a repository, then confirm and write configuration and optional maintenance hooks.             |
| `add <capability>`                           | Install a versioned package recipe and optional web or API bindings.                                   |
| `info [topic]`                               | Explain capabilities, packages, and operations without requiring repository configuration.             |
| `database compatibility [--database=<name>]` | Compare selected Prisma artifacts with an existing schema without writing or connecting to a database. |
| `database sync [--database=<name>]`          | Materialize schema artifacts into a selected named target.                                             |
| `emails init`, `content init`, `i18n init`   | Initialize the selected package-owned artifact kind.                                                   |
| `lint init`                                  | Emit or verify the managed Playstack ESLint fragment.                                                  |
| `skills sync`                                | Install or verify repository-local agent guidance.                                                     |
| `event-store replay\|status\|cancel`         | Operate projection replay through an authenticated, application-owned gateway.                         |
| `adapter scaffold <package>`                 | Materialize an application-owned persistence adapter with typed method stubs and contract-test seams.  |
| `eject`, `merge`                             | Transfer ownership of an ejectable artifact and reconcile later upstream changes.                      |
| `doctor`                                     | Check managed artifacts, lint, Skills, and ejected upstream state together.                            |
| `update [--pr]`                              | Update fixed Playstack versions and optionally partition changes into review branches.                 |
| `ci init`                                    | Emit the scheduled update workflow from committed policy.                                              |
| `feedback [message]`                         | Send a bug report, idea, or question to the Playstack API; `--last` attaches the last failed command.  |

## Capability recipes

`playstack add` currently knows 24 recipes: `accounts`, `analytics`, `audiences`, `audit`, `auth`, `auth-client`, `billing`, `cache`, `commerce`, `connections`, `content`, `delivery`, `devices`, `errors`, `events`, `licensing`, `local-first`, `mail`, `notifications`, `queues`, `rate-limit`, `search`, `storage`, and `validation`. Use `playstack add --list --json` for the versioned catalog and `playstack info <capability>` to inspect prerequisites, portable packages, optional web and API surfaces, supported database adapters, and provider choices before installation.

```sh
npx playstack add commerce --api=apps/api --database=primary --yes
npx playstack add notifications --web=apps/web --api=apps/api --database=primary --yes
npx playstack add search --web=apps/web --api=apps/api --adapter=minisearch --yes
npx playstack info commerce --json
```

`auth-client` installs the session contract and client-side web surfaces without credentials, persistence, Argon2, Auth.js, or a Nest server. Other provider-bearing recipes select adapters explicitly; no provider is installed merely because it was current when the package was authored.

The CLI installs package closures and records explicit targets; it does not directly generate controllers, routes, modules, migrations, or application composition roots. `add --dry-run --json` includes integration manifests and ejectable templates for Megamono or another repository generator to materialize as application-owned wiring. Third-party dependencies are installed through your repository's package manager.

## Feedback

`playstack feedback "message"` sends a bug report, idea, or question to the Playstack API. Nothing is sent without an explicit command: after a failed command the CLI prints a hint suggesting `playstack feedback --last`, which attaches the redacted failure record (command, exit code, message, CLI and Node versions) to the report. Set `PLAYSTACK_FEEDBACK_HINT=0` to silence the hint.

```sh
npx playstack feedback "The add command hung on pnpm install" --category=bug
npx playstack feedback --last
npx playstack feedback "Support Bun" --category=idea --dry-run
npx playstack feedback --resend
```

`--category` is one of `bug`, `idea`, `question`, or `other`; `--contact` adds an e-mail address for follow-up; `--dry-run` prints the report instead of sending it. Reports go to `https://api.playstack.dev/v1/feedback` unless `PLAYSTACK_FEEDBACK_URL` or `--endpoint=<url>` overrides it. If delivery fails the report is saved locally and `playstack feedback --resend` retries it later. The intake is defined by [`@playstack/feedback`](/docs/packages/events-operations/feedback) and served by [`@playstack/nest-feedback`](/docs/packages/events-operations/nest-feedback).

## Updates and CI

```sh
npx playstack update --dry-run
npx playstack update
npx playstack update --pr
npx playstack ci init
```

`update` is the explicit network and package-manager boundary. It updates only installed `@playstack/*` dependencies, synchronizes managed output, and attempts safe ejected-file merges. `--pr` additionally requires a clean tracked worktree and delegates review creation to the configured host adapter.

## Boundary

Artifact operations, information, and initialization are offline. `add` and `update` are explicit package-manager network boundaries; event-store commands are the explicit application-control network boundary. The CLI does not scaffold applications, run database migrations or schema push, connect to a database, or hide generated files.

Use named `databases` and `playstack database sync`. Superseded pre-release configuration and command aliases are not supported.

{/* package-reference:start */}

## API entry points and requirements

Reference snapshot: `@playstack/cli@0.1.0-beta.1`. Import only the entry point your runtime needs. Paths below are relative to the installed package; use **Go to Definition** in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/cli` | `./dist/index.d.ts` |
| `@playstack/cli/playstack.schema.json` | No TypeScript declaration (asset or metadata export). |
| `@playstack/cli/playstack.integration.schema.json` | No TypeScript declaration (asset or metadata export). |
| `@playstack/cli/playstack.integrations.json` | No TypeScript declaration (asset or metadata export). |
| `@playstack/cli/playstack.catalog.json` | No TypeScript declaration (asset or metadata export). |
| `@playstack/cli/package.json` | No TypeScript declaration (asset or metadata export). |

Node.js engine requirement: `>=20`. This is not a claim that every entry point works in browsers or Workers.

### Peer dependencies

This package declares no peer dependencies. Its ordinary dependencies are resolved by the package manager.

For a complete first program, start with [Getting started](/docs/getting-started). For API lookup and partial-example conventions, see [Reading the reference](/docs/packages#reading-the-reference). Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.

{/* package-reference:end */}