Commands

Almost every command is projected from the API’s own operations. The flags, their help text, which fields are positional, and how the request is assembled all come from the operation’s declaration, so the help you get describes the surface your organization actually has.

Discovery is the same registry read back:

minima --help
minima entities --help
minima entities publish --help

The command groups are articles, categories, collections, email-campaigns, email-lists, entities, entity-types, images, menus, pages, permalinks, relationships, screenshot, short-links, site-categories, sites, subscribers, tags and units, plus pull and push and papercut.

Output

Commands print readable text by default. Add --json anywhere in a command for one machine-readable JSON document, which is the preferred mode for scripts and agents. --text selects the default explicitly.

minima sites list --json

Errors are written to stderr in text mode, and to stdout as JSON in JSON mode.

Dry runs

--dry-run prints the request a command would send — method, resolved path, headers, body — and sends nothing. It is the same assembly the real call makes, so what it prints is what would go:

minima entities publish <entityId> --sites <siteId> --dry-run --json

Flags and values

Path parameters are positional, in path order. A field the API declares as a list of scalars repeats, and a single value needs no ceremony:

minima entities publish <entityId> --sites <siteId>
minima entities publish <entityId> --sites <siteId> --sites <anotherSiteId>

A field declared as an object, or as a list of objects, arrives as a JSON string, because a shell flag has no better way to carry a nested document:

minima entities create --name Afterimage --type Release \
  --body '{"type":"doc","content":[]}'

A JSON payload does not have to travel in argv, where it has to survive shell quoting and ARG_MAX. On any JSON-carrying flag, @path reads the file and @- reads stdin, following curl. Plain string flags are left alone, so a name that begins with @ is a name:

minima entities create --name Afterimage --type Release --body @body.json
generate-body | minima entities create --name Afterimage --type Release --body @-

Two parser edges are worth knowing. A value that begins with - is read as the next flag, so pass it as --name=-x; the CLI refuses the emptied flag rather than sending the request without it. And a flag the operation does not declare is refused, so a renamed flag fails loudly instead of doing nothing.

Entities

minima entities create --name Afterimage --type Release --slug afterimage \
  --attributes '{"releaseDate":"2026-07-22","catalogNumber":"MIN-001"}'
minima entities list --type Repository
minima entities update <entityId> --name "Renamed entity"

name is required. type and the shape of attributes come from the organization’s entity type registry and are validated by the API at runtime; read them with minima entity-types list and minima entity-types get <id>.

attributes merges: supplied keys are added or updated, omitted keys are preserved, and a null value clears one.

minima entities update <entityId> --attributes '{"repoCreatedAt":null}'

Pass --expected-etag with the value from a prior read to make the write conditional; a stale token is rejected rather than silently overwriting.

Publishing

Publishing puts an entity on a site. Reserving a canonical permalink for it is a separate choice, and it is off unless asked for:

minima entities publish <entityId> --sites <siteId>
minima entities publish <entityId> --sites <siteId> --create-permalinks

The first creates site visibility and returns permalinks: []. The entity can be enumerated by the site’s public entity API, but no slug is required and no canonical path is reserved. The second mints a canonical permalink per site, and needs the entity to have a slug.

Images stay private until they are published explicitly:

minima images publish <imageId>

Relationships

minima relationships list --entity-id <entityId>
minima relationships create --entity-id <entityId> \
  --related-entity-id <relatedEntityId> --relationship contains
minima relationships delete <relationshipId>

Categories

minima categories list
minima categories create --name News --slug news
minima categories publish <siteId> <categoryId> --description "Product news."
minima categories unpublish <siteId> <categoryId>
minima entities categories add <entityId> --category-id <categoryId>

Publishing is per site, so the site comes first: the operation is /sites/{siteId}/categories/{id}, and path parameters are positional in path order. Publishing one category to several sites is a loop over publish — check each exit code before continuing, so a partial failure does not become a duplicate on retry.

Entity types and properties

minima units list --namespace minima
minima units create --key kg --label Kilograms
minima entity-types create --key Repository --label Repository --visibility private
minima entity-types properties add <entityTypeId> \
  --key firstCommitAt --label "First commit at" --type date
minima entity-types properties add <entityTypeId> \
  --key status --label Status --type enum \
  --options '[{"label":"Draft","value":"draft"},{"label":"Live","value":"live"}]'
minima entity-types properties add <entityTypeId> \
  --key owner --label Owner --type relationship \
  --allowed-types '["Person","Organization"]'
minima entity-types properties update <entityTypeId> <propertyId> --unit-id <unitId>

Generating a typed SDK

The CLI is the portable runtime surface. For a compile-time typed client, generate one from your organization’s OpenAPI document — the generator is a build-time dependency of your project, not part of the CLI.