Workspace

For anything beyond a single call, work a local workspace rather than issuing commands one at a time. pull materialises the organization into reviewable files, push reports what applying them would change, and --apply commits it.

minima pull
minima push
minima push --apply
minima push minima/entities --apply

push writes nothing without --apply. Positional paths narrow the plan to those files or directories.

What pull writes

pull writes a minima/ directory of .jsonc files, plus a .minima/ cache it uses as the baseline for the next pull:

minima/
├── entities/<Type>/<slug>.jsonc
├── entity-types/<key>.jsonc
├── categories/<slug>.jsonc
├── images/<slug>.jsonc
└── sites/<site>/
    ├── site.jsonc
    ├── pages/<slug>.jsonc
    ├── articles/<slug>.jsonc
    └── menus/<slug>.jsonc

The files are JSONC, so comments you add survive a later pull. Anything under sites/ that does not match one of those shapes is reported rather than skipped — a plan that quietly ignored a file would claim the workspace agrees with the API about a record it never read.

Add .minima/ to .gitignore; it is a cache, not source.

Reviewing and applying

A plain push prints the plan: what would be created, updated, or left alone. Read it, then apply:

minima push --json     # the plan, machine-readable
minima push --apply

A failed apply and a clean one both write a report to stdout, with the failures inside it — they are distinguished by the exit code, so check it in scripts rather than assuming a written report means success.

Round-tripping

pull keeps its merge baseline under .minima/, so a later pull can tell a local edit from an upstream change and merge instead of overwriting. A key the server dropped — a cleared attribute — is removed from your file rather than left behind, so push cannot resurrect it later.

Images are pulled and pruned like everything else, but push does not plan them: no operation converges an image file. Upload and publish images with minima images upload and minima images publish.