---
title: "Overview"
description: "Install and configure the Minima CLI."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.minima.ltd/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

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

Or run it without installing:

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

## Configure

Set two environment variables:

```sh
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](/developers/api-keys) 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:

```sh
minima sites list
minima entity-types list
```

Then materialise the organization into files you can review:

```sh
minima pull
minima push
```

`push` writes nothing without `--apply`. See [Workspace](/cli/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:

```sh
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](/cli/papercuts) from wherever you hit one:

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

Source: https://docs.minima.ltd/cli/overview/index.mdx