Playstack CLI
Capability adoption, artifact synchronization, drift detection, merge orchestration, and authenticated application controls.
Reference: @playstack/cli@0.1.0-beta.5 · TypeScript · MIT licence
Free. MIT licensed. Check preview availability before installing. See package access.
@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 | Understand playstack.json, project survey, paths, and package selection. |
| Artifact synchronization | Preview, write, and verify package-owned database-schema, email, content, and translation artifacts. |
| Existing schema adoption | Compare a mature Prisma schema, declare satisfied artifacts, and choose an application adapter when storage differs. |
| Integration planning | Inspect package-authored routes, environment, framework, health, test, and ejectable wiring requirements. |
| Using Playstack with Megamono | Let Megamono own repository placement while Playstack owns capability package and artifact correctness. |
| Ejection and merging | Transfer ownership of an ejectable artifact and reconcile later upstream changes. |
| Lint and Skills | Install deterministic checks and repository-local agent guidance. |
| Updates and 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
npm install --save-dev @playstack/cliKeep 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 --checkinit --survey reports recognized project markers, declared packages, and proposed destinations without writing. Interactive init confirms targets and writes configuration only; it does not install packages or run a sync.
Workspace discovery and source ownership
Survey combines dependency declarations from the root and included workspace
manifests. It does not prove installation or runtime compatibility. Ordinary
artifact discovery and doctor remain root-local: install artifact-owning
packages beside the configuration that owns their output, or run from an owning
workspace with its own configuration and relative targets. Nested runtime
dependencies alone do not make artifacts root-resolvable under strict pnpm.
playstack add <capability> --local-packages=yalc --dry-run resolves the full
local Playstack closure before mutation. Existing archive overrides such as
file:vendor/*.tgz are deliberate source conflicts, not equivalent local Yalc
references. Review and explicitly change only the selected conflicting override
before rerunning the dry-run; the CLI does not silently replace repository pins.
Preserve unrelated policy, commit the reconciled lockfile and qualify exact
replacement bytes with a frozen install. Local Yalc publication is development
distribution, not evidence of a registry release or fresh-builder availability.
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
}
}| 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.
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 synclint 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
| 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.
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 --jsonauth-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 initupdate 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.5. 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. 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.