Minima CLI

minima is a command-line client for the Minima API. It is designed for agents, scripts, and people who want a direct, machine-readable way to manage an organisation's content.

Alpha status

This package is an alpha. Its command and API surface may change between minor releases. Install the alpha dist-tag deliberately and keep the CLI updated: the API refuses versions below the minimum it currently accepts, and says so.

Requirements

Node.js 22 or later. Nothing else.

Install

npm install -g @twofutures/minima-cli@alpha

Or run it without installing:

npx @twofutures/minima-cli@alpha --help

Configure

Set these two environment variables:

export MINIMA_ORGANIZATION_ID=org_your_organization
export MINIMA_API_KEY=priv_your_api_key

Both identifiers come from the Minima app. Open your organization there and the organization ID is in the URL, as /app/<organizationId>/. From the same organization, go to API Keys and add a key of type Admin — the CLI reads and writes, so a Public key is not enough. The key starts with priv_ and is shown once, at creation.

The CLI never writes credentials into your working directory. It does read a .env.local or .env file from the directory you run it in, so a project can keep its own settings there; real environment variables win over the file. Anything holding MINIMA_API_KEY is a secret — add it to .gitignore and keep it out of commits.

If either is missing, every command that talks to the API stops with a usage error naming both.

Try it

Two reads, to confirm the credentials work and see what the organization holds:

minima sites list
minima entity-types list

Then materialise the organization into files you can review:

minima pull
minima push

pull writes a minima/ directory of .jsonc files — sites, pages, articles, entities, categories, images — plus a .minima/ cache it uses as the baseline for the next pull. push reads those files back and reports what applying them would change.

push writes nothing without --apply. Everything above is read-only. When the reported plan is what you want:

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

Positional paths narrow the plan to those files or directories.

Output and inspection

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

--dry-run prints the request a command would send and sends nothing:

minima entities list --limit 5 --dry-run --json

Run minima --help for the available commands, and minima <command> --help for one command's arguments and flags. The help is generated from the API's own operations, so it describes the surface your organization actually has.

Update checks

Once a day the CLI asks the API which version is current, and prints a notice after your command has finished if a newer one exists. Your command never waits for that: the request runs in a separate background process and its answer is cached, so the notice you see comes from the last check rather than this one. Nothing about you or your organization is sent — the request carries the CLI version and needs no credentials.

To turn it off:

export MINIMA_NO_UPDATE_CHECK=1

Checks are skipped automatically when CI is set. MINIMA_UPDATE_CHECK_INTERVAL sets the interval in seconds. ~/.config/minima/config.json holds the same settings for good — { "updateCheck": false } to disable, { "channel": "beta" } to follow a pre-release channel where one is published. The cached answer lives in ~/.cache/minima/update.json and can be deleted at any time.

Support

The alpha is intentionally small and has no telemetry. Share feedback through your Minima contact, including the command, its --json output, and the installed package version.

Minima CLI is proprietary software, distributed under the UNLICENSED license.