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

minima auth signup

It offers your git config user.email as the default, so most people press Enter. A six-digit code arrives by email; paste it back and the terminal finishes. You end up with an account, an organization, and an Admin API key written to ~/.config/minima/config.json.

minima auth login is the same command for a machine that already has an account.

CI jobs, containers and agents set two environment variables instead, and those win over anything stored on the machine:

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. A key created there must be 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.

If a command finds no credentials at all, it stops and names the one command that fixes it. See Signing in for where credentials live, how to hold several organizations at once, and how to reach the dashboard from an account the CLI created.

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"