> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mima.works/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mima.works/_mcp/server.

# CLI Reference

The `mima` CLI is installed with the Python SDK:

```bash
pip install mima-governance
mima --version
```

Or run via Python:

```bash
python -m mima_governance --version
```

---

## Authentication

### `mima login`

Store your API key and workspace credentials locally.

```bash
mima login
```

Prompts for your API key, then resolves and stores your workspace ID.
Credentials are written to `~/.mima/config.json` with owner-only permissions (`0600`).

```bash
mima login --api-key mima_ext_...
```

---

## Evidence

### `mima push`

Push a GRC evidence record from the command line. Pass the record type as the first positional argument, then supply fields as named flags.

```bash
mima push change_event \
  --by ci-bot@company.com \
  --description "Deploy v1.2.3 to production" \
  --environment production \
  --system api-service
```

```bash
mima push ai_risk_assessment \
  --system loan-scorer \
  --risk-tier limited \
  --use-case "Customer support routing" \
  --intended-purpose "Route queries to the correct team" \
  --impact-domains customer_service \
  --art5-self-assessment true \
  --assessor alice@example.com
```

```bash
mima push model_evaluation \
  --model-id loan-scorer-v2 \
  --dataset holdout-q2-2026 \
  --accuracy 0.94 \
  --evaluated-by alice@example.com \
  --evaluation-type quarterly
```

Pipe JSON for scripted use:

```bash
echo '{"by":"ci-bot@company.com","description":"Deploy","environment":"production","system":"api-service"}' \
  | mima push change_event --stdin
```

Add `--dry-run` to preview controls without writing:

```bash
mima push model_evaluation \
  --model-id loan-scorer-v2 --dataset holdout --accuracy 0.94 \
  --evaluated-by alice@example.com --dry-run
# Output: Would earn: EUAIA_ART9_4, ISO42001_9_1
```

**Common flags**

| Flag             | Description                      |
| ---------------- | -------------------------------- |
| `--dry-run`      | Preview controls without writing |
| `--api-key`      | Override stored API key          |
| `--workspace-id` | Override stored workspace ID     |
| `--stdin`        | Read fields from JSON on stdin   |

### Environment variable: `MIMA_BASE_URL`

Used by `mima push` and `mima gates`. Set when pointing at a self-hosted
deployment:

```bash
export MIMA_BASE_URL=https://mima.internal.example.com/api
mima push ...
```

---

## Gates

### `mima gates`

Check whether required evidence gates pass for a system.

```bash
mima gates --system my-pipeline
```

Outputs a table of gate name, pass/fail status, and blocking status.
Exits with code `0` if all gates pass, `1` if any soft gates fail, `2` if any hard gates fail.

Use in CI to block deploys when gates fail:

```bash
mima gates --system my-pipeline || exit 1
```

**Options**

| Flag             | Description                                  |
| ---------------- | -------------------------------------------- |
| `--system`       | System to check (defaults to workspace-wide) |
| `--api-key`      | Override stored API key                      |
| `--workspace-id` | Override stored workspace ID                 |
| `--format`       | `table` (default) \| `json`                  |

---

## Controls

### `mima derive-controls`

Get recommended evidence record types for a system description.

```bash
mima derive-controls --description "A classification model that routes \
  customer support tickets to the correct team."
```

Returns a list of recommended record types and the controls they earn.

```
Recommended records for this system:

  ai_risk_assessment     → EUAIA_ART9, ISO42001_6_1
  model_evaluation       → EUAIA_ART9_4, ISO42001_9_1
  human_oversight        → EUAIA_ART14, ISO42001_6_1_2
  training_data_governance → EUAIA_ART10
```

**Options**

| Flag            | Description                           |
| --------------- | ------------------------------------- |
| `--description` | System description (natural language) |
| `--risk-tier`   | `high`, `limited`, or `minimal`       |
| `--api-key`     | Override stored API key               |

### Environment variable: `MIMA_API_URL`

Used by `mima derive-controls`. Defaults to `https://api.mima.works/api`.

---

## Status

### `mima status`

Show your current posture score and top open gaps.

```bash
mima status
```

```
Posture score: 74/100

Open gaps (top 5):
  [HIGH]   model_drift_event not logged in 90 days (loan-scorer)
  [MEDIUM] training_data_governance missing for 2 systems
  [MEDIUM] quarterly model_evaluation overdue (customer-support-ai)
  [LOW]    vendor_risk not reviewed in 180 days (OpenAI)
  [LOW]    governance_review overdue

Gates: 3/5 passing
```

---

## Configuration file

Stored at `~/.mima/config.json`. Do not edit manually — use `mima login`.

```json
{
  "api_key": "mima_ext_...",
  "workspace_id": "ws_...",
  "base_url": "https://api.mima.works"
}
```

Permissions are set to `0600` (owner read/write only). The API key is
never written to `.env` files or environment exports by `mima login`.

---

## Exit codes

| Code | Meaning                              |
| ---- | ------------------------------------ |
| `0`  | Success                              |
| `1`  | Soft gate failure or partial success |
| `2`  | Hard gate failure                    |
| `3`  | Authentication error                 |
| `4`  | Network or server error              |