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

# CLI Reference

> Mnemom CLI commands and usage

# CLI reference

The `mnemom` CLI manages authentication, alignment cards, protection cards, and agent diagnostics for the Mnemom trust stack.

## Installation

```bash theme={null}
npm install -g @mnemom/mnemom
```

## Authentication

<Steps>
  ### `mnemom login`

  Authenticate with your Mnemom account. Opens a browser-based login flow and stores the auth token locally.

  ```bash theme={null}
  mnemom login
  ```

  Auth tokens are stored in `~/.mnemom/auth.json`. All subsequent commands use this token automatically.

  <Note>
    Logging in does **not** select an organization — the session carries no org
    context. Org-scoped commands (like `agents claim`) target an org via `--org`,
    defaulting to your personal org when omitted.
  </Note>

  ### `mnemom logout`

  Remove locally stored auth credentials.

  ```bash theme={null}
  mnemom logout
  ```

  ### `mnemom whoami`

  Display the currently authenticated user.

  ```bash theme={null}
  mnemom whoami
  ```

  **Example output:**

  ```
  Logged in as alex@example.com (org: mnemom)
  ```
</Steps>

## Organizations

<Steps>
  ### `mnemom org list`

  List every org you belong to. Your personal org is tagged `(personal)`.

  ```bash theme={null}
  mnemom org list
  ```

  ### `mnemom org show [org_id]`

  Print details for one org (`--personal` for your personal-org-of-one).

  ```bash theme={null}
  mnemom org show --personal
  ```
</Steps>

## Card commands

<Steps>
  ### `mnemom card show`

  Fetch your agent's active alignment card and display it as structured YAML output showing principal, values, autonomy envelope, enforcement, and audit commitment.

  ```bash theme={null}
  mnemom card show --agent my-coder
  ```

  **Example output:**

  ```yaml theme={null}
  card_id: ac-a4c12709-v2
  schema: unified-card/1.0
  issued_at: "2026-02-21"
  expires_at: "2026-08-21"

  principal:
    type: human
    relationship: delegated_authority

  values:
    declared:
      - transparency
      - honesty
      - harm_prevention
      - editorial_independence
      - source_attribution
      - investigative_rigor
    hierarchy: lexicographic

  autonomy:
    bounded_actions:
      - inference
      - read
      - write
      - edit
      - exec
      - web_fetch
      - web_search
    forbidden_actions:
      - fabricate_sources
      - impersonate_human
    escalation_triggers:
      - condition: named_entity_critical
        action: escalate
      - condition: legal_claims_present
        action: escalate

  enforcement:
    mode: warn

  audit:
    trace_format: ap-trace-v1
    retention_days: 365
    queryable: true
    tamper_evidence: append_only
  ```

  ### `mnemom card edit`

  Open your agent's alignment card in your `$EDITOR` for interactive editing. Validates the card on save.

  ```bash theme={null}
  mnemom card edit --agent my-coder
  ```

  The card is fetched from the server, opened in your editor, and published back on save. If validation fails, the CLI reports errors and gives you the option to re-edit.

  ### `mnemom card publish <file>`

  Read a YAML or JSON alignment card file, validate it against the unified schema, confirm before publishing, and upload to your agent's alignment card via the API. Optionally triggers re-verification of existing traces against the new card.

  ```bash theme={null}
  mnemom card publish card.yaml --agent my-coder
  ```

  **Options:**

  | Option           | Description                               |
  | ---------------- | ----------------------------------------- |
  | `--agent <name>` | Target agent                              |
  | `--no-verify`    | Skip re-verification prompt after publish |
  | `--yes`          | Skip confirmation prompt                  |

  **Example:**

  ```
  $ mnemom card publish card.yaml --agent my-coder

    Validating card.yaml...
    ✓ Valid YAML
    ✓ Required blocks present (principal, values, autonomy, audit)
    ✓ 6 declared values (3 standard, 3 custom with definitions)
    ✓ 7 bounded actions
    ✓ 2 escalation triggers (evaluable conditions)
    ✓ Card not expired

    Publish this card for agent my-coder? (y/N) y

    ✓ Card published: ac-a4c12709-v2
    Re-verify existing traces against new card? (y/N) y
    ✓ 247 traces re-verified
  ```

  ### `mnemom card validate <file>`

  Local-only validation with no API call. Checks compliance against the unified schema. CI-friendly: exit code 0 on pass, 1 on fail.

  ```bash theme={null}
  mnemom card validate card.yaml
  ```

  **Example:**

  ```
  $ mnemom card validate card.yaml

    ✓ Valid YAML
    ✓ Required blocks: principal, values, autonomy, audit
    ✓ values.declared: 6 values (non-empty)
    ✓ Custom values defined: editorial_independence, source_attribution, investigative_rigor
    ✓ bounded_actions: 7 actions (non-empty)
    ✓ escalation_triggers: 2 triggers (evaluable conditions)
    ✓ expires_at: 2026-08-21 (valid)

    Card is valid.
  ```

  ### `mnemom card evaluate <file> --tools <tools>`

  Evaluate a card's policy against a set of tools locally. This replaces the old `mnemom policy evaluate` command. The alignment card now includes capability mappings and enforcement rules directly.

  ```bash theme={null}
  mnemom card evaluate card.yaml --tools mcp__browser__navigate,mcp__filesystem__delete --agent my-coder
  ```

  **Options:**

  | Option                  | Description                                    |
  | ----------------------- | ---------------------------------------------- |
  | `--agent <name>`        | Target agent                                   |
  | `--tools <tools>`       | Comma-separated list of tool names to evaluate |
  | `--format <json\|text>` | Output format (default: text)                  |

  **Exit codes:**

  * `0` -- All evaluations pass
  * `1` -- One or more evaluations fail

  **Example output:**

  ```
  Evaluating card.yaml against 2 tools...

    mcp__browser__navigate .... PASS (mapped to web_fetch)
    mcp__filesystem__delete ... FAIL (forbidden)
      Reason: File deletion not permitted

    Verdict: FAIL
    1 pass, 1 fail
  ```
</Steps>

## Protection commands

<Steps>
  ### `mnemom protection show`

  Display the protection card for an agent as structured YAML output.

  ```bash theme={null}
  mnemom protection show --agent my-coder
  ```

  ### `mnemom protection edit`

  Open the protection card in your `$EDITOR` for interactive editing. Validates the card on save.

  ```bash theme={null}
  mnemom protection edit --agent my-coder
  ```

  ### `mnemom protection publish <file>`

  Validate and upload a protection card for an agent.

  ```bash theme={null}
  mnemom protection publish protection.yaml --agent my-coder
  ```

  **Options:**

  | Option           | Description              |
  | ---------------- | ------------------------ |
  | `--agent <name>` | Target agent             |
  | `--yes`          | Skip confirmation prompt |

  ### `mnemom protection validate <file>`

  Local-only validation of a protection card. CI-friendly exit codes.

  ```bash theme={null}
  mnemom protection validate protection.yaml
  ```
</Steps>

## Agent listing

### `mnemom agents`

List all agents associated with your authenticated account.

```bash theme={null}
mnemom agents
```

**Example output:**

```
  my-coder
    Agent ID:  mnm-0b3f2a1c-d4e5-4f60-b7a8-9c0d1e2f3a4b
    Created:   2/23/2026
    Last seen: 2 minutes ago

  my-researcher
    Agent ID:  mnm-550e8400-e29b-41d4-a716-446655440000
    Created:   2/7/2026
    Last seen: 1 hour ago

  Total: 2 agent(s)
```

<Note>
  Requires authentication via `mnemom login`. Agents are auto-created by the gateway on first API call -- there is no registration step.
</Note>

### `mnemom agents claim <id-or-name>`

Claim a gateway-provisioned agent into an org by proving you hold its provider
key. See the [Agent Claim Flow guide](/guides/agent-claim-flow) for the full
lifecycle.

```bash theme={null}
mnemom agents claim mnm-... --key "$AGENT_PROVIDER_KEY" --org mnemom
```

* `--org <slug|id>` — destination org. Defaults to your personal org (with a
  loud notice) when omitted.
* `--key <key>` — the agent's provider API key; the CLI derives the
  `hash_proof` locally. Alternatively pass `--hash-proof <64-hex>` directly.

<Note>
  To re-home an agent, re-`claim` it with a new `--org` (possession-based:
  requires the agent's key). The destination org's template can floor/cap the
  agent's composed card — its effective posture may change. See
  [Idempotency and re-homing](/guides/agent-claim-flow#idempotency-and-re-homing).
</Note>

## Diagnostics

<Steps>
  ### `mnemom status`

  Show agent status, connected providers, and connection info.

  ```bash theme={null}
  mnemom status --agent my-coder
  ```

  **Output includes:**

  * Agent ID
  * Connected providers (Anthropic, OpenAI, Gemini)
  * Gateway URL
  * Connection status
  * Last activity timestamp

  **Example output:**

  ```
  Agent:    my-coder (mnm-0b3f2a1c-d4e5-4f60-b7a8-9c0d1e2f3a4b)
  Gateway:  https://gateway.mnemom.ai
  Status:   Connected
  Providers:
    Anthropic  ✓ (Claude Opus 4.6)
    OpenAI     ✓ (GPT-5.2)
    Gemini     ✗ (not configured)
  Last seen: 2 minutes ago
  ```

  ### `mnemom integrity`

  Display integrity score and verification statistics for your agent.

  ```bash theme={null}
  mnemom integrity --agent my-coder
  ```

  **Output includes:**

  * Overall integrity ratio (percentage of `clear` verdicts)
  * Verification statistics (total traces, violations, warnings)
  * Drift alert status
  * Recent concern categories

  **Example output:**

  ```
  Integrity Score: 0.94 (94%)
  Traces verified: 1,247
  Violations:      12 (3 CRITICAL, 9 HIGH)
  Drift alerts:    0 active
  Window:          10 checkpoints, 2h retention
  ```

  ### `mnemom logs`

  Show recent traces and actions.

  ```bash theme={null}
  mnemom logs --agent my-coder [-l N]
  ```

  **Options:**

  | Option | Description                      | Default |
  | ------ | -------------------------------- | ------- |
  | `-l N` | Number of log entries to display | 10      |

  **Example:**

  ```bash theme={null}
  # Show last 10 traces (default)
  mnemom logs --agent my-coder

  # Show last 50 traces
  mnemom logs --agent my-coder -l 50
  ```

  **Example output:**

  ```
  2026-02-17 14:32:01  CLEAR      api_call    Claude Opus 4.6    "Search for documents"
  2026-02-17 14:31:45  CLEAR      api_call    Claude Opus 4.6    "Summarize results"
  2026-02-17 14:31:12  REVIEW     api_call    GPT-5.2            "Execute trade"
    └─ concern: autonomy_violation (HIGH) — action exceeds bounded_actions
  2026-02-17 14:30:58  CLEAR      api_call    Claude Opus 4.6    "Draft email"
  ```
</Steps>

## License

<Steps>
  ### `mnemom license activate`

  Activate a license key for your account.

  ```bash theme={null}
  mnemom license activate <key>
  ```

  ### `mnemom license status`

  Show current license status.

  ```bash theme={null}
  mnemom license status
  ```

  ### `mnemom license deactivate`

  Deactivate the current license.

  ```bash theme={null}
  mnemom license deactivate
  ```
</Steps>

## Global options

| Option           | Description                               |
| ---------------- | ----------------------------------------- |
| `--agent <name>` | Select which agent to use for the command |
| `--version`      | Show CLI version                          |
| `--help`         | Show help text                            |

## Agent selection

Commands that operate on an agent use this priority to determine which agent:

1. `--agent <name>` flag (highest priority)
2. `MNEMOM_AGENT` environment variable

There is no default agent concept. If neither `--agent` nor `MNEMOM_AGENT` is set, the CLI will prompt you to specify one (or error in non-interactive mode).

**Environment:**

Set `MNEMOM_ENV` to control which environment the CLI targets:

| Value        | Description                      |
| ------------ | -------------------------------- |
| `production` | Production environment (default) |
| `staging`    | Staging environment              |
| `local`      | Local development environment    |

**Example:**

```bash theme={null}
# Use --agent flag
mnemom status --agent my-coder

# Use environment variable
MNEMOM_AGENT=my-coder mnemom logs

# Target staging environment
MNEMOM_ENV=staging mnemom status --agent my-coder
```

## Workflow

A typical workflow with the mnemom CLI:

<Steps>
  ### Install and authenticate

  ```bash theme={null}
  npm install -g @mnemom/mnemom
  mnemom login
  ```

  ### Point your LLM client at the gateway

  Configure your application or LLM client to use `gateway.mnemom.ai` with the `x-mnemom-agent` header. The agent is auto-created on first API call -- no registration needed.

  ```bash theme={null}
  curl https://gateway.mnemom.ai/anthropic/v1/messages \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "x-mnemom-agent: my-coder" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-4-6",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello"}]
    }'
  ```

  ### Verify your agent is connected

  ```bash theme={null}
  mnemom status --agent my-coder
  ```

  ### Check integrity

  ```bash theme={null}
  mnemom integrity --agent my-coder
  ```

  ### Review recent activity

  ```bash theme={null}
  mnemom logs --agent my-coder -l 20
  ```

  ### View your alignment card

  ```bash theme={null}
  mnemom card show --agent my-coder
  ```

  ### Customize your alignment card (optional)

  Create a YAML alignment card file and publish it:

  ```bash theme={null}
  mnemom card validate my-card.yaml
  mnemom card publish my-card.yaml --agent my-coder
  ```

  Or edit the existing card directly:

  ```bash theme={null}
  mnemom card edit --agent my-coder
  ```

  See the [Card Management guide](/guides/card-management) for how to build a card from scratch.

  ### Evaluate card policy against tools (optional)

  Test your card's capability mappings against a set of tools:

  ```bash theme={null}
  mnemom card evaluate my-card.yaml --tools mcp__browser__navigate,mcp__slack__post_message --agent my-coder
  ```
</Steps>

## Supported providers

The gateway supports tracing for these providers:

| Provider  | Models                                | Thinking/AIP            | Auth Method             |
| --------- | ------------------------------------- | ----------------------- | ----------------------- |
| Anthropic | Claude Opus 4.6, Opus 4.5, Sonnet 4.5 | Full (thinking blocks)  | `x-api-key`             |
| OpenAI    | GPT-5.2, GPT-5.2 Pro, GPT-5           | Via reasoning summaries | `Authorization: Bearer` |
| Gemini    | Gemini 2.5 Pro, Gemini 3 Pro          | Full (thought parts)    | `x-goog-api-key`        |

## See also

* [Gateway Overview](/gateway/overview) -- Architecture and how it works
* [Enforcement Modes](/gateway/enforcement) -- Configure violation response behavior
* [Card Management](/guides/card-management) -- Creating and managing alignment cards