Playstack CLI

@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

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

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:

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

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

{
  "$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
  }
}

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:

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.

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 and @playstack/skills reference for the full corpus.

Complete command surface

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.

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.

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 and served by @playstack/nest-feedback.

Updates and CI

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.

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.

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. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.