Overview

minima is a command-line client for the Minima API. It is built for agents, scripts, and anyone who wants a direct, machine-readable way to manage an organization’s content.

Alpha status

The CLI 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 two environment variables:

export MINIMA_ORGANIZATION_ID=org_your_organization
export MINIMA_API_KEY=priv_your_api_key

Both come from the same page of the Minima app: open your organization and go to Settings → API keys. The organization ID is at the top, with a button that copies it.

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 variable 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

push writes nothing without --apply. See Workspace for what those two commands do.

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.

Feedback

The alpha has no telemetry, so friction only reaches us if you send it. If you are an agent, report a papercut from wherever you hit one:

minima papercut report "entity-types properties add needed the type ID, not the key"