# Neotoma CLI reference

## Scope

This document covers CLI commands, options, configuration, and developer facing details. It does not cover MCP behavior or server side implementation beyond public API references.

## Purpose

Provide a complete CLI command reference and developer context for Neotoma CLI behavior.

## Invariants

1. Commands and options MUST match the CLI implementation.
2. Output formatting MUST remain deterministic and stable.
3. Configuration details MUST remain consistent with the CLI config module.

## Definitions

- **Operation ID**: OpenAPI operation identifier used by `neotoma request`.
- **Config path**: The file path where CLI stores connection settings.
- **PKCE**: OAuth Proof Key for Code Exchange used for login.

## Running the CLI

Run via npm scripts: `npm run cli` or `npm run cli:dev` (dev mode with immediate source changes). For global `neotoma` command: `npm run setup:cli` (build and link in one step), or manually `npm run build:server` then `npm install -g .` or `npm link`. If `neotoma` is not found, add `$(npm config get prefix)/bin` to PATH. See [CLI setup](getting_started.md#cli-setup) and [CLI overview](cli_overview.md#installation-and-setup) for full installation and troubleshooting details.

### Keeping the global CLI in sync

The global `neotoma` runs the built files in `dist/`, not the TypeScript source. After you change CLI code, either build once (`npm run build:server`) or run a watcher so the global install stays current:

- **One-off:** `npm run build:server` after CLI changes.
- **Ongoing (terminal):** Run `npm run dev:types` in a terminal. It runs `tsc --watch` so every save recompiles `dist/`; the next `neotoma` invocation uses the new code. With `npm link`, no re-link is needed.
- **Ongoing (after reboot):** Run `npm run setup:launchd-cli-sync` once (alias: `setup:launchd-watch-build`). This installs a macOS LaunchAgent that re-links the global `neotoma` command to the current checkout, runs `tsc --watch` at login, and keeps it running so the global CLI stays in sync even after restart. The agent captures the current `node` / `npm` paths during setup; re-run the setup command after switching Node manager or Node version. Logs: `data/logs/launchd-watch-build.log`. Unload with `launchctl unload ~/Library/LaunchAgents/com.neotoma.watch-build.plist`.

### Dev or prod HTTP at login (macOS)

- **Dev API:** `npm run setup:launchd-dev` (alias `setup:launchd-dev-server`) installs `com.neotoma.dev-server`, which runs `npm run dev:server`. See [`docs/developer/launchd_dev_servers.md`](launchd_dev_servers.md).
- **Built production-mode API:** `npm run setup:launchd-prod-server` installs `com.neotoma.prod-server`, which runs `npm run start:server:prod`. See [`docs/developer/launchd_prod_server.md`](launchd_prod_server.md).

### Scheduled GitHub issues sync (macOS)

Run `npm run setup:launchd-issues-sync` once to install `com.neotoma.issues-sync`: it runs `neotoma issues sync` every 5 minutes (and once at login). Logs: `data/logs/launchd-issues-sync.log`. Optional env for launchd (not in your shell profile): copy `scripts/launchd-issues-sync.env.example` to `data/local/launchd-issues-sync.env`. Unload with `launchctl unload ~/Library/LaunchAgents/com.neotoma.issues-sync.plist`.

### Environment: `neotoma dev` / `neotoma prod`

To target a specific API environment, pass `dev` or `prod` as the first argument or use `--env`.

- `neotoma dev` — development API (port 3080).
- `neotoma prod` — production API (port 3180).

Examples: `neotoma prod`, `neotoma dev`, `neotoma prod storage info`. Equivalent to using `--env`.

### Default: interactive session (use-existing only)

When you run `neotoma` with **no arguments**, source checkout selection follows this precedence:

1. explicit CLI flags (for commands that accept root/path flags)
2. `NEOTOMA_REPO_ROOT`
3. directory-local checkout (walk up from current directory)
4. saved config `project_root` (legacy `repo_root`) in `~/.config/neotoma/config.json`
5. user-level env at `~/.config/neotoma/.env` when no checkout is detected

With a source checkout, the CLI:

1. Uses **use-existing** policy only (no automatic server start).
2. Discovers running API instances from session ports, default ports (`3080`, `3180`), remembered ports, and optional extra configured ports.
3. Applies `--env` as a preference when selecting among multiple detected instances.
4. If multiple candidates remain, prompts you to choose the instance.
5. If none respond, shows fallback startup guidance and the command menu.
6. Enters an **interactive session** with a `neotoma> ` prompt.

**Non-interactive (e.g. agents):** When stdout is not a TTY, the CLI does **not** prompt. It uses **use-existing** (connect only). If **no command** is given and stdout is not a TTY (e.g. an agent runs `neotoma` with no args), the CLI prints: "No command given. Run neotoma <command> (e.g. neotoma entities list). Use neotoma --help for options." and exits with code 1.

**Direct invocation and session parity:** Every action available at the interactive `neotoma>` prompt is available as a direct CLI call: `neotoma <top-level> [subcommand] [options] [args]`. Examples: `neotoma entities list`, `neotoma relationships list <entityId>`, `neotoma storage info`. Agents and scripts should always use direct invocation; do not depend on entering the interactive session. See [CLI overview](cli_overview.md) and the command sections below for the full command tree.

To show the intro and then a **command menu** (prompt `> ` and `? for shortcuts`; no servers), use:

- `neotoma --no-session`
  You get the same intro panel, then an interactive prompt. Type a command, or `?` / `help` to list commands. Type `exit` or `quit`, or press Ctrl+D, to exit.

To enter a session without starting any servers (connect to an already-running API):

- `neotoma --no-servers` or `neotoma --servers=use-existing`
  Connect-only startup. Detects all available local API instances (not only `3080`/`3180`), prefers `--env` matches when available, and prompts when multiple candidates remain.

To start the API in the **background**:

- `neotoma api start --background --env dev` (or `--env prod`)
  Starts the selected environment only and writes env-specific PID/log files.
- `neotoma api start --background --env dev --tunnel` (or `--env prod --tunnel`)
  Starts the API with an HTTPS tunnel (ngrok/cloudflared) for remote MCP access. Tunnel URL is written to `/tmp/ngrok-mcp-url.txt` when ready. Use `--tunnel-provider ngrok` or `--tunnel-provider cloudflare` to force a provider; otherwise the script auto-detects from installed tools.
- `neotoma api start --env dev --tunnel` (or `--env prod --tunnel`, no `--background`)
  Runs the API and tunnel in the **foreground** in the current terminal (same as `npm run dev:server:tunnel`). Logs stream to the terminal; Ctrl+C stops both. Tunnel URL: `cat /tmp/ngrok-mcp-url.txt`.

**`--watch` flag (source checkouts).** The product CLI command remains `neotoma api start`, but source-checkout npm spawn targets now use the `dev:server*` taxonomy. Production-env source checkouts route to `dev:server:prod`; installed-package production starts route to `start:server:prod`.

- `neotoma api start --env prod --watch` — keeps source-checkout watch behavior explicit.
- `neotoma api start --env prod --tunnel` — routes to `dev:server:prod:tunnel`.

The flag is a no-op on `--env dev`, on installed-package checkouts without source watch scripts, and on the `--tunnel` path (the tunnel flow always wants the watcher). The deprecation line is suppressed under `--output json`.

For a real **headless / systemd** production deployment, install the published npm package (`npm install -g neotoma`) and use the recipe in [install.md § Production deployment (headless / systemd)](../../install.md#production-deployment-headless--systemd) rather than `neotoma api start` on a source checkout.

## npm scripts summary

All `npm run <script>` commands in one place. Scripts follow the taxonomy documented in [`docs/developer/npm_scripts.md`](npm_scripts.md): `dev:*` for local development and watch processes, `build:*` for one-shot builds, `start:*` for compiled-`dist` runners, and `info:*` for one-shot informational output. Old `watch:*`, `start:api*`, and pages-site names remain as one-release compatibility aliases.

### Build and start

| Script              | Description                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `build:server`      | Compile server TypeScript (`tsc`) → MCP, API, CLI, services                                                                                                                        |
| `build:ui`          | Build frontend (Vite)                                                                                                                                                              |
| `start:mcp`         | Run built MCP server (stdio)                                                                                                                                                       |
| `start:server`      | Run built HTTP Actions API                                                                                                                                                         |
| `start:api`         | Deprecated alias for `start:server`                                                                                                                                                |
| `start:server:prod` | Run `build:server`, pick HTTP port from 3180, set `NEOTOMA_ENV=production`, then run `start:server` (same `node dist/actions.js` as `start:server`). Does not build UI or run MCP. |
| `start:api:prod`    | Deprecated alias for `start:server:prod`                                                                                                                                           |
| `start:ws`          | Run MCP WebSocket bridge                                                                                                                                                           |

### Development (watch mode)

| Script                                   | Port           | Description                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `dev:mcp`, `watch`                       | —              | MCP stdio watch                                                                                                                                                                                                                                                                                                                                                                                                                |
| `dev:server`, `watch:server`             | 3080           | HTTP Actions API + watch                                                                                                                                                                                                                                                                                                                                                                                                       |
| `dev:ui`, `watch:ui`                     | Vite           | Frontend dev server                                                                                                                                                                                                                                                                                                                                                                                                            |
| `dev:server:tunnel`                      | 3080           | API + HTTPS tunnel (Cloudflare/ngrok)                                                                                                                                                                                                                                                                                                                                                                                          |
| `dev:server:tunnel:types`                | 3080           | API + tunnel + `tsc --watch`                                                                                                                                                                                                                                                                                                                                                                                                   |
| `dev`, `dev:full`                        | 3080, Vite, WS | API + UI + build + resource banner + Inspector live build into `dist/inspector` (`NEOTOMA_INSPECTOR_LIVE_BUILD=1`: no long cache + **full page reload** when build output mtimes change — `index.html` plus `assets/*`, so lazy chunks trigger reload). With out-of-package `dist/inspector`, Vite watch uses **chokidar polling** by default so LaunchAgents pick up saves (`NEOTOMA_INSPECTOR_BUILD_WATCH_POLL=0` disables). |
| `dev:full:prod`                          | 3180, Vite, WS | Same as `dev` with `NEOTOMA_ENV=production` and prod-scoped Inspector watch (`dev:inspector:prod`)                                                                                                                                                                                                                                                                                                                             |
| `dev:inspector`, `dev:inspector:prod`    | —              | Inspector only: `vite build --watch` → repo `dist/inspector` (use with API already running, or rely on `dev` / `dev:full:prod`; polling applies when output is `../dist/inspector` per `inspector/vite.config.ts`)                                                                                                                                                                                                             |
| `watch:mcp:dev-shim`, `dev:mcp:dev-shim` | —              | Stable stdio dev shim that restarts its MCP worker behind the client connection                                                                                                                                                                                                                                                                                                                                                |
| `dev:mcp`                                | —              | MCP stdio watch                                                                                                                                                                                                                                                                                                                                                                                                                |
| `dev:mcp:prod`                           | —              | MCP stdio, production env                                                                                                                                                                                                                                                                                                                                                                                                      |
| `dev:server:mcp`                         | 3080, 8280     | API + MCP HTTP + build                                                                                                                                                                                                                                                                                                                                                                                                         |
| `dev:ws`                                 | 3080, 8280     | API + WebSocket bridge watch                                                                                                                                                                                                                                                                                                                                                                                                   |
| `dev:server:prod`                        | 3180           | API + build, production env                                                                                                                                                                                                                                                                                                                                                                                                    |
| `dev:server:prod:tunnel`                 | 3180           | API + tunnel + build, production env                                                                                                                                                                                                                                                                                                                                                                                           |

Scripts that start servers use the port(s) above when free; if a port is in use, they bind to the next available port (no process killing). See `scripts/pick-port.js`.

### Tunnel and setup

| Script             | Description                                    |
| ------------------ | ---------------------------------------------- |
| `tunnel:https`     | Start HTTPS tunnel only (Cloudflare or ngrok)  |
| `setup:cli`        | Build and link `neotoma` globally              |
| `setup:env-hook`   | Install git hook to copy `.env` into worktrees |
| `copy:env`         | Copy env file into current worktree            |
| `setup:worktree`   | Cursor worktree init                           |
| `setup:data`       | Data directory symlink                         |
| `setup:foundation` | Foundation submodule symlink                   |
| `setup:storage`    | Create storage buckets                         |

### Test and quality

| Script                   | Description                                                                        |
| ------------------------ | ---------------------------------------------------------------------------------- |
| `test`                   | Run Vitest                                                                         |
| `test:unit`              | Vitest, unit/services/agent/contract/security/cli only (no integration dir)        |
| `test:remote`            | Vitest with remote DB tests (RUN_REMOTE_TESTS=1)                                   |
| `test:frontend`          | Vitest for frontend                                                                |
| `test:integration`       | Integration tests                                                                  |
| `test:agent-mcp`         | Agent MCP tests                                                                    |
| `test:coverage`          | Vitest with coverage                                                               |
| `test:coverage:critical` | Coverage for critical paths                                                        |
| `test:e2e`               | Playwright E2E                                                                     |
| `test:e2e:headed`        | Playwright E2E, headed browser                                                     |
| `lint`                   | ESLint (src)                                                                       |
| `type-check`             | `tsc --noEmit`                                                                     |
| `validate:coverage`      | Validate coverage map                                                              |
| `validate:doc-deps`      | Validate doc dependencies                                                          |
| `validate:mdx-site`      | Validate `docs/site/pages/**/*.meta.json` + MDX siblings and `ROUTE_METADATA` keys |
| `validate:routes`        | Site route parity vs `seo_metadata` / `MainApp`                                    |
| `doctor`                 | Project health check (env, local SQLite hints)                                     |

### Database and schema

| Script                  | Description                                |
| ----------------------- | ------------------------------------------ |
| `migrate`               | Run migrations                             |
| `migrate:dry-run`       | Migrations dry run                         |
| `migrate:plans`         | Migrate plans                              |
| `migrate:plans:dry-run` | Migrate plans dry run                      |
| `schema:export`         | Export schema snapshots                    |
| `schema:init`           | Initialize schemas                         |
| `schema:init:dry-run`   | Schema init dry run                        |
| `schema:icons:generate` | Generate schema icons                      |
| `schema:cleanup:test`   | Cleanup test schemas                       |
| `recover:db`            | Check dev SQLite integrity / recover copy  |
| `recover:db:prod`       | Check prod SQLite integrity / recover copy |
| `wipe:dev`              | Wipe dev database                          |
| `wipe:prod`             | Wipe prod database                         |
| `wipe:local`            | Wipe local database                        |
| `wipe:*:storage`        | Wipe + storage (e.g. `wipe:prod:storage`)  |

### Docs and other

| Script                                     | Description                   |
| ------------------------------------------ | ----------------------------- |
| `cli`, `cli:dev`                           | Run Neotoma CLI (built / dev) |
| `docs:generate`                            | Generate docs                 |
| `build:docs`, `dev:docs`, `dev:docs:serve` | Docs site build/dev/serve     |
| `openapi:generate`                         | Generate OpenAPI types        |
| `branches:prune`                           | Prune merged branches         |
| `parquet:samples`                          | Create sample parquet files   |
| `sync:env`                                 | Sync env from 1Password       |

For environment and ports, see [Getting started](getting_started.md#start-development-server).

## Command reference

### Global options

- `--base-url <url>`: Override API base URL.
- `--env <env>`: Environment selector (`dev` or `prod`). Required for server commands such as `api start`, `api stop`, `api logs`, and `watch`.
- `--offline`: Force in-process local transport for data commands (no external API process required).
- `--api-only`: Force API-only mode; fail when API is unreachable (use when you want to avoid loading the local DB).
- `--json`: Output machine readable JSON.

### Issues

- `neotoma issues create --title <title> --body <body> [--visibility public|private] [--labels a,b]`: submit an issue through the same orchestration as MCP `submit_issue`. **Reporter environment is required** (v0.12+): the underlying API requires at least one of `reporter_git_sha` or `reporter_app_version`; pass them via the HTTP body when scripting against `/issues/submit`, or set `--reporter-git-sha` / `--reporter-app-version` once the CLI exposes those flags. JSON output includes `guest_access_token` when the configured operator instance accepts the issue; treat that value as a credential for later token-scoped status or message calls. **Cross-repo mirror:** the `/issues/submit` body also accepts an optional `target_repo` (`owner/repo`) field that redirects the GitHub mirror destination for that one call — use it to file an issue about a repo other than the one Neotoma is globally configured for (`NEOTOMA_ISSUES_REPO`). It overrides only the GitHub mirror; the Neotoma authoring home (operator instance) is unchanged, and the stored `issue` / `conversation` identity is namespaced to `target_repo`. A malformed value is rejected with a structured `owner/repo` validation error. Deprecated hidden alias: `--advisory` maps to `--visibility private` for one minor release and prints `visibility 'advisory' is deprecated; use 'private' instead.` to stderr outside JSON output.
- `neotoma issues message [number] --body <body> [--entity-id <id>] [--guest-access-token <token>]`: append to an issue thread. Use the guest token when the local issue snapshot does not already carry the operator token. On public issue threads, supply at least one of `reporter_git_sha` / `reporter_app_version` to record the build the message was authored against (soft requirement; the server emits a warning when both are missing).
- `neotoma issues status [--entity-id <id> | --issue-number <n>] [--skip-sync] [--guest-access-token <token>]`: print issue metadata and thread messages. At least one of `--entity-id` or `--issue-number` is required. The guest token is only needed for remote operator read-through when it is not already stored on the local issue row.
- `neotoma issues import --from-jsonl <path> [--since <iso8601>] [--until <iso8601>] [--reporter-channel <label>] [--reporter-git-sha <sha>] [--reporter-app-version <version>] [--mode proactive|consent] [--dry-run] [--limit <n>]`: ingest an observer JSONL log and file or fold issues for detected anomalies. Each line is scanned against a fixed set of filter predicates (see below); matching lines are redacted with the same `runRedactionGuard` PII backstop used by `issues create`, then either filed as new issues or folded as thread messages on existing open issues with the same dedup key `(anomaly_class, command_prefix, reporter_channel)`. Options: `--from-jsonl <path>` (required) path to the JSONL file; `--since` / `--until` filter lines by ISO 8601 timestamp; `--reporter-channel` overrides the channel label stamped on every filed issue; `--reporter-git-sha <sha>` / `--reporter-app-version <version>` supply the reporter environment when the JSONL lines lack per-line `reporter_git_sha` / `reporter_app_version` fields and the CLI binary version is unavailable (dev builds); the import fails fast with an actionable error if neither the resolved version nor any per-line field is available; `--mode proactive` files immediately, `--mode consent` (default) prompts before each filing action; `--dry-run` emits a structured JSON sweep report and commits nothing; `--limit <n>` stops after extracting n anomalies. Sweep report (emitted at end, or as JSON with `--dry-run` or `--json`) includes: `lines_scanned`, `lines_unparseable`, `lines_skipped_by_filter`, `anomalies_extracted`, `issues_filed`, `issues_folded`, `issues_skipped`, and per-issue `outcomes`.

  **Filter predicates (hard-coded in `src/services/issues/observer_import.ts`):**
  1. `exit_code != 0` AND `ERR_` class in `stderr` → `hard_error` (transport / execution failure)
  2. `unknown_fields_count > 0` → `schema_drift` (unknown response fields indicate schema projection drift)
  3. `HEURISTIC_MERGE` in `stderr` → `heuristic_merge` (identity resolution warning)
  4. `duration_ms > 5000` on store/retrieve commands → `perf_regression`
  5. `ERR_STORE_RESOLUTION_FAILED` in any field → `resolver_bug`
  6. `database disk image is malformed` in any field → `sqlite_corruption`
  7. `ERR_REPORTER_ENVIRONMENT_REQUIRED` in any field → `reporter_env_required`
  8. `status_code == 503` on `/mcp` path → `stale_mcp_session`

  Clean lines (`exit_code == 0`, no warnings matching any predicate) are skipped silently. PII redaction runs in scan mode: UUIDs, email addresses, auth tokens, and home-directory paths are replaced with `<LABEL:hash>` placeholders before the title and body are filed; lines are never dropped for containing PII. Redaction can only fail if an unexpected exception is thrown by the guard itself (which would indicate a programming error); in that case the line is skipped with a `skipped` outcome and an error reason in the sweep report. Deduplication stamps a deterministic `observer-dedup:<hash>` label (derived from `(anomaly_class, command_prefix, reporter_channel)`) on every filed issue, loads the existing open GitHub issues (best-effort; proceeds without dedup if GitHub is unavailable), and folds via `issues add_message` when an existing issue carrying the exact same dedup label is found.

- `neotoma plans capture <file> | --all`: persist a harness `.plan.md` file (raw markdown source + structured `plan` row + EMBEDS) into Neotoma via the canonical combined `store` path. `--all` walks `.cursor/plans/`, `.claude/plans/`, `.codex/plans/`, `.openclaw/plans/` under the current repo (or `--repository-root <path>`). Optional `--source-message-entity-id`, `--source-entity-id`, `--source-entity-type` link the plan to the prompting message and a source entity (e.g. an `issue`). See [`docs/subsystems/plans.md`](../subsystems/plans.md).
- `neotoma plans list [--source-entity-id <id>] [--status <s>] [--harness <h>] [--limit <n>]`: list `plan` entities filtered by source / status / harness. Wraps `POST /retrieve_entities`.
- `--pretty`: Output formatted JSON.
- `--no-session`: With no arguments, show intro then command menu (prompt `> `, `? for shortcuts`). No servers started.
- `--no-servers`: With no arguments, enter session with connect-only behavior.
- `--tunnel`: Start HTTPS tunnel (ngrok/cloudflared) with server start commands.
- `--tunnel-provider <provider>`: Force tunnel provider to `ngrok` or `cloudflare` when using `--tunnel`; default is auto-detect from installed tools.
- `--no-update-check`: Disable the update availability check. When enabled (default), the CLI checks the npm registry for a newer version and, if available, prints a one-line notice to stderr. The notice is never shown when `--json` is used.

### Access Policies

- `neotoma access list`: Show effective non-default guest access policies. Resolution follows env var > SchemaMetadata > deprecated config fallback > default; text output includes the winning source.
- `neotoma access set <entity_type> <mode>`: Set a schema metadata guest policy when the schema exists, falling back to the deprecated config file only when SchemaMetadata is unavailable.
- `neotoma access reset <entity_type>`: Clear any deprecated config fallback for the entity type and set schema metadata to the default `closed` policy when the schema exists. If an environment override still wins, output reports the remaining effective mode/source.
- `neotoma access enable-issues`: Set `issue`, `conversation`, and `conversation_message` to `submitter_scoped`.
- `neotoma access disable-issues`: Reset `issue`, `conversation`, and `conversation_message` to effective `closed` policy, subject to any env override.

### Runtime overrides (precedence: flag > env > default)

CLI behavior can be pinned per invocation via flags or across invocations via environment variables. Every runtime override follows the same precedence: explicit flag > environment variable > default.

| Flag             | Environment variable                         | Purpose                                                                                                                                                                                                                                                                                                                           |
| ---------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--api-only`     | `NEOTOMA_API_ONLY`                           | Force API-only transport; fail if API is unreachable.                                                                                                                                                                                                                                                                             |
| `--offline`      | `NEOTOMA_OFFLINE`                            | Force in-process local transport; do not contact a remote API.                                                                                                                                                                                                                                                                    |
| `--env <env>`    | `NEOTOMA_ENV` (`development` / `production`) | Environment selector for server lifecycle commands.                                                                                                                                                                                                                                                                               |
| `--root <path>`  | `NEOTOMA_REPO_ROOT`                          | Source-checkout root when `neotoma` is run with no args.                                                                                                                                                                                                                                                                          |
| `--user-id <id>` | `NEOTOMA_USER_ID`                            | Pin the user scope for read-verb requests (`entities`, `observations`, `relationships`, `timeline`, `schemas`, `sources`, `stats`, `list-recent-changes` (alias `recent`), `memory-export`). The flag wins per call; the env var acts as a session-wide pin; the server falls back to the authenticated user when both are unset. |

`--offline` and `--api-only` are mutually exclusive; setting both (via flag or env) raises an error at startup.

`NEOTOMA_USER_ID` must be non-empty when set — an empty or whitespace-only value causes the CLI to fail fast with a clear error rather than silently falling back to the authenticated user. Resolution is performed by `resolveEffectiveUserId()` in `src/cli/index.ts`.

Any new runtime override must follow this precedence model: add the env var read in the `preAction` hook in `src/cli/index.ts` alongside the existing transport variables, use a `NEOTOMA_`-prefixed name, let an explicit flag override it, and document it in the table above. See `docs/architecture/change_guardrails_rules.mdc` for the cross-cutting guardrails.

### Peer sync and HTTP API (server process)

These are read by the Neotoma HTTP server (not the CLI `preAction` hook) for outbound peer sync and optional release-note enrichment:

| Environment variable      | Purpose                                                                                                                              |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `NEOTOMA_PUBLIC_BASE_URL` | Public base URL of this API (no trailing slash). Required for `POST /peers/{id}/sync` outbound `/sync/webhook` as `sender_peer_url`. |
| `NEOTOMA_LOCAL_PEER_ID`   | Stable id this instance sends as `sender_peer_id`; must match the `peer_id` your counterparty stored for you.                        |
| `GITHUB_TOKEN`            | Optional bearer for GitHub API when `npm_check_update` runs with `include_release_notes: true`.                                      |

`GET /peers/{peer_id}` returns `remote_health` from probing `{peer_url}/health` and semver compat vs the local package version (same rules as `neotoma compat`). See `docs/subsystems/peer_sync.md`.

### Sandbox (server process)

Read by the Neotoma HTTP server when running the public-sandbox profile; no paired CLI flag. Full runbook: [`docs/subsystems/sandbox_deployment.md`](../subsystems/sandbox_deployment.md).

| Environment variable               | Default                       | Purpose                                                                                                                                                                                                                                                                                |
| ---------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEOTOMA_SANDBOX_MODE`             | unset                         | Truthy (`1`/`true`/`yes`) enables all sandbox-only behaviors (ephemeral sessions, anon writes, tighter limits). Also auto-enables tenant-scoped entity ids.                                                                                                                              |
| `NEOTOMA_TENANT_SCOPED_ENTITY_IDS` | follows `NEOTOMA_SANDBOX_MODE` | Truthy forces tenant-scoped deterministic entity ids (salt `generateEntityId` with `user_id`) independent of sandbox mode. Without it (and outside sandbox mode) entity ids are global `hash(entity_type, canonical_name)`, so per-tenant same-named entities collide on one row.        |
| `NEOTOMA_SANDBOX_BASE_URL`         | `http://127.0.0.1:$HTTP_PORT` | Base URL the per-session pack seeder calls back into (`/sandbox/session/new` seeds over HTTP as the new bearer). Defaults to loopback on the server's own port.                                                                                                                          |

### MCP / SSE transport tuning (server process)

These are read by the Neotoma HTTP server when it serves the MCP StreamableHTTP transport at `/mcp`. They keep the long-lived SSE stream alive behind reverse proxies (Cloudflare Tunnel, nginx, ngrok) and clients with idle timeouts. This is a reliability/transport concern; see issue #1483 and the [v0.15.1 release supplement](../releases/in_progress/v0.15.1/github_release_supplement.md).

| Environment variable           | Default  | Purpose                                                                                                                                                                                                                                                                                                                                                                                     |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEOTOMA_MCP_SSE_KEEPALIVE_MS` | `25000`  | Interval (ms) between SSE comment heartbeat frames (`: hb\n\n`) on the MCP GET SSE stream. The frames keep proxies and clients from treating the stream as idle and silently closing it. Set to `0` (or any value `<= 0`) to disable the heartbeat (restores prior behavior); an unset, empty, or non-numeric value uses the default. TCP keepalive on the socket stays enabled regardless. |
| `NEOTOMA_KEEPALIVE_TIMEOUT_MS` | `120000` | Node HTTP `server.keepAliveTimeout` (ms). Extended from Node's 5 s default so idle keep-alive sockets are not closed before typical proxy idle windows (60–300 s), which otherwise surfaces as a mid-stream RST / 502 reconnect cycle.                                                                                                                                                      |
| `NEOTOMA_HEADERS_TIMEOUT_MS`   | `125000` | Node HTTP `server.headersTimeout` (ms). Must exceed `NEOTOMA_KEEPALIVE_TIMEOUT_MS` to avoid a Node bug where the socket is closed before the headers timeout fires.                                                                                                                                                                                                                         |

The MCP transport tuning vars are server-process knobs read in `src/actions.ts`, not CLI `preAction` overrides; they have no paired flag.

### MCP signed shim (`mcp.json` — not CLI `preAction`)

Cursor reads these from the **`env`** block for **`run_neotoma_mcp_signed_stdio_dev_shim.sh`** (they are **not** parsed by `neotoma` CLI `preAction`; document them here for discoverability).

| Environment variable                  | Values                              | Purpose                                                                                                                                                                                                                                |
| ------------------------------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEOTOMA_MCP_USE_LOCAL_PORT_FILE`     | `1` / `true`                        | **Shim:** read `<repo>/.dev-serve/local*http_port*<dev                                                                                                                                                                                 | prod>`(and legacy`local_http_port`for dev) after HTTP bind, then set`MCP_PROXY_DOWNSTREAM_URL`after a successful TCP probe. **CLI:**`resolveBaseUrl()`uses the same rules and probe (after session port env, before`config.json` `base_url`). Repo root order: `NEOTOMA_PROJECT_ROOT`, then `project_root`/`repo_root`in`~/.config/neotoma/config.json`, then `cwd`. |
| `NEOTOMA_MCP_LOCAL_HTTP_PORT_PROFILE` | `dev` / `prod`                      | Which port file the shim and CLI prefer when `NEOTOMA_MCP_USE_LOCAL_PORT_FILE` is on; preset A sets this per MCP slot for parallel dev + prod APIs. If unset, CLI infers from `NEOTOMA_ENV`; shim reads legacy `local_http_port` only. |
| `NEOTOMA_MCP_PORT_PROBE_MS`           | integer ms (200–5000, default 1200) | TCP probe timeout for the port file in both the shim and the CLI.                                                                                                                                                                      |
| `MCP_PROXY_DOWNSTREAM_URL`            | URL                                 | Explicit downstream `/mcp`; used when port-file mode is off, or as fallback when the file is missing / probe fails.                                                                                                                    |

Details, defaults, and verification steps: **`docs/developer/mcp/proxy.md`**.

### Update check (stderr notice)

When the CLI runs in an interactive context (TTY, not `--json`), it may check the npm registry for a newer version of the package. If an update is available, it writes one or two lines to **stderr only** (e.g. "Update available: neotoma 0.2.15 → 0.2.16" and "Run: npm i -g neotoma@latest"). The check is fire-and-forget and does not block startup. To disable: set `NO_UPDATE_NOTIFIER=1` or pass `--no-update-check`. The check is also skipped when `CI` is set. Cache: `~/.config/neotoma/update_check.json` with a 24-hour TTL so the registry is not queried on every run.

### Session (interactive prompt)

- `neotoma session`: Start an interactive session with a persistent `neotoma> ` prompt. Run subcommands (e.g. `storage info`, `api status`) without restarting the CLI. Similar to a native shell or IDE command prompt. Does **not** start servers automatically.
  - Type `help` to list commands.
  - Type `/` to open the live command list (command + description per line), and keep typing to filter matches.
  - Type `exit` or `quit`, or press Ctrl+D, to end the session.
  - Arguments with spaces can be quoted: `request --operation "GET /api/entities"`.
  - Maintenance invariant (TTY redraw): slash suggestions are rendered on the next line with a leading newline, so cursor-up must move `rendered_lines + 1`. See `getSlashSuggestionCursorUpLines()` and `tests/cli/cli_session_startup_ux.test.ts` (regression guard).

### Offline support matrix

- **Data commands (entities, relationships, sources, observations, timeline, store, schemas, stats, corrections, snapshots):** offline-first in-process local transport by default (no API server required).
- **Explicit local path:** pass `--offline`.
- **Strict remote path:** pass `--api-only`.
- **Server lifecycle commands (`api start|stop|status|logs`):** server-management behavior is unchanged and not redirected to local fallback.
- **Local OS inspection (`processes list|kill`):** uses `ps` only; does not use the Neotoma API or offline SQLite transport.
- **Watch/storage/logs/backup:** already local backend commands and continue to run without a running API.

**Transport default rationale:** The CLI defaults to offline-first so that data commands work without a running API (e.g. `neotoma entities list` works right after `neotoma init`). The native SQLite addon is lazy-loaded only when a data command actually uses the local DB, so entry points that never touch the DB (e.g. `neotoma --help`, `neotoma api start`) do not trigger macOS permission prompts. The first time a user runs a data command, the local DB may be opened and the OS may show a one-time permission prompt for the native addon; this is an accepted tradeoff for out-of-the-box usability. Use `--api-only` if you want to avoid loading the local DB and require the API instead.

**Examples:**

```bash
# Session only (no servers; use when API is already running)
neotoma session
# neotoma> storage info
# neotoma> api status
# neotoma> exit

# Session with dev + prod servers (same as running `neotoma` with no args)
neotoma session --servers
```

### Initialization

- `neotoma init`: Initialize Neotoma for first-time use. Creates data directories, initializes the SQLite database, and can prompt to create encryption keys for privacy-first mode. Default flow is auto-detection-first: if a source checkout is detected, init targets project `.env`; otherwise it configures user `.env` at `~/.config/neotoma/.env` without prompting for a source path. Source-path prompts only appear in personalization mode. In interactive mode (TTY), init can prompt to set `OPENAI_API_KEY` for LLM extraction. Init can also delegate harness setup through the same MCP and CLI instruction path used by `neotoma setup`.
  - `--data-dir <path>`: Custom data directory path. Default: `./data` (if in repo) or `~/neotoma/data` (if installed globally).
  - `--force`: Overwrite existing configuration.
  - `--skip-db`: Skip database initialization.
  - `--skip-env`: Skip interactive `.env` creation and variable prompts (e.g. for CI or non-interactive use).
  - `--project-local`: Store the Neotoma config in `.neotoma/config.json` in the current directory (project-scoped) instead of the user-level `~/.config/neotoma/config.json`. The CLI reads this project-local config automatically for all subsequent commands run from that directory via `readEffectiveConfig`, which checks for `.neotoma/config.json` before falling back to the user-level config. Trust boundary: project-local config is only loaded when the containing directory is owned by the current user (prevents untrusted directories from silently overriding user settings). Use this when you want per-project Neotoma configuration independent of the user-level setup.
  - `--safe`: Dry-run mode. Reports what `init` would do (create directories, write config, run migrations) without writing any files or making any changes. Output lists each planned action with a check mark or blocker reason. Exit code is 0 if all planned actions would succeed; exit code 1 if any blocker is detected (e.g. config already exists without `--force`, parent directory not writable). Combine with `--json` to get machine-readable output. Note: `--safe` checks the filesystem layout planned by `init`; it does not simulate authentication or preflight steps.

**Examples:**

```bash
# Basic initialization
neotoma init

# Initialize with custom data directory
neotoma init --data-dir /path/to/data

# Store config in current project directory instead of user home
neotoma init --project-local

# Preview what init would do without making any changes
neotoma init --safe

# Dry-run with machine-readable output
neotoma init --safe --json

# Combine: dry-run scoped to current project
neotoma init --safe --project-local
```

**What it creates:**

- Data directories: `<data-dir>/`, `<data-dir>/sources/`, `<data-dir>/logs/` (event log is `<data-dir>/logs/events.log`)
- SQLite database: `<data-dir>/neotoma.db` (with WAL mode enabled)
- Encryption key (if user chooses key-derived auth when prompted): `~/.config/neotoma/keys/neotoma.key` (mode 0600).
- Environment file target: project `<checkout>/.env` when checkout is detected, otherwise `~/.config/neotoma/.env`
- Config file: `~/.config/neotoma/config.json` (default) or `.neotoma/config.json` in the current directory when `--project-local` is given.

**Runtime overrides** for `neotoma init`:

| Precedence | Source | Description |
|------------|--------|-------------|
| 1 (highest) | `--data-dir` flag | Explicit data directory path |
| 2 | `NEOTOMA_DATA_DIR` env var | Environment variable override |
| 3 (default) | Auto-detected or `~/neotoma/data` | Resolved at startup |

Config scope for `neotoma init` is a binary switch: `--project-local` writes to `.neotoma/config.json` in cwd; without the flag, init writes to `~/.config/neotoma/config.json`. All subsequent commands that call `readEffectiveConfig` will read the project-local file when present (and owned by the current user).

### Harness setup

- `neotoma setup`: One-shot, idempotent harness setup. It runs init when needed, configures MCP entries, applies agent CLI instruction files, installs lifecycle hooks or the Claude Code plugin for the selected harness, then patches permission allowlists where the harness supports them.
  - `--tool <claude-code|cursor|codex|openclaw|claude-desktop|windsurf|continue|vscode>`: Target harness. If omitted, `neotoma status` supplies the current tool hint when available. `windsurf`, `continue`, and `vscode` are MCP-only targets (no skills or hook installation; setup writes the MCP config entry only).
  - `--install-scope <project|user|both>`: Scope for MCP entries and agent CLI instruction files.
  - `--scope <project|user|both>`: Permission-file scope only. This is intentionally separate from `--install-scope`.
  - `--mcp-transport <a|b|c|d|e>`: Same transport presets as `neotoma mcp config`.
  - `--rewrite-neotoma-mcp`: Rewrite existing Neotoma MCP entries in the selected install scope.
  - `--skip-hooks`: Skip lifecycle hook/plugin installation.
  - `--all-harnesses`: Infer hook-capable harnesses from MCP configs and install hooks for all of them. The default remains one harness via `--tool` or the `neotoma status` hint.
  - `--dry-run`: Plan the setup without writing files.
  - `--yes`: Suppress prompts in init, MCP config, CLI instruction config, and hook install paths.
  - `--skip-permissions`: Skip permission-file writes.

`neotoma setup` writes a structured report when the global `--output json` flag is active. The report includes `steps[]`, `permission_patches`, `doctor_before`, `doctor_after`, `overall_ok`, `verify_line`, and `privacy_transport_summary`, which lets agent-led installs show exactly what changed.

After the JSON report, `neotoma setup` always emits two plain-text lines to stdout (regardless of `--json` / `--pretty` mode):

1. **Install-verification line** — a single grep-able line confirming the binary path, version manager, version, data directory, and MCP transport. Format: `Neotoma installed at <path> (resolved via <manager>; v<version>; data_dir=<dir>; mcp=<transport>)`. Agent harnesses grep this line to confirm install succeeded without parsing JSON.
2. **Privacy/transport summary** — `Transport: local stdio MCP (no network egress). Override with --mcp-transport=http for signed HTTP /mcp proxy.` Surfaces the data-egress model for privacy-conscious evaluators.

Use `neotoma setup --tool <harness> --yes` for the normal greenfield path. Use `neotoma mcp config` or `neotoma cli config` when only one layer needs repair.

### Reporter

One-shot onboarding for friction reporters (testers or user agents who file issues via Neotoma):

- `neotoma reporter setup`: Orchestrate the full reporter setup in one command.
  - `--tool <tool>`: Target harness (`claude-code|cursor|codex|openclaw|claude-desktop`). Auto-detected from cwd when omitted.
  - `--git-sha <sha>`: Default `reporter_git_sha` embedded in every submitted issue.
  - `--app-version <version>`: Default `reporter_app_version` embedded in every submitted issue.
  - `--default-visibility <public|private>`: Default issue visibility (default: `public`).
  - `--dry-run`: Plan the setup without writing files or applying changes.
  - `--print-block`: Print a copy-pastable env-var block instead of writing the project config file.

The command runs four steps in sequence: (1) version check — warns when the installed CLI is older than the minimum required version; (2) preflight — applies harness permission-file allowlist entries via `neotoma preflight --apply`; (3) config write — persists the reporter defaults to `.neotoma/reporter.json` in the project root so subsequent `neotoma issues create` calls pick them up automatically; (4) smoke-test hint — prints a ready-to-run dry-run command. The structured JSON report includes `tool`, `dry_run`, `installed_version`, `version_ok`, `steps[]`, `reporter_config`, `reporter_config_path`, `smoke_test_command`, `overall_ok`, and `summary`.

### Preflight

- `neotoma preflight`: Check or apply harness permission-file entries for Neotoma.
  - `--tool <tool>`: Target harness. Accepted values: `claude-code`, `cursor`, `codex`, `openclaw`, `claude-desktop`, `windsurf`, `continue`, `vscode`.
  - `--apply`: Write the allowlist file(s) directly instead of printing a copy-paste block. Only has effect for `claude-code`, `cursor`, and `codex`; other harnesses do not expose a writable allowlist file.
  - `--scope <project|user|both>`: Permission scope for `claude-code` (default: `both` when `--apply` is set).
  - `--dry-run`: Plan the write without modifying files.

**Allowlist-capable harnesses** (`claude-code`, `cursor`, `codex`): without `--apply`, prints a copy-paste block; with `--apply`, writes the allowlist file(s) directly. `claude-code` writes both project (`.claude/settings.local.json`) and user (`~/.claude/settings.json`) scopes by default. `neotoma setup` calls the same write path, so running preflight before setup is only necessary when you need the allowlist entry in place before `npm install -g neotoma` runs.

**MCP-only harnesses** (`claude-desktop`, `openclaw`, `windsurf`, `continue`, `vscode`): these harnesses have no writable command allowlist. Passing `--apply` is accepted but produces no file write; preflight prints a message directing you to `neotoma setup --tool <tool>` to configure the MCP server entry instead.

The structured report includes `tool`, `apply`, `dry_run`, `patches[]`, `already_ok`, `copy_paste_block`, and `overall_ok`.

### Reset

- `neotoma reset`: Reset local Neotoma state to a clean slate.
  - Backs up and removes local Neotoma state (config/env/keys/instructions and known local data directories).
  - Always backs up a data directory before removing it.
  - If `.env` sets `NEOTOMA_DATA_DIR`, that configured data directory is protected: reset does not back it up or remove it.
  - Cleans Neotoma MCP entries from user/project MCP configs.
  - Attempts global uninstall via `npm uninstall -g neotoma` (best effort; failures are reported but do not roll back completed local cleanup).
  - `-y, --yes`: Skip confirmation prompt.

### Authentication

CLI uses the same auth patterns as MCP and REST API. Local CLI commands can run without login in development, but MCP OAuth now requires key-auth preflight.

- `neotoma auth status`: Show auth mode (none, dev-token, key-derived) and user details. Works without prior login.
- `neotoma auth login`: OAuth PKCE flow for MCP Connect (Cursor) setup. Browser flow requires key authentication (`/mcp/oauth/key-auth`) first. Use `--tunnel` to read the API base URL from `/tmp/ngrok-mcp-url.txt` (for testing OAuth when the API is behind a tunnel).
- `neotoma auth logout`: Clear stored OAuth credentials (MCP Connect only).
- `neotoma auth mcp-token`: Print MCP auth token derived from private key (when encryption is enabled). Add to mcp.json headers.
- If key-authenticated OAuth is unavailable, configure `Authorization: Bearer <NEOTOMA_BEARER_TOKEN>` for MCP instead of OAuth.

- `neotoma inspector admin unlock`: Redeem a feedback-admin challenge via the same CLI AAuth signer used for signed API traffic; prints an Inspector URL to **`/feedback/admin-unlock?challenge=…`** (and optional `--open`). Omit `--challenge` to mint one from the API. When the Inspector dev server runs on another origin, set `NEOTOMA_INSPECTOR_BASE_URL` or pass `--inspector-base`. Use `--skip-browser-url` to suppress the printed link in text mode. When the HTTP API binds a non-default port, set **`NEOTOMA_MCP_USE_LOCAL_PORT_FILE=1`** and **`NEOTOMA_MCP_LOCAL_HTTP_PORT_PROFILE`** when needed (same rules as the MCP signed shim) so `--base-url` resolution reads the matching `.dev-serve/local_http_port_*` file after a successful TCP probe; set **`NEOTOMA_PROJECT_ROOT`** if the file lives outside `cwd`.

### Access Policies

- `neotoma access list`: Show effective non-default guest access policies. Resolution follows env var > SchemaMetadata > deprecated config fallback > default; text output includes the winning source.
- `neotoma access set <entity_type> <mode>`: Set a schema metadata guest policy when the schema exists, falling back to the deprecated config file only when SchemaMetadata is unavailable.
- `neotoma access reset <entity_type>`: Clear any deprecated config fallback for the entity type and set schema metadata to the default `closed` policy when the schema exists. If an environment override still wins, output reports the remaining effective mode/source.
- `neotoma access enable-issues`: Set `issue`, `conversation`, and `conversation_message` to `submitter_scoped`.
- `neotoma access disable-issues`: Reset `issue`, `conversation`, and `conversation_message` to effective `closed` policy, subject to any env override.

### MCP configuration

Commands for managing MCP server configuration files (Cursor, Claude Code, Windsurf, etc.). The CLI uses symmetric verbs: `guide` is read-only guidance; `config` mutates files.

- `neotoma mcp guide`: Show MCP configuration guidance for Cursor and other clients.
  - `--no-check`: Skip checking for existing MCP config files (default: check and suggest `mcp config` if servers are missing).
  - Prints example JSON config for Cursor with URL or stdio server entries.
  - After printing config, scans current directory for MCP config files and suggests running `neotoma mcp config` if dev or prod servers are missing.

- `neotoma mcp config`: Scan for MCP config files in current directory and subdirectories, detect whether dev and prod Neotoma servers are configured, and offer to install missing servers.
  - `--rewrite-neotoma-mcp`: After you pick install scope and transport, rewrite **existing** `neotoma-dev` / `neotoma` (or Claude Desktop `mcpsrv_*`) entries in that scope to match the preset. Without this flag, configs that already have both slots are skipped so transport changes only apply where something was still missing.
  - `--user-level`: Include user-level MCP config paths (e.g. `~/.cursor/mcp.json`, Claude, Windsurf) in scan (default: project-local only).
  - `--install-hooks` / `--no-hooks`: Install or skip matching Neotoma lifecycle hooks when a configured MCP path maps to a hook-capable harness. Hook installation is enabled by default for non-JSON runs; use `--no-hooks` to limit the command to MCP config only.
  - `--yes`: Skip hook installation confirmation prompts. MCP server config prompts still follow the normal interactive flow.
  - `--mcp-transport <a|b|c|d|e>`: Transport preset. TTY installs prompt when omitted; non-TTY defaults to `b`.

**MCP transport presets:**

| Preset | Use when                                                                        | Notes                                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `a`    | You want signed HTTP `/mcp` proxy entries with AAuth attribution.               | Requires a reachable Neotoma API for each configured slot (`neotoma-dev` → dev, `neotoma` → prod).                                                                            |
| `b`    | You want the lowest-friction local MCP setup.                                   | Default. Packaged npm installs launch Neotoma directly over stdio; source checkouts use the unsigned dev shim.                                                                |
| `c`    | You explicitly want direct stdio entries.                                       | Best for simple local clients that do not need HTTP proxy parity.                                                                                                             |
| `d`    | You want both MCP slots to point at prod HTTP `/mcp`.                           | Signed proxy path; requires prod API reachability.                                                                                                                            |
| `e`    | You want both MCP slots to point at prod HTTP `/mcp` using the local port file. | Signed proxy using `NEOTOMA_MCP_USE_LOCAL_PORT_FILE=1` + `NEOTOMA_MCP_LOCAL_HTTP_PORT_PROFILE=prod`. Requires prod API reachable on the port recorded by the local port file. |

- Scans for known config file patterns:
  - **Cursor:** `.cursor/mcp.json`, `.mcp.json` (project), `~/.cursor/mcp.json` (user-level with `--user-level`)
  - **Claude Code:** `claude_desktop_config.json` (project or user-level with `--user-level`):
    - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
    - Linux: `~/.config/Claude/claude_desktop_config.json`
    - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
  - **Windsurf:** `mcp_config.json` (project or user-level with `--user-level`):
    - macOS/Linux: `~/.codeium/windsurf/mcp_config.json`
    - Windows: `%APPDATA%\Codeium\Windsurf\mcp_config.json`
  - **Continue:** `config.json` (user-level with `--user-level`):
    - All platforms: `~/.continue/config.json`
  - **VS Code (Copilot Chat MCP):** `.vscode/mcp.json` (project-level, picked up by directory scan)
- For each found config, checks for `neotoma-dev` and `neotoma` server entries (based on `command` script names or `url` patterns). In Claude Desktop's `claude_desktop_config.json`, new entries use `mcpsrv_neotoma_dev` and `mcpsrv_neotoma`, and legacy `neotoma-dev` / `neotoma` keys are reported for repair because Claude Desktop validates server IDs as UUIDs or `mcpsrv_*` tags.
- If any config is missing dev or prod servers, prompts to add them with absolute script paths.
- If no config files found, offers to create `.cursor/mcp.json` in current directory.
- Uses Neotoma source root (from `findRepoRoot`, config, or `NEOTOMA_REPO_ROOT`) to resolve absolute script paths for the selected transport. Preset `a` emits signed shim / `mcp proxy --aauth` with dev+prod downstreams as above; `b` emits unsigned dev shim; `c` emits direct stdio scripts; `d` emits signed shim with prod downstream for both MCP server entries.
- After install, verifies or installs lifecycle hooks for hook-capable harnesses inferred from the configured MCP paths (for example `.cursor/mcp.json` → Cursor hooks, `.codex/config.toml` → Codex hooks). Harnesses without an auto-installer print the matching manual instruction.
- After install, shows a reminder to run `neotoma cli config`; when MCP servers are installed interactively, it can also prompt to add CLI instructions if missing.
- `neotoma mcp check` is retained as a deprecated alias for `neotoma mcp config` during the migration window.

**MCP transport presets:**

- **A:** signed shim + AAuth. Installs **both** `neotoma-dev` and `neotoma`: dev slot → dev API `http://127.0.0.1:3080/mcp` (default when `neotoma-dev` omits `MCP_PROXY_DOWNSTREAM_URL`, matching `run_neotoma_mcp_signed_stdio_dev_shim.sh`), prod slot → prod API `http://127.0.0.1:3180/mcp` (via `scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh` or packaged `neotoma mcp proxy --aauth`). Requires matching API processes to be reachable.
- **B (default):** unsigned/local stdio. Packaged npm installs launch `dist/index.js` directly over stdio so local MCP does not require a separate API process; source checkouts use `scripts/run_neotoma_mcp_stdio_dev_shim.sh`, and prod entries add `NEOTOMA_ENV=production`.
- **C:** direct stdio. Uses `scripts/run_neotoma_mcp_stdio.sh` for dev and `scripts/run_neotoma_mcp_stdio_prod.sh` for prod. Reconnect the MCP client after code changes.
- **D:** signed prod parity. Signed shim with `MCP_PROXY_DOWNSTREAM_URL=http://127.0.0.1:3180/mcp` for **both** slots (including `neotoma-dev`), so both MCP entries hit the prod HTTP `/mcp` when the prod API is on the default port.

**Dev vs Prod detection patterns:**

- **Dev:** `command` contains `run_neotoma_mcp_stdio.sh`, `run_neotoma_mcp_stdio_dev_watch.sh`, `run_neotoma_mcp_stdio_dev_shim.sh`, `run_neotoma_mcp_signed_stdio_dev_shim.sh`, `run_neotoma_mcp_unsigned_stdio_dev_shim.sh`, or the legacy forwarder `run_neotoma_mcp_unsigned_stdio_proxy.sh` under a dev server id, or `url` contains `localhost:3080/mcp` or `127.0.0.1:3080/mcp`. During connect-only sessions, the currently selected instance port is also considered for dev if the active env is dev.
- **Prod:** `command` contains `run_neotoma_mcp_stdio_prod.sh`, `run_neotoma_mcp_stdio_prod_watch.sh`, `run_neotoma_mcp_signed_stdio_dev_shim.sh`, `run_neotoma_mcp_unsigned_stdio_dev_shim.sh`, or the legacy forwarder `run_neotoma_mcp_unsigned_stdio_proxy.sh` under a prod server id / prod downstream URL, or `url` contains `localhost:3180/mcp`, `127.0.0.1:3180/mcp`, or `neotoma.fly.dev/mcp`. During connect-only sessions, the currently selected instance port is also considered for prod if the active env is prod.

**Example workflow:**

```bash
# Show config guidance and check if servers are configured
neotoma mcp guide

# Scan project-local MCP configs and add missing servers
neotoma mcp config

# Scan including user-level configs (Cursor, Claude, Windsurf)
neotoma mcp config --user-level

# Deterministically install direct stdio entries without the transport prompt
neotoma mcp config --user-level --mcp-transport c

# Configure MCP and install matching hooks without hook prompts
neotoma mcp config --user-level --yes

# Interactive: refresh user-level Cursor/Claude JSON entries to transport D even when dev+prod already exist
neotoma mcp config --rewrite-neotoma-mcp
```

### CLI instructions (prefer MCP when available, CLI as backup)

Commands to ensure agent instructions tell agents to use the Neotoma CLI when running locally and MCP when remote. Like MCP, `guide` is read-only and `config` mutates files:

- `neotoma cli guide`: Show guidance for adding the "prefer MCP when available, CLI as backup" rule to Cursor, Claude, and Codex (project: `.cursor/rules/`, `.claude/rules/`, `.codex/`; user: `~/.cursor/rules/`, `~/.claude/rules/`, `~/.codex/`). Does not modify files.
- `neotoma cli config`: Scan only paths that each IDE actually loads (applied paths). Reports Cursor, Claude, and Codex separately and, with `--yes`, writes missing or stale files to the selected scope.
  - `--scope <project|user|both>`: Choose where to apply instruction files. This is separate from `neotoma setup --scope`, which controls permission-file patches.
  - `--yes`: Apply without prompting. Without `--yes`, the command reports what would change.
- `neotoma cli-instructions config` and `neotoma cli-instructions check` are deprecated aliases for `neotoma cli guide` and `neotoma cli config`.
- `neotoma instructions print`: Print the first fenced code block from `docs/developer/mcp/instructions.md` bundled with this package (same text MCP sends to clients). Use `--format md` to wrap output in a markdown fence, or `--json` with global JSON output mode for `{ path, body }`.
  - `--user-level` / `--no-user-level`: Include or exclude user-level paths in scan (default: include).

See `docs/developer/agent_cli_configuration.md` for the rule text and strategy.

### Entities

- `neotoma entities list`:
  - `--type <entityType>`
  - `--search <query>`
  - `--limit <n>`
  - `--offset <n>`
  - `--include-merged`
  - `--status <value>`: Server-side exact-match filter on the snapshot `status` field. Returns only entities whose `snapshot.status` equals the given value (e.g. `--status active`). Applied before pagination. Each returned entity includes `status` in its snapshot projection even without `--include-snapshots`. Passing `--status ""` is not meaningful; omit the flag to return all statuses.
  - `--updated-since <iso>` / `--since <iso>`: Return only entities whose `updated_at` is >= this ISO 8601 timestamp.
  - `--created-since <iso>`: Return only entities whose `created_at` is >= this ISO 8601 timestamp.
- `neotoma entities get <id>`
- `neotoma entities search [identifier]`:
  - Preferred: positional `identifier` or `--identifier <id>`
  - Compatibility alias: `--query <id>` (equivalent to `--identifier`)
  - If both `--identifier` and `--query` are provided, they must match
- `neotoma entities import <file>`: bulk-import entities from a JSONL file (one entity JSON object per line) by chunking them into batched `POST /store` calls.
  - `--batch-size <n>`: entities per store call (default `200`). Lower it if a request exceeds the server body limit.
  - `--idempotency-prefix <prefix>`: prefix for the per-chunk idempotency key (default derived from the file name). Re-running with the same prefix and file is a safe no-op, so a large backfill can be replayed without duplicating data.
  - `--user-id <userId>`: store under a specific user.
  - `--commit`: actually write. Without it the command runs in dry-run/plan mode.
  - The `/store` endpoint already writes each batch transactionally; this command owns file reading, chunking, and per-chunk idempotency. For very large backfills, this is the supported "replay from an external source" path.
- `neotoma entities export`: the inverse of `entities import` — pages through all entities and emits import-compatible JSONL (one object per line, `entity_type` plus the snapshot fields at the top level), so an instance can be exported and rebuilt with a matched command pair. See [`exit_rebuild_test.md`](exit_rebuild_test.md) for the leave-and-rebuild protocol this supports.
  - `--type <entityType>`: only export this entity type.
  - `--out <path>`: write JSONL here (default: stdout).
  - `--with-relationships`: also write a companion `<out>.relationships.json` of typed edges that `relationships create --file` re-imports, for a full entities-plus-edges round-trip.
  - `--page-size <n>`: entities fetched per page (default `500`).
  - `--include-merged`: include merged entities (default: exclude).
  - `--user-id <userId>`: export under a specific user scope.
  - Export reflects only what the snapshot captured: fields an entity's registered schema does not declare are not in the snapshot and do not survive this path. Declare every field that matters before relying on export for a rebuild.

### Sources

- `neotoma sources list`:
  - `--search <query>`
  - `--mime-type <mimeType>`
  - `--limit <n>`
  - `--offset <n>`

### Observations

- `neotoma observations list`:
  - `--entity-id <id>`
  - `--entity-type <type>`
  - `--limit <n>`
  - `--offset <n>`

### Relationships

- `neotoma relationships create --source-entity-id <id> --target-entity-id <id> --relationship-type <type>`: Create one relationship.
  - `--metadata <json>`: attach relationship metadata.
  - `--file <path>`: create a batch from a JSON array, or an object with `relationships: [...]`. Each entry uses `relationship_type`, `source_entity_id`, `target_entity_id`, and optional `metadata`.
- `neotoma relationships list <entityId>`:
  - `--direction <direction>`: inbound, outbound, or both
- `neotoma relationships get-snapshot <relationshipType> <sourceEntityId> <targetEntityId>`: Get relationship snapshot with provenance (observations). Relationship type is one of: PART_OF, CORRECTS, REFERS_TO, SETTLES, DUPLICATE_OF, DEPENDS_ON, SUPERSEDES, EMBEDS.
- `neotoma relationships restore <relationshipType> <sourceEntityId> <targetEntityId>`: Restore a deleted relationship (creates restoration observation). Optional: `--reason <reason>`.

### Timeline

- `neotoma timeline list`:
  - `--start-date <date>`
  - `--end-date <date>`
  - `--event-type <type>`
  - `--entity-id <id>`: Filter by entity ID
  - `--user-id <userId>`: Filter by user ID (default: authenticated user)
  - `--limit <n>`
  - `--offset <n>`
  - `--order-by <column>`: `event_timestamp` (default, document dates) or `created_at` (when the timeline row was written)

### Schemas

- `neotoma schemas list`
- `neotoma schemas get <entityType>`
- `neotoma schemas audit-fragments [entityType]`: Report undeclared `raw_fragments` awaiting schema declaration (fields stored on observations but excluded from the entity snapshot because no active schema declares them). Read-only. Outputs, per type, the undeclared `fragment_key`s with occurrence / affected-entity counts and a `schema_missing` flag, plus `total_entity_types` / `total_undeclared_fields` rollups. Optional positional `entityType` (or `--entity-type <type>`) scopes the audit to one type; `--user-id <id>` overrides the resolved user. Maps to `POST /audit_undeclared_fragments` / MCP `audit_undeclared_fragments`.

### Peers

Cross-instance peer sync. Backed by `src/services/sync/` and the HTTP `/peers` surface; see [`docs/subsystems/peer_sync.md`](../subsystems/peer_sync.md) for the underlying model and the env vars (`NEOTOMA_PUBLIC_BASE_URL`, `NEOTOMA_LOCAL_PEER_ID`) required on the API process.

- `neotoma peers add --peer-id <id> --name <name> --url <url> --types <csv>`: Register a peer.
  - `--direction <push|pull|bidirectional>` (default `bidirectional`).
  - `--sync-scope <all|tagged>` (default `all`). With `tagged`, only entities whose snapshot lists this peer in `sync_peers` are eligible.
  - `--auth-method <shared_secret|aauth>` (default `shared_secret`).
  - `--shared-secret <secret>`: HMAC peer secret when `auth-method=shared_secret`.
  - `--peer-public-key-thumbprint <thumbprint>`: Expected AAuth thumbprint when `auth-method=aauth`.
  - `--conflict-strategy <last_write_wins|source_priority|manual>` (default `last_write_wins`).
  - `--target-user-id <id>`: Receiver `user_id` on the peer instance.
- `neotoma peers list`: List configured peers.
- `neotoma peers status <peer_id>`: Show peer config plus `remote_health` (probed `{peer_url}/health`) and semver compatibility vs the local package version.
- `neotoma peers sync <peer_id>`: Run a bounded bilateral catch-up against the peer (push local changed observations, pull remote snapshots through `/sync/entities`).
  - `--limit <n>`: Cap observations / snapshots per direction.
- `neotoma peers remove <peer_id>`: Deactivate the peer (does not delete prior `observation_source: "sync"` rows).

### Interpretations

- `neotoma interpretations list`: List interpretation runs.
  - `--source-id <id>`: Filter by source.
  - `--limit <n>` / `--offset <n>`: Pagination.
- `neotoma interpretations create --source-id <id> --entities <path>`: Create an interpretation row for an existing source from agent-extracted flat entities.
  - `--interpretation-config <json>`: Audit configuration such as extractor type/version, model, prompt hash, schema version, and agent notes.
  - `--relationships <path>`: Optional JSON array of relationship refs to create after entity observations.
  - `--idempotency-key <key>`: Optional replay-safe operation key.

### Store

- `neotoma store`:
  - Preferred structured input: `--entities <json>` or `--file <path>`
  - Compatibility alias: `--json=<json>` maps to structured `--entities` for backward compatibility.
    - Use `--json=` (equals, no space) so the payload is parsed as entities input.
    - Bare `--json` (without `=`) remains the global output-format flag.
  - `--file <path>`: Path to JSON file containing entity array. Use for long payloads.
  - `--observation-source <kind>`: Classify the *kind* of write. Closed enum — `sensor | llm_summary | workflow_state | human | import | sync` (default `llm_summary`). **Breaking change in v0.18.x (was open in v0.17):** arbitrary strings are rejected. Put custom v0.17 labels (e.g. `cboe_live`, `stale_cache`) in the free-form `data_source` field and map the closest enum value here. See [Migrating from v0.17 to v0.18](fleet_onboarding.md#migrating-observation_source-from-v017-to-v018).
  - `--interpretation-source-id <id>` / `--interpretation-source-ref <structured|unstructured>` plus `--interpretation-config <json>`: Opt into Source -> Interpretation -> Observation provenance for source-derived extraction. Omit for ordinary already-structured/chat-native facts.
  - Silent-failure guard (v0.5.1+): when a commit-mode store returns `entities_created=0`, no resolved entities, and is not an idempotency replay (`replayed: true`), the CLI emits a non-fatal stderr warning so agents/humans don't mistake an empty result for success. Typical root cause: fields nested under `attributes` (see v0.5.0 breaking change) or mismatched `user_id` scope.
  - Idempotency replays: `POST /store` returns `replayed: true` when a request is a deterministic re-commit of a previously committed `(user_id, idempotency_key)` tuple. Use this to distinguish "same call, no new work" from "call produced zero entities."

### Ingest

- `neotoma ingest`: Atomic structured-entities + source-file ingest (composes `/store`).
  - `--entities <path>` (required): JSON file containing the entity array extracted by the caller.
  - `--source-file <path>` (required): Raw source artifact (PDF, transcript, CSV, etc.) attached as provenance.
  - `--user-id <id>` / `--idempotency-key <key>` / `--file-idempotency-key <key>`: same semantics as `neotoma store`.
  - `--plan` / `--dry-run`: Preview planned actions without committing.
  - `--strict`: Refuse silent merges (schema `canonical_name_fields` must match, or `--target-id` must be supplied).
  - `--source-upload` (v0.5.1+): Force base64 upload of the source file via `file_content`. Use this when the CLI and API run on different machines so the server can't read the CLI's local filesystem.
  - `--source-content` (v0.5.1+): Alias for `--source-upload`.
  - Auto-upload (v0.5.1+): when the resolved base URL is non-localhost (anything other than `localhost`, `127.0.0.1`, `::1`, `0.0.0.0`), the CLI automatically switches from `file_path` to `file_content` so remote deployments work without any flag. Localhost base URLs continue to send `file_path` so the server reads the artifact directly from disk.
  - Upload size limit: the server caps JSON bodies at 10 MB (`express.json({ limit: "10mb" })`). Accounting for base64 overhead (~1.37×), the CLI refuses to upload source files larger than ~7.5 MB with a clear error pointing operators at a localhost API as the alternative.

### MCP/CLI parity note

For chat persistence recipes, MCP and CLI use the same underlying store contract. In CLI examples:

- entity lookup supports positional identifier, `--identifier`, and compatibility alias `--query`
- structured store supports preferred `--entities`/`--file` and compatibility alias `--json=<json>`

### Upload

- `neotoma upload <path>`: Store an unstructured file (raw upload with optional AI interpretation).
  - `--no-interpret`: Skip AI interpretation after store.
  - `--idempotency-key <key>`: Idempotency key (default: content hash).
  - `--mime-type <type>`: MIME type (default: inferred from extension).
  - `--local`: Run store and interpretation in-process without starting or connecting to the API server. Uses the same `.env`, database, and storage backend as the server. Requires `neotoma init` to have been run. Encryption-off only (local dev user) for MVP. Example: `neotoma upload --local invoice.pdf`.

### Analyze

- `neotoma analyze <filePath>`

### Stats

- `neotoma stats`

### Watch (local backend only)

- `neotoma watch`: Stream record changes (entities, observations, sources, etc.) as they happen. Uses local dev user when encryption is off (no login needed).
  - `--interval <ms>`: Polling interval in ms (default: 400).
  - `--json`: Output NDJSON (one JSON object per line).
  - `--human`: Output one sentence per change (e.g. "Created person \"George\"", "Updated relationship \"wife\" for person \"Alice\" with person \"Bob\""). No timestamps, emoji, or IDs.
  - `--tail`: Only show changes from now (skip existing records).
  - When encryption is on, set `NEOTOMA_KEY_FILE_PATH` or `NEOTOMA_MNEMONIC`.

### Processes (local OS only)

- `neotoma processes list` (default for `neotoma processes`): Scan `ps` for processes whose argv matches Neotoma checkout paths, `tsx watch src/actions.ts`, `run-neotoma-api-node-watch.sh` / `node --watch-path` + `src/actions.ts`, `run_neotoma_mcp*.sh`, `run_watch_build_launchd.sh`, `mcp proxy`, orchestrator (`pick-port` / `concurrently`), `tsc --watch`, `esbuild`, Cursor hooks under the repo, etc. **TCP listen ports** per PID come from a single `lsof -nP -iTCP -sTCP:LISTEN -F pn` pass (comma-separated in the PORTS column, `-` when none); if `lsof` is missing or fails, PORTS stays `-`. Text mode adds **ENV** (`dev` \| `prod` \| `mix` \| `?`) and **CAT** (comma-separated tags: `server`, `mcp`, `build`, `orchestrator`, `tunnel`, `tooling`, `other`) inferred heuristically from argv and listen ports; a footer line explains the encoding. The full `ps` command line is **word-wrapped within the COMMAND column** to the current terminal width (continuation lines are blank under the fixed columns so COMMAND stays aligned). `--json` prints `{ "processes": [...] }` with `ports` (number array), `env_hint`, `categories` (string array), and each full `command` on one line.
- `neotoma processes servers`: Same `ps` + `lsof` scan as `list`, but only rows with category **`server`** (not limited to default HTTP ports). Rows are **deduplicated by server stack**: all processes in a connected parent-child chain that share the same stack context are collapsed into a single row showing the PID that actually holds the TCP listener (or the deepest child when no listener is detected). Prints a compact table: **PID** (the representative listener PID for the stack), **ENV** (resolved `NEOTOMA_ENV` when readable, otherwise inherited from the nearest connected server/orchestrator stack when the stack is unambiguous, else the same heuristic as `list`), **PORT** (all TCP listen ports visible anywhere in that connected server stack, comma-separated, with **`3080`** / **`3180`** listed first when present; `-` when none of the connected rows expose a listener), **LAUNCHAGENT** (macOS LaunchAgent label inferred from the process ancestry, plist path, or known launchd wrapper / `npm run ...` entrypoint such as `com.neotoma.dev-server`; `-` when not inferable), **DATA_DIR** (`NEOTOMA_DATA_DIR` from procfs or argv on the PID itself, otherwise inherited from the connected server stack when available, else `-`), **LOGS** (best-effort deduped paths: default event log per `src/config.ts` when data dir / `NEOTOMA_EVENT_LOG_*` overrides are known, app **`NEOTOMA_LOGS_DIR`** or data-relative `logs` / `logs_prod` when distinct from the parent directory of the event log, **`~/.config/neotoma/logs/api.log`** (dev) or **`logs_prod/api.log`** (prod) for `neotoma api start --background`, optional repo **`data/logs/session.log`** / `session.prod.log` when **`NEOTOMA_PROJECT_ROOT`** is set). `--watch` keeps the table running and refreshes it every few seconds until interrupted; use `--interval <ms>` to override the default 3000 ms cadence. In `--json --watch` mode it emits one JSON object per refresh line with `refreshed_at`. Plain `--json` prints `{ "servers": [ { "pid", "neotoma_env", "port", "launchagent", "data_dir", "log_paths" } ] }` (`log_paths` is a string array; `port` is comma-separated).
- `neotoma processes kill <pids...>`: One or more PIDs as separate tokens (e.g. `neotoma processes kill 92450 18852`) or a single comma/space string in quotes. Re-runs the same classifier; **only PIDs that appear in a fresh scan** are signalled (prevents typos from killing unrelated processes). Default signal is **SIGTERM**; use `--signal SIGKILL` when needed. `--dry-run` prints the plan. On a TTY, prompts once unless `--force`. Non-TTY requires `--force`.

### Mirror

- `neotoma mirror enable`: Enable the markdown mirror under `<NEOTOMA_DATA_DIR>/mirror/` and run an initial rebuild.
  - `--path <dir>`: Override mirror root.
  - `--git`: Enable git-backed history (`git init` on the mirror path, one commit per write batch). Requires the optional `simple-git` dependency (installed by default).
  - `--kinds <list>`: Comma-separated kinds to mirror (`entities,relationships,sources,timeline,schemas`, default all).
  - `--gitignore`: After enabling, append the resolved mirror path to the enclosing git repo's `.gitignore` (idempotent). No-op when the mirror path is not inside a repo. Equivalent to running `neotoma mirror gitignore` after `enable`.
  - `--no-gitignore`: Explicit form for `--yes` scripts that want to leave `.gitignore` alone (default).
- `neotoma mirror disable`: Disable mirror write-through. Does not delete existing files.
- `neotoma mirror rebuild`: Regenerate the mirror from SQLite.
  - `--kind <entities|relationships|sources|timeline|schemas|all>` (default `all`).
  - `--entity-type <type>`, `--entity-id <id>`: Scope rebuild to a type or single record.
  - `--clean`: Remove stale mirror files within the targeted scope that this rebuild did not produce.
- `neotoma mirror push [profile]`: Write on-disk mirror edits BACK into Neotoma as corrections — the inverse of `rebuild`. **Opt-in and gated:** only runs for profiles with `allow_disk_writeback: true`, and is a no-op otherwise. Pull-based (explicit invocation, no background watcher): for each mirrored file it 3-way compares the editable fields (last-synced base / on-disk / current canonical) and applies changed fields as `correct()` calls; managed/generated regions (frontmatter, "do not edit" headers) are never written back. When both the file and canonical changed since the base, it surfaces a conflict instead of overwriting.
  - `--check` / `--dry-run`: Show the corrections that would be applied, without writing.
  - `--target <path>`: Restrict the push to a specific mirror file or directory.
  - `--verbose`: Print per-field diffs and per-file outcomes.
  - Example (dry-run): `neotoma mirror push --dry-run` lists files with pending edits and the field-level corrections each would produce.
  - See [`docs/subsystems/markdown_mirror.md`](../subsystems/markdown_mirror.md) for 3-way-diff semantics.
- `neotoma mirror status`: Print current mirror config, file counts per kind, and whether git is enabled.
- `neotoma mirror gitignore`: Idempotently append the resolved mirror path to the enclosing git repo's `.gitignore`, under a `# Neotoma markdown mirror` comment. The helper walks up from the mirror path to find the enclosing `.git` directory; it never prompts for a path and never writes to a repo it did not detect. When the mirror path is not inside a repo, it exits 0 with a "not inside a git repo" message. Use `--json` to get the structured result (`repo_root`, `gitignore_path`, `entry`, `added`, `already_present`).

The mirror is a derived artifact: SQLite is the only source of truth. Mirror files carry a header warning that manual edits are overwritten on the next write — **unless** the profile opts into write-back (`allow_disk_writeback: true`), in which case `neotoma mirror push` (above) is the supported path to flow on-disk edits back as corrections. To edit an entity directly, use `neotoma edit <id>` or the Inspector (see below). The mirror defaults to disabled; activation offers it as an opt-in (see [`install.md`](../../install.md#activation-step-66-offer-markdown-mirror-opt-in)). See `docs/subsystems/markdown_mirror.md` for layout, determinism, and git semantics.

### Skills

- `neotoma skills sync`: Mirror the published skills (`skills/` shipped with the package) into every installed harness's skills directory. This is the same reconciler `neotoma setup` uses for skill installation, run across all harnesses at once.
  - `--scope <user|project>` (default `user`): Mirror into the home-directory harness dirs (`~/.claude/skills`, `~/.cursor/skills`, `~/.codex/skills`, `~/.openclaw/skills`) or into the project's `.<harness>/skills`.
  - `--json`: Emit the machine-readable report (`source`, `source_present`, `scope`, per-harness `results`, `changed`, `has_errors`) instead of the human summary.
  - Targets a harness only when its **base** directory exists (e.g. `~/.cursor`), and creates the `skills` subdirectory if missing — so a harness installed later is picked up on the next sync. Cursor uses `.cursor/skills` (not Cursor's separate built-in `.cursor/skills-cursor` root).
  - Reconciliation: a single whole-directory symlink when the target is absent or already ours; a per-skill symlink fallback that preserves any foreign content when the target holds non-Neotoma skills. Foreign content is never overwritten or deleted.
  - Exit code `1` when the source is missing or any per-skill link fails (errors are surfaced per harness in both pretty and `--json` output); otherwise `0`.

For continuous mirroring, install the `com.neotoma.skills-sync` LaunchAgent with `npm run setup:launchd-skills-sync` (macOS; watches `skills/` and re-runs `neotoma skills sync` on change). See [`npm_scripts.md`](npm_scripts.md#macos-launchagents).

### Edit

- `neotoma edit <id>`: Open the entity snapshot as YAML in `$EDITOR`, diff on save, and submit changed fields as one batch correction (one `correct()` observation per changed field, applied atomically).
  - `--set field=value` (repeatable): Non-interactive edit. No editor invoked. Same batch backend, same concurrency prompt.
  - `--force`: On optimistic-concurrency conflict, overwrite without prompting (non-interactive use).
  - Editor fallback order: `$EDITOR`, then `$VISUAL`, then `vi`.
  - Optimistic concurrency: captures `last_observation_at` on load. If a newer observation exists at save time, the CLI prints conflicting fields and prompts `[r]ebase / [o]verwrite / [a]bort`.
  - On validation failure, the draft file is preserved under `~/.config/neotoma/edit-drafts/<entity_id>-<ts>.yaml` and the path is printed so the user can rerun `neotoma edit <id>`.

The CLI and the Inspector share one `applyBatchCorrection` backend (`src/services/batch_correction.ts`), so both surfaces have identical semantics.

### Memory export

- `neotoma memory-export`: Write a single `MEMORY.md` file with bounded, deterministic contents for agent harnesses that consume file-based memory.
  - `--path <path>` (default `MEMORY.md`): Output path.
  - `--limit-lines <n>` (default 200): Hard line cap. When exceeded, output is truncated with a `<!-- fold: N entities not shown -->` marker. Set to `0` to include every entity with no line cap.
  - `--include-types <list>`: Comma-separated entity types to include. Omit to include all types (minus bookkeeping).
  - `--exclude-types <list>`: Comma-separated entity types to exclude. Applied on top of the default bookkeeping filter.
  - `--include-bookkeeping`: Include chat bookkeeping (`conversation`, `agent_message`). Excluded by default because they are noise in a memory manifest and already live in conversation history.
  - `--max-field-chars <n>` (default 400): Per-field character cap for long string values. Long bodies (posts, notes, transcripts) are truncated with a deterministic `… (<N> chars truncated)` suffix so one long entity cannot consume the entire line budget. Set to `0` to emit full values.
  - `--order <importance|recency>` (default `importance`): Sort strategy.
    - `importance`: type-weighted signal score `typeWeight × log2(observation_count + 2) × recency_decay` (half-life 30 days). Tier-1 types (`task`, `contact`, `event`, `transaction`, `business_opportunity`, `issue`, `user_persona_insight`, `life_tenets`, `architectural_decision`, `agent_decision`, `release`, `feature_unit`) rank above Tier-2 durable artifacts (`note`, `post`, `meeting_transcription`, `email_message`, `location`, `file_asset`, etc.). Bookkeeping types score 0 when included explicitly.
    - `recency`: `last_observation_at desc`, ties broken by `entity_id asc`.
  - `--user-id <id>`: Scope to a specific user. Defaults to the active local dev user when encryption is off.

`MEMORY.md` is regenerated automatically after each mirror batch when `mirror.memory_export.enabled` is set in `~/.config/neotoma/config.json`.

### Storage

- `neotoma storage info`: Show where CLI config and server data are stored (file paths and backend).
  - Local backend (only supported backend): prints `data_dir`, `sqlite_db` (default `data/neotoma.db` in development, `data/neotoma.prod.db` in production), `raw_sources` (e.g. `data/sources`), `event_log` (e.g. `data/logs/events.log`), `logs` (e.g. `data/logs`). Paths are resolved from current directory when run from a Neotoma source checkout, or from `NEOTOMA_PROJECT_ROOT` / `NEOTOMA_DATA_DIR` and other env overrides.
- `neotoma storage set-data-dir <dir>`: Update repo `.env` with `NEOTOMA_DATA_DIR=<dir>`, and optionally copy SQLite DB files (`neotoma.db`, `neotoma.prod.db`, and `-wal`/`-shm` sidecars) from the old data directory.
  - For durable SQLite storage on macOS, prefer a local-only path such as `~/Library/Application Support/neotoma/data` over iCloud-synced `Documents`, `Desktop`, or `iCloud Drive` folders.
  - Interactive mode asks whether to copy DB files.
  - When DB files exist in both old and new directories, conflict handling is:
    - `merge`: back up target DB files, then insert missing rows from old DBs into target DBs.
    - `overwrite`: back up target DB files, then replace target DB files with old DB files.
    - `use-new`: keep target DB files unchanged and only switch `NEOTOMA_DATA_DIR`.
  - Old directory files are always preserved (copy/merge only, never delete old DB files).
  - Options:
    - `--move-db-files` / `--no-move-db-files`
    - `--on-conflict <merge|overwrite|use-new>`
    - `--yes` (skip prompts)
  - `--json` output includes backup paths, copied files, conflict strategy, and merge stats.
- `neotoma storage merge-db`: Merge one SQLite DB file into another.
  - Required:
    - `--source <path>`: Source DB file.
    - `--target <path>`: Target DB file.
  - Options:
    - `--mode <safe|keep-target|keep-source>`:
      - `safe` (default): fail when matching primary keys contain differing row values.
      - `keep-target`: insert missing rows; keep target rows on conflicts (`INSERT OR IGNORE` behavior).
      - `keep-source`: insert/replace source rows into target (`INSERT OR REPLACE` behavior).
    - `--dry-run`: Analyze conflicts and merge impact without writing the target DB.
    - `--no-recompute-snapshots`: Skip post-merge snapshot recomputation.
  - Behavior notes:
    - Default mode is safety-first (`safe`) to avoid silent row loss on conflicts.
    - Post-merge recomputation rebuilds `entity_snapshots` and `relationship_snapshots` when those tables exist.
    - This command merges DB rows only; it does not copy `sources/` files or log directories. Use backup/restore or storage migration workflows when file assets must move with DB content.
- `neotoma storage recover-db`: Check SQLite integrity and optionally write a recovered copy via `sqlite3 .recover`.
  - Default: check only. Exits non-zero when corruption is detected.
  - `--recover`: write a new sibling file such as `neotoma.prod.recovered-<timestamp>.db`.
  - `--output <path>`: explicit recovered DB path.
  - Behavior notes:
    - Requires `sqlite3` on `PATH`.
    - Does not replace the live DB automatically.
    - Stop Neotoma (MCP/API) before running `--recover`.
    - After a successful recover, manually archive the live `.db` / `-wal` / `-shm` and then copy the recovered file into place.
    - If corruption recurs, run `neotoma status --json`; the `data.risks` block flags cloud-synced data directories and prior repair artifacts.

### Status

- `neotoma status` (alias: `neotoma doctor`): Check Neotoma configuration and connectivity. Verifies that the global CLI is on `PATH`, that `NEOTOMA_DATA_DIR` and the SQLite db are usable, whether a local API process is running, which MCP server entries the configured harnesses expose, and whether the data directory is on a high-risk filesystem.
  - The `doctor` name is a deprecated alias retained for backward compatibility; prefer `neotoma status`. The `--json` payload shape is unchanged.
  - `--json`: Emit a structured report instead of the human summary. Designed for agent-led installs (`neotoma setup --output json` consumes it) and for CI/operator scripts.
  - `--tool <claude-code|cursor|codex|openclaw|claude-desktop|windsurf|continue|vscode>`: Override the current-tool hint that `status` ships in the report and that `neotoma setup` reads.

  **`--json` shape (v0.12+):**

  ```jsonc
  {
    "version": "0.12.0",                  // installed neotoma version
    "cwd": "/Users/.../repos/neotoma",
    "global_cli": {
      "node_on_path": true,
      "resolved_via": "global-bin" | "fallback" | "missing",
      "which_neotoma": "/usr/local/bin/neotoma" | null,
      "global_bin": "/usr/local/bin",
      "global_package_dir": "/usr/local/lib/node_modules/neotoma",
      "npm_global_root": "/usr/local/lib/node_modules",
      "path_fix_hint": null | "Add /usr/local/bin to your PATH"
    },
    "data": {
      "config_dir": "/Users/.../.neotoma",
      "data_dir": "/Users/.../Library/Application Support/neotoma/data",
      "db_exists": true,
      "initialized": true,
      "risks": [
        // 0..N entries — see "data.risks codes" below
      ],
      "suggested_safe_data_dir":
        "/Users/.../Library/Application Support/neotoma/data" | null
    },
    "api": {
      "running": true,
      "env": "dev" | "prod" | null,
      "port": 3080,
      "pid": 12345,
      "base_url": "http://127.0.0.1:3080"
    },
    "mcp_servers_detected": {
      "cursor": { "path": "~/.cursor/mcp.json", "has_neotoma": true, "has_neotoma_dev": false }
      // …one entry per harness probed (cursor, claude_code, codex, claude_desktop, openclaw)
    },
    "cli_instructions": {
      "project": { "cursor": true, "claude": false, "codex": false },
      "user":    { "cursor": true, "claude": false, "codex": false }
    },
    "permission_files": { /* per-harness file existence + allow-list match */ },
    "current_tool_hint": "cursor" | null,
    "hooks": { /* HooksReport — installed hooks by harness */ },
    "mirror": { /* MirrorReport — mirror clone state */ },
    "suggested_next_step":
      "install" | "init" | "configure-mcp" | "configure-cli-instructions" |
      "configure-permissions" | "activate" | "offer-hooks" | "offer-mirror" | "ready"
  }
  ```

  **`data.risks[]` entry shape:**

  ```jsonc
  {
    "code": "icloud_drive"
          | "macos_synced_desktop_or_documents"
          | "prior_sqlite_repair_artifacts",
    "severity": "warn",
    "message": "<human-readable description>",
    "suggested_action": "<single concrete next command>"
  }
  ```

  The risk detector (`detectDataDirRisks` in `src/cli/doctor.ts`) covers three classes:
  - **`icloud_drive`** — `NEOTOMA_DATA_DIR` resolves inside `~/Library/Mobile Documents/`. iCloud Drive can re-upload `neotoma.db`, `neotoma.db-wal`, and `neotoma.db-shm` while Neotoma is writing, which is the corruption shape behind the SQLite `recover-db` flow. `suggested_action` points at the suggested local-only path returned by `suggested_safe_data_dir`.
  - **`macos_synced_desktop_or_documents`** — data dir sits under `~/Documents` or `~/Desktop`, both of which macOS enables for iCloud Drive sync by default. `suggested_action` is the matching `neotoma storage set-data-dir "<safe path>" --move-db-files` invocation.
  - **`prior_sqlite_repair_artifacts`** — the data directory contains marker files (`repair_backups/`, `repair_swaps/`, `recover-errors.log`, or `db_corrupt_before_swap_*`) left behind by a previous `neotoma storage recover-db` run. A recurrence is a signal to move the data dir to local-only storage.

  **`suggested_safe_data_dir`** is computed by `suggestSafeDataDir(os.homedir())`. On macOS it is `~/Library/Application Support/neotoma/data`; on other platforms it returns `null` and the report only contains `risks` without a generated suggestion. The field is `null` whenever `data.risks` is empty.

  **Migration command**: when `data.risks` is non-empty, an operator (or `neotoma setup` acting on their behalf) can move the data dir with:

  ```bash
  neotoma storage set-data-dir "<suggested_safe_data_dir>" --move-db-files
  ```

  Cross-references: [`docs/foundation/local_install.md`](../foundation/local_install.md) §§ data-dir hygiene, [`docs/security/threat_model.md`](../security/threat_model.md) `## Operator hardening knobs`, and the `recover:db` script in `### Database and schema` above.

### Snapshots

Fleet-general write-integrity tooling built on the canonical snapshot layer. `snapshots check` / `snapshots request` operate on the runtime snapshot tables; `snapshots export`, `snapshots diff`, and `snapshots parsers` power the fleet-neutral drift workflow described in `docs/releases/in_progress/v0.6.0/` (item 3: snapshot export + drift comparison).

- `neotoma snapshots check`: Check for stale entity snapshots.
  - `--auto-fix`: Also recompute stale snapshots in place.
- `neotoma snapshots request`: Request snapshot recomputation for stale snapshots.
  - `--dry-run`: Check only; do not recompute.
- `neotoma snapshots export`: Export entity snapshots as fleet-neutral JSON (schema_version `0.1.0`) with per-field provenance, an `observation_source` histogram, and an `attribution_fingerprint` roll-up per entity.
  - `--entity-types <csv>`: Restrict to comma-separated entity types (e.g. `agent_task,agent_attempt`).
  - `--agent-sub <sub>`: Restrict to a single AAuth `agent_sub`.
  - `--attribution-tier <tier>`: Restrict to one tier — `hardware | software | unverified_client | anonymous`.
  - `--observation-source <kind>`: Restrict to one write kind — `sensor | llm_summary | workflow_state | human | import | sync`.
  - `--since <iso>`: ISO-8601 lower bound on `last_observation_at`.
  - `--limit <n>`: Cap on returned entities (default: 500).
  - `--out <path>`: Write the export to this file instead of stdout.
  - `--user-id <id>`: Override user scope (flag > `NEOTOMA_USER_ID` > authenticated user).
  - Output shape: `{ schema_version, exported_at, filter, total_entities, entities[] }`.
- `neotoma snapshots diff`: Compare a Neotoma export against an external-state snapshot via a pluggable `ExternalParser`. Defaults to the identity `json` parser; fleet-specific parsers register via `registerExternalParser` in `src/services/drift_comparison.ts`.
  - `--neotoma <path>` (required): Path to a `snapshots export` JSON file.
  - `--external <path>` (required): Path to the external-state snapshot file.
  - `--parser <name>`: External parser name (default: `json`; list via `snapshots parsers`).
  - `--out <path>`: Write the drift report to this file instead of stdout.
  - Report shape: `{ summary, missing_in_neotoma[], missing_in_external[], field_diffs[], provenance_gaps[] }`. `provenance_gaps` flags entities with unclassified `observation_source` or anonymous / unverified_client attribution even when field values agree.
- `neotoma snapshots parsers`: List registered external parsers available to `snapshots diff`.

Fleet round-trip example (AIBTC Lumen, LangGraph, custom adapters all follow the same shape):

```bash
neotoma snapshots export --entity-types agent_task,agent_attempt --out ./neotoma.json
# produce a NormalizedExternalSnapshot from whatever your fleet keeps on disk
neotoma snapshots diff --neotoma ./neotoma.json --external ./fleet.json --parser json
```

### Database maintenance

- `neotoma db migrate-encryption [--direction encrypt|decrypt] [--dry-run]`: Bulk-encrypt or bulk-decrypt all sensitive columns in the local SQLite database. Operates on the closed database file directly (server must not be running). Safe to re-run — idempotent.
  - `--direction encrypt` (default): Encrypt all plaintext values in covered columns across `observations`, `entity_snapshots`, `relationship_snapshots`, `raw_fragments`, `schema_recommendations`, and `auto_enhancement_queue`.
  - `--direction decrypt`: Reverse the encryption on all covered columns.
  - `--dry-run`: Report how many rows would be processed without writing any changes.
  - Requires `NEOTOMA_KEY_FILE_PATH` or `NEOTOMA_MNEMONIC` to be set.

- `neotoma db repair-schema-lag [--dry-run] [--types <entity_types>] [--rollback <run_id>]`: Audit and repair `raw_fragments` rows that were misrouted due to the schema-projection-lag bug (issue #142). Rows in `raw_fragments` whose `fragment_key` now matches a declared field in the active schema for their entity type are promoted to observations, and affected entity snapshots are recomputed. Safe to re-run — uses deterministic observation IDs.
  - `--dry-run`: Report affected entity types and fragment counts without writing any rows.
  - `--types <entity_types>`: Comma-separated list of entity types to limit the repair scope (default: all).
  - `--rollback <run_id>`: Roll back a prior repair run by its `run_id`. Deletes the observations inserted by that run and recomputes affected snapshots.
  - Every observation inserted by `repair-schema-lag` carries a `_migration_run_id` field in its `fields` JSON, making runs fully rollback-safe.
  - After a repair, the command prints the `run_id` with a copy-paste rollback hint.

### Backup and restore

- `neotoma backup create`: Create a backup of the local database, sources, and logs.
  - `--output <dir>`: Output directory (default: `./backups`).
  - `--tar`: After the directory backup is verified, also create `<backup-folder-name>.tar.gz` in the same parent directory as the backup folder (GNU/BSD `tar` on `PATH` required). The timestamped directory is kept; the archive is an additional artifact for transport.
  - Creates a timestamped subdirectory with `neotoma.db`, WAL file, `sources/`, `logs/` (includes `events.log`), and a `manifest.json` with checksums.
  - **Human output** prints **backup size** first (total bytes on disk for the backup directory, file count, and raw byte count; with `--tar`, the same line also includes the `.tar.gz` size). Then **Backed up from**, **Contents**, **Sizes** (per-component breakdown; the directory total is labeled **total (directory)**), **db_checksum** when recorded. With `--tar`, also an **Archive** line for the `.tar.gz` path and size.
  - **JSON output** (`--json`) includes **`backup_size`**: `{ bytes, files, human }` for the backup directory walk (same totals as `sizes.total_backup_bytes` / `total_backup_files`, plus a single `human` summary string). With `--tar`, `backup_size` also has `archive_bytes` and `human` includes the archive. Other fields: `manifest_path`, `backed_up_from`, `sizes`, and with `--tar` `archive_path`, `archive_bytes`, `sizes.archive_bytes`.
  - Exits non-zero if the database copy is missing or under 1 KiB after write, or if `--tar` was set and creating the archive failed.
  - If encryption is enabled, data in the backup remains encrypted. Preserve the key file or mnemonic for restore.
- `neotoma backup verify <dir>`: Verify a backup directory (manifest, DB size, optional SHA-256 vs manifest). Exits non-zero if invalid. **Human** and **`--json`** both include **`backup_size`** (`bytes`, `files`, `human`) for the full directory tree on disk.
- `neotoma backup restore`: Restore a backup into the data directory.
  - `--from <dir>`: Backup directory to restore from (required).
  - `--target <dir>`: Target data directory (default: `NEOTOMA_DATA_DIR` or `./data`).

### Logs

- `neotoma logs tail`: Read persistent log files.
  - `--decrypt`: Decrypt encrypted log lines using `NEOTOMA_KEY_FILE_PATH` or `NEOTOMA_MNEMONIC`.
  - `--lines <n>`: Number of lines to show (default: 50).
  - `--file <path>`: Specific log file (default: latest in env-specific `data/logs`; prod uses `data/logs_prod`).

### Developer scripts

- `neotoma dev list`: List available npm scripts from `package.json`.
- `neotoma dev <script>`: Run a script from `package.json` (equivalent to `npm run <script>`).
- `neotoma dev run <script>`: Run a script by name (same as `neotoma dev <script>`).
- Use `-- <args>` to pass through extra arguments to the npm script.
- The source checkout is found by: explicit CLI inputs (where supported), then `NEOTOMA_REPO_ROOT`, then walking up from the current directory, then saved config `project_root` (legacy `repo_root` is still read).

### Debugging and testing (e.g. with an agent)

- **When debugging CLI-related issues, always check the CLI log first.** In dev the default path is `~/.config/neotoma/cli.log`. If the user passed `--log-file`, check that path. For session server output, check `<repo>/data/logs/session.log` (dev) or `session.prod.log` (prod). The same file is used whether the API was started by the CLI or by the MCP server (both append); look for "started by MCP" in the log to see who started a given run. For background API, check `neotoma api logs` or `~/.config/neotoma/logs/api.log`. See **Where to look for what (logs)** in `docs/operations/troubleshooting.md` for a per-component log map.
- **Dev** (default): CLI appends stdout and stderr to `~/.config/neotoma/cli.log`. Use `--no-log-file` to disable.
- **Prod** (`NEOTOMA_ENV=production`): No log file by default; use `--log-file <path>` to enable.
- `--log-file <path>`: Append CLI output to this path (overrides env default).
- `--no-log-file`: Do not write to the log file (dev only; prod has no default log file).
- `--debug`: Emit detailed initialization logs to stderr when starting a session.

### OpenAPI request

- `neotoma request --operation <id>`:
  - `--params <json>`: JSON object with `{ path, query, body }`.
  - `--body <json>`: JSON body override.
  - `--query <json>`: JSON query override.
  - `--path <json>`: JSON path override.
  - `--skip-auth`: Skip auth token for public endpoints.

## Configuration and storage paths

The CLI stores configuration in:

- `~/.config/neotoma/config.json`

To see where server data is stored (SQLite path, raw sources dir, etc.), run:

- `neotoma storage info`

Fields:

```
{
  "base_url": "http://localhost:3080",
  "access_token": "redacted",
  "token_type": "bearer",
  "expires_at": "2026-02-01T12:00:00Z",
  "connection_id": "redacted"
}
```

## Deterministic output

The CLI sorts object keys before outputting JSON. This keeps output stable between runs.

## Diagrams

```mermaid
flowchart TD
    cli[CLI] -->|"Read config"| config[ConfigFile]
    cli -->|"Call API"| api[HttpApi]
    api -->|"JSON response"| cli
```

## Examples

### Request by OpenAPI operation ID

```
neotoma request --operation listEntities --params '{"query":{"limit":5}}' --pretty
```

### Store entities from a file

```
neotoma store --file ./fixtures/tasks.json
```

### Stream record changes alongside MCP actions

```
neotoma watch --tail --json   # NDJSON, only new changes
neotoma watch --tail --human  # Plain one-line-per-change, only new
neotoma watch --tail          # Human-readable, only new changes
neotoma watch --human         # Plain one-line-per-change, no technical formatting
neotoma watch                 # Human-readable, includes existing records on startup
```

## Testing requirements

1. Verify each command prints deterministic JSON output.
2. Validate auth login flow against local server.

## Agent Instructions

### When to Load This Document

Load this document when updating CLI commands, options, or configuration behavior.

### Required Co-Loaded Documents

- `docs/NEOTOMA_MANIFEST.md`
- `docs/conventions/documentation_standards.md`
- `docs/api/rest_api.md`

### Constraints Agents Must Enforce

1. Commands and flags MUST match the CLI implementation.
2. Config path and fields MUST be accurate.
3. Examples MUST use synthetic data.

### Forbidden Patterns

- Listing commands that do not exist
- Using real tokens or private values
- Omitting required sections

### Validation Checklist

- [ ] Purpose, Scope, Invariants, Definitions present
- [ ] Commands and options match CLI implementation
- [ ] Config path and fields are accurate
- [ ] Agent Instructions included