CLI & project config
CLI & project config
The crouton CLI keeps your resource.json files in sync with your database. It introspects a datasource's Prisma schema, then generates new resources and reconciles existing ones β interactively, so you stay in control of every change.
pnpm add -D @ghentcdh/crouton-cli
npx crouton update resourcesCommands
Every command is verb β noun. A bare verb runs all of its nouns.
| Command | What it does |
|---|---|
crouton update | Runs update resources, then update translations (asks once). |
crouton update resources | Introspect the database and create/update resource.json files. |
crouton update translations | Regenerate and merge translation bundles (--lang, --prune). |
crouton init translations | Create translation files for every configured language (--lang). |
crouton create | Asks whether to create a resource, a datasource or a project. |
crouton create resource [name] | Scaffold a custom resource. |
crouton create datasource | Scaffold a new datasource. |
crouton create project [name] | Add a project to an existing codespace (below). |
crouton validate | Validate every discovered resource.json, nested sub-resources too. |
crouton validate resources [pathsβ¦] | Validate the given files/directories (--json). |
crouton migrate | Runs migrate resources, then migrate layout (asks once). |
crouton migrate resources | Rewrite every resource.json to the current shape (upgrading). |
crouton migrate layout | Rewrite only layout nodes (controls β items, actions β rowActions, β¦). |
Common options, accepted by every command that touches a project:
| Option | Effect |
|---|---|
--cwd <dir> | Project directory (defaults to the current directory). |
-p, --project <name> | Project to use: a subfolder of --cwd holding a crouton.json. |
--dry-run | Show the planned changes without writing files. |
-y, --yes | Accept all recommended defaults (non-interactive). |
Aggregates (crouton update, crouton migrate, β¦) only take the common options; noun flags such as --prune or --datasource stay on the nouns and are never applied implicitly.
Choosing a project
Every command works on one project β a folder with a crouton.json. It is resolved once per invocation:
--project <name>β the subfolder of--cwdwith that name (an unknown name lists the available ones).- The current directory, or one of its parents, has a
crouton.jsonβ that project. - Otherwise the immediate subfolders of the current directory are scanned: one project is used as-is, several open a picker. With
-y(orvalidate resources --json) several projects are an error that lists them β pass--project.
# monorepo with apps/ and admin/ each holding a crouton.json
cd my-workspace
npx crouton update resources --project admincrouton.json
A crouton.json file at the project root tells the CLI where things live. It holds only project-wide paths and settings β datasources are described in their own folders (see Data sources), not here.
{
"title": "My App",
"resourcesDir": "apps/backend/src/app/resources",
"dataSourcesDir": "apps/backend/src/app/data-sources",
"sidebarGroups": {
"catalogue": { "label": "Catalogue", "position": 1 }
},
"i18n": { "languages": ["en", "nl"], "defaultLanguage": "en" }
}title, resourcesDir and dataSourcesDir are required; everything else is optional. sidebarGroups is an object keyed by group slug. See the crouton.json reference for the full field list and defaults.
If no crouton.json is found, the CLI proposes one (and a data-source.json per detected datasource) and offers to write it.
crouton create datasource
Scaffold a new datasource β interactively, or fully via flags:
npx crouton create datasource
# or scripted:
npx crouton create datasource \
--name analyticsdb \
--url-env ANALYTICS_DATABASE_URL \
--generated-import @my-app/generated/analyticsdbIt reads crouton.json for dataSourcesDir, checks the name isn't already taken, and writes four files (never overwriting existing ones):
| File | Purpose |
|---|---|
<dataSourcesDir>/<name>/data-source.json | Self-describing datasource config. |
<dataSourcesDir>/<name>/index.ts | Runtime PrismaClient, connecting via the chosen env var. |
prisma/<name>/schema.prisma | Per-datasource schema with unique client and zod outputs, so multiple datasources never collide. |
prisma/<name>/prisma.config.ts | Binds this datasource's urlEnv (Prisma 7 reads the URL here, not from the schema). |
Without flags it asks for the name, the adapter (prisma or custom), the database type (Prisma only), the connection env var and the generated-types import. The first datasource in a project becomes the default; later ones are non-default unless you pass --default (and only one datasource may be default). Useful flags: -a/--adapter (prisma/custom), --type (postgres/mysql/sqlite/β¦), --zod-output, --prisma-schema, --prisma-config, --client-output, --cwd, --dry-run, -y/--yes.
After scaffolding: add the urlEnv to your .env, map the generatedTypesImport to the zod output in your tsconfig paths / workspace, then run crouton update resources --datasource <name>.
crouton create resource
Scaffold a custom resource β one whose form, table and view are configured declaratively while you implement the data access.
npx crouton create resource zotero_itemWithout flags it asks for the name, route, tag, title (each prefilled with its default β press Enter to keep it), the datasource for ctx.prisma and the primary-key type; -y keeps every default. Writes two files, and never overwrites an existing one:
resources/zotero_item/
βββ resource.json # "kind": "custom"
βββ repository.ts # typed stub, one TODO per operation| Flag | Description |
|---|---|
-k, --kind <kind> | Only custom is supported β prisma-backed resources come from crouton update resources |
-r, --route <route> | URL segment (defaults to the name) |
-t, --tag <tag> | OpenAPI tag |
--title <title> | UI title |
-d, --datasource <name> | Datasource exposed to the repository as ctx.prisma (--database is a deprecated alias) |
--id-type <type> | string (default) or number |
--cwd <dir> | Project directory |
-p, --project <name> | Project to use (choosing a project) |
--dry-run | Show the planned files without writing |
-y, --yes | Accept all defaults (non-interactive) |
crouton create project
Add another project β a backend app with its default datasource, plus an optional Vue frontend β to a codespace made with create-crouton. Run it from the codespace root:
npx crouton create project archive
npx crouton create project archive --dry-run # list the files firstIt asks the same questions as create-crouton (frontend, database URL) but skips everything workspace-wide: no root config, git init or dependency install. The layout is detected, not asked:
| Layout | What it writes |
|---|---|
Nx (nx.json at the root) | A workspace under archive/ (like create-crouton --prefix archive): crouton.json, .env, apps/backend, apps/frontend, generated/default, Dockerfiles, plus compose.app.archive.yml at the root. It registers the project in pnpm-workspace.yaml, tsconfig.base.json (@archive/generated-default-* paths) and the root compose.yml include. |
Regular (package.json + crouton.json) | A standalone NestJS app in archive/ with its own package.json and Docker files. The root app is left untouched. |
Backend and frontend ports are the next free ones after those found in the root and per-project .env / compose.app.*.yml files (3000/4200 count as taken). The new compose file joins the codespace's Docker network.
| Flag | Description |
|---|---|
--frontend / --no-frontend | Include the Vue frontend (Nx only; asked when omitted, default yes with -y) |
--db-url <url> | Connection URL written to the project's .env (default: a database named after the project on localhost:5432) |
--no-docker | Skip Docker files |
--backend-port <n>, --frontend-port <n> | Override the detected free ports |
--cwd <dir> | Codespace root |
--dry-run | List the files without writing |
-y, --yes | Accept all defaults (non-interactive) |
--force | Write into a non-empty project folder |
Afterwards: create the database if needed, run pnpm install (regular: inside archive/), then crouton update resources --project archive.
crouton update resources
The command walks through:
- Pick a datasource β discovered by scanning
dataSourcesDir. Skipped when there's a single ordefaultdatasource, or pass--datasource <name>. prisma db pullβ refreshes the datasource's schema using itsprismaConfig. The current schema is backed up first; the CLI warns if it has uncommitted changes.prisma-case-formatβ automatically converts model names to PascalCase and field names to camelCase, adding@@map/@mapannotations to preserve the original database names. This means your Prisma client uses idiomatic TypeScript casing (Work,createdAt) while the database keeps its original naming (work,created_at).normalizeSchemaβ renames ugly auto-generated relation field names using anormalize-schema.jsonfile placed next toschema.prisma. Skipped when the file does not exist.prisma generateβ regenerates Zod types from the formatted schema.- Pick models β choose which Prisma models to generate or update (existing ones are marked).
- Resolve changes β for each new column or change, choose per resource how to apply it: keep existing, overwrite, merge, or decide per field. New resources can be added to the sidebar.
- Preview & confirm β only changed files are listed; nothing is written until you confirm.
Useful flags:
| Flag | Effect |
|---|---|
--datasource <name> | Use a specific datasource. |
--models <a,b> | Limit to specific models (Prisma or resource names). |
--dry-run | Show the plan without writing. |
--yes | Non-interactive; accept recommended choices. |
--skip-pull / --skip-generate | Skip the Prisma steps. |
--draft | Write new resources with draft: true (hidden until reviewed). |
What gets generated
For each model, the CLI writes a resource.json (columns as a map, sensible defaults applied) and, when absent, a sibling schema.ts that re-exports the generated Zod schema from the datasource's generatedTypesImport. A hand-written schema.ts is never overwritten.
Every generated resource.json is stamped with a $schema URL and the current schemaVersion (see Versioning), so it validates and autocompletes in your editor and starts at the current version.
Defaults applied during generation:
- new resources are written without
draft: trueby default and served immediately β pass--draftto mark them as hidden until reviewed, then flipdrafttofalse(or remove it) when ready. See Draft resources; - relations are ignored (not added as columns) unless explicitly enabled;
id, and create/update timestamps are hidden in the table;description-style string fields default to atextareainput;- enum columns become
{ value, label }selects backed by the shared registry.
Tips
crouton update resources ignores custom resources. They have no Prisma model, so introspection would see every column as missing from the database and offer to remove it.
Enum registry
Enum option lists live once in a project-level crouton.enums.json so every resource references the same labels instead of duplicating them:
{
"author_origin_enum": [
{
"value": "wikidata",
"label": "Wikidata"
},
{
"value": "syriaca",
"label": "Syriaca",
"disabled": true
}
],
"text_type_enum": [
{
"value": "original",
"label": "Original"
},
{
"value": "translation",
"label": "Translation"
}
]
}A column references a list by name:
{
"text_type": {
"enum": "text_type_enum",
"displayKey": "label",
"fieldInput": {
"options": {
"emitObject": true
}
}
}
}At load time the referenced list is injected into the column's options, so the table shows the label while forms submit the scalar value. crouton update resources merges newly discovered enum values into the registry, preserving labels and order you've edited by hand and never dropping existing entries.
The registry is loaded by walking up from the resources directory, or via the enumsFile option to forResourceDir (see Backend setup). In production, deploy crouton.enums.json somewhere that walk-up can reach, or pass enumsFile explicitly.
Keeping the CLI fresh
When you consume crouton via file: links, package managers install a copy of the built CLI, not a live link to dist. After rebuilding crouton, re-run your install (e.g. pnpm install / pnpm install --force) so the binary you run is the rebuilt one.