---
title: "Configuration"
description: "Configure Playstack artifact targets, lint adoption, Skills installation, and managed updates in one committed file."
tags: ["cli","configuration","playstack-json","survey"]
---

The CLI reads `playstack.json` from the repository root. Commit this file so local work, CI checks, and managed update branches use the same package selections and ownership boundaries.

## Survey before initialization

```sh
npx playstack init --survey
```

Survey mode recognizes root and nested Nx projects, Next Pages and App Router applications, Nest APIs and workers, Redis and BullMQ usage, datasource-bearing Prisma contexts, generated schema derivatives, package-manager state, installed Playstack packages, and likely artifact destinations. It reports proposals without writing files or installing dependencies.

Use `--json` for one machine-readable object with no human prelude:

```sh
npx playstack init --survey --json
```

Run interactive initialization when the proposals look right:

```sh
npx playstack init
```

Initialization confirms every target before writing. Optional package scripts, a `doctor --check` CI step, and configured Skills installation are each proposed and confirmed independently.

### Exclude generated and unrelated directories

Survey discovery skips generated `.app`, `.app.dSYM`, and `.xcarchive` bundles, Rust `target` directories, `.contentlayer`, `.expo`, and `.turbo` output by default. Add repeatable repository-relative directory exclusions when needed:

```sh
npx playstack init --survey --json --exclude='.prismark/**' --exclude='scratch'
```

Patterns use `/` separators and apply to project-root and technology discovery. They cannot re-include generated output or bypass symlink exclusions. Inspect the survey before accepting proposals; discovery is not runtime qualification.

Utility packages do not require a capability recipe. For example, inspect `playstack info @playstack/crypto`, install the package and its dependencies with your existing package manager, and use its supported `/primitives` entry point directly. The CLI does not replace dependency ownership or application composition.

## Configuration reference

```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 JSON Schema shipped with the installed CLI.                          |
| `databases.<name>.adapter`                              | `prisma \| drizzle`                             | Selects the schema representation accepted by this named target.                           |
| `databases.<name>.dialect`                              | `postgresql?`                                   | Required for Drizzle and omitted for Prisma.                                               |
| `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.                                            |
| `databases.<name>.packages.<package>.artifacts`         | `string[]?`                                     | Restricts synchronization to named manifest artifact IDs.                                  |
| `databases.<name>.packages.<package>.existingArtifacts` | `string[]?`                                     | Declares artifacts that the existing schema must fully satisfy before they can be skipped. |
| `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 scoped presets.                            |
| `skills.targets`                                        | `string[]`                                      | Selects repository-relative destinations for the Skills corpus.                            |
| `skills.overrides`                                      | `Record<skillId, path>?`                        | Shadows packaged guidance with a user-owned 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 eligible managed updates.                                                |

## Path and schema guarantees

Every target and override must be a relative path confined to the repository. Absolute paths and parent traversal fail before the CLI writes anything.

Invalid types and malformed values fail configuration loading. Unknown keys warn during the preview period so a typo is visible without blocking forward-compatible experimentation; the published schema supplies editor completion and validation.

Artifact commands can establish one missing target interactively. See [Artifact synchronization](/docs/cli/artifact-synchronization) for that focused workflow.

If exactly one database is configured, `database sync` selects it automatically. With several databases, interactive use prompts for a target and automation must provide `--database=<name>`.

Database package options can select individual artifacts or ask Playstack to verify that application-owned storage already satisfies them:

```json
{
  "databases": {
    "primary": {
      "adapter": "prisma",
      "target": "prisma/playstack",
      "packages": {
        "@playstack/accounts": {
          "scope": "account",
          "existingArtifacts": ["accounts.prisma"]
        },
        "@playstack/auth": {
          "artifacts": ["auth.prisma"]
        }
      }
    }
  }
}
```

Unknown, incompatible, duplicate, or overlapping artifact IDs fail before mutation. `existingArtifacts` is fail-closed: a package artifact is skipped only after the existing schema satisfies its physical storage contract.

Use named `databases` with an explicit `adapter`. A top-level `prisma` object is unsupported and rejected before artifact writes.