CLI Reference (Markdown)

<!--
  Full-page Markdown export (rendered HTML → GFM).
  Source: https://neotoma.io/cli
  Generated: 2026-04-26T19:09:38.336Z
-->
# Command-line interface (CLI)

The Neotoma CLI provides full access to every operation available in the MCP and REST API, plus administration commands for server lifecycle, storage, backups, and configuration. Run `neotoma` with no arguments for an interactive session (`neotoma>` prompt), or invoke commands directly (e.g. `neotoma entities list`).

## Installation

\# Install globally
npm install -g neotoma

# Initialize data directory and database
neotoma init

# Start the API server (development)
neotoma api start --env dev --background

From a source checkout: `npm run setup:cli` builds and links the global `neotoma` command. Use `npm run watch:build` to keep the global CLI in sync during development.

◆

## Environments

Target a specific environment with `neotoma dev` (port 3080) or `neotoma prod` (port 3180), or pass `--env dev` / `--env prod`. Server lifecycle commands (`api start`, `api stop`, `api logs`) always require `--env`.

◆

## Typical workflow

\# Store entities
neotoma store --json='\[{"entity\_type":"task","title":"Review API rollout","status":"open"}\]'

# List entities by type
neotoma entities list --type task --limit 10

# Search by identifier
neotoma entities search "Ana Rivera" --type contact

# Inspect provenance
neotoma observations list --entity-id <entity\_id>

# Upload a file with AI interpretation
neotoma upload ./invoice.pdf

# Upload locally (no API server needed)
neotoma upload --local ./invoice.pdf

# Stream changes in real time
neotoma watch --tail --human

◆

## Global options

-   `--offline`: force in-process local transport (no API required)
-   `--api-only`: fail if API server is unavailable
-   `--base-url <url>`: target a specific API instance
-   `--env dev|prod`: environment selector (required for server commands)
-   `--json`: machine-readable JSON output
-   `--pretty`: formatted JSON output
-   `--tunnel`: start HTTPS tunnel (ngrok/cloudflared) with server start
-   `--debug`: emit detailed initialization logs to stderr

◆

## Offline support

Data commands (`entities`, `relationships`, `sources`, `observations`, `timeline`, `store`, `schemas`, `stats`, `corrections`, `snapshots`) are offline-first and use in-process local transport by default - no API server required. Server lifecycle commands (`api start|stop|status|logs`) manage the API process and are unaffected.

| Command | Description | Flags |
| --- | --- | --- |
| auth login | Get or authenticate the current user. | — |
| auth status | Get or authenticate the current user. | — |
| auth whoami | Get or authenticate the current user. | — |
| request (OAuth ops) | Get or authenticate the current user. | — |
| entities list | Query entities with filters. | \--type, --limit, --offset, --search |
| entities get | Get an entity by ID. | <entity\_id> |
| request --operation getEntitySnapshot | Get an entity snapshot with provenance. | \--entity-id, --at? |
| request (getEntityObservations | List observations for an entity or get field provenance. | \--entity-id (or body) |
| listObservationsForEntity | List observations for an entity or get field provenance. | — |
| getFieldProvenance) | List observations for an entity or get field provenance. | — |
| relationships list | List relationships for an entity. | \--entity-id |
| entities search | Search for an entity by identifier or semantic. | \--query, --type |
| entities related | Retrieve related entities or the graph neighborhood. | \--entity-id |
| entities neighborhood | Retrieve related entities or the graph neighborhood. | \--entity-id |
| request --operation mergeEntities | Merge two entities. | \--source-id, --target-id |
| entities delete | Delete or restore an entity. | <entity\_id> |
| entities restore | Delete or restore an entity. | <entity\_id> |
| sources list | List sources or get a source by ID. | — |
| request --operation getSourceById | List sources or get a source by ID. | — |
| request (listObservations) | List, query, or create observations. | — |
| observations list | List, query, or create observations. | — |
| relationships list | List relationships, get one by ID, or get a snapshot. | — |
| request (getRelationshipById) | List relationships, get one by ID, or get a snapshot. | — |
| relationships get-snapshot | List relationships, get one by ID, or get a snapshot. | — |
| request (createRelationship) | Create, delete, or restore a relationship. | \--source-id, --target-id, --type |
| relationships delete | Create, delete, or restore a relationship. | \--relationship-key |
| relationships restore | Create, delete, or restore a relationship. | \--relationship-key |
| timeline list | List timeline events or get one by ID. | — |
| timeline get | List timeline events or get one by ID. | <id> |
| schemas list | List schema types or get a schema by entity type. | — |
| schemas get | List schema types or get a schema by entity type. | <entity\_type> |
| schemas analyze-candidates | Analyze schema candidates, get recommendations, update incrementally, or register a schema. | \--entity-type |
| schemas recommendations | Analyze schema candidates, get recommendations, update incrementally, or register a schema. | \--entity-type |
| schemas update-incremental | Analyze schema candidates, get recommendations, update incrementally, or register a schema. | \--entity-type |
| schemas register | Analyze schema candidates, get recommendations, update incrementally, or register a schema. | — |
| store | Store structured entities. | \--json |
| upload <path> | Store an unstructured file. | <path>, --no-interpret?, --mime-type? |
| corrections create | Submit a correction or reinterpret a source. | — |
| interpretations reinterpret | Submit a correction or reinterpret a source. | <source\_id> |
| request --operation listInterpretations | List interpretations. | — |
| stats | Get server stats, server info, or run health check snapshots. | — |
| snapshots check | Get server stats, server info, or run health check snapshots. | — |
| request --operation getFileUrl | Get a signed file URL (internal). | — |
| analyze <filePath> | Parse a file into agent-readable text without storing. | <filePath> |
| — | Check for a newer npm package version. | — |
| api status | Health check. | \--env dev|prod |
| — | OpenAPI specification. | — |
| init | Initialize Neotoma (data dirs, DB, encryption, .env). | \--data-dir, --force, --skip-db, --skip-env |
| reset | Reset local Neotoma state to clean slate. | \--yes |
| api start | Start, stop, or manage the API server. | \--env, --background, --tunnel, --tunnel-provider |
| api stop | Start, stop, or manage the API server. | \--env |
| api status | Start, stop, or manage the API server. | \--env |
| api logs | Start, stop, or manage the API server. | \--env |
| api processes | Start, stop, or manage the API server. | — |
| mcp config | Configure or check MCP server entries in IDE configs. | \--no-check |
| mcp check | Configure or check MCP server entries in IDE configs. | \--user-level |
| cli-instructions config | Check or install CLI agent instructions for IDEs. | — |
| cli-instructions check | Check or install CLI agent instructions for IDEs. | \--user-level, --yes |
| watch | Stream record changes in real time. | \--interval, --json, --human, --tail |
| storage info | Show or change storage paths and merge databases. | — |
| storage set-data-dir | Show or change storage paths and merge databases. | \--move-db-files, --on-conflict, --yes |
| storage merge-db | Show or change storage paths and merge databases. | \--source, --target, --mode, --dry-run |
| backup create | Create or restore a backup. | \--output |
| backup restore | Create or restore a backup. | \--from, --target |
| logs tail | Read persistent log files. | \--decrypt, --lines, --file |
| session | Interactive session with persistent prompt. | \--servers |
| dev list | Run npm scripts from the repo. | — |
| dev <script> | Run npm scripts from the repo. | \-- <args> |
| interpretations interpret-uninterpreted | Interpret uninterpreted sources (backfill). | \--limit, --dry-run, --interpretation-config |
| auth logout | Log out or get MCP auth token. | — |
| auth mcp-token | Log out or get MCP auth token. | — |

Scroll right

◆

## Authentication

Local CLI commands run without login in development. For production or MCP OAuth:

-   `neotoma auth login` - OAuth PKCE flow for MCP Connect
-   `neotoma auth status` - show auth mode and user details
-   `neotoma auth mcp-token` - print key-derived MCP token (when encryption is enabled)
-   `neotoma auth logout` - clear stored OAuth credentials

◆

## Storage and configuration

CLI config is stored at `~/.config/neotoma/config.json`. Run `neotoma storage info` to see data directory, database path, sources directory, and log paths. Use `neotoma storage set-data-dir` to relocate the data directory with optional DB migration. Use `neotoma storage merge-db` to merge SQLite databases (safe mode by default).

◆

## Backups

`neotoma backup create` creates a timestamped backup of the database, sources, and logs with a `manifest.json` containing checksums. `neotoma backup restore --from <dir>` restores a backup into the data directory. Encrypted data stays encrypted; preserve the key file or mnemonic.

See [MCP reference](/mcp) for agent-native transport, [REST API reference](/api) for HTTP endpoints, and [troubleshooting](/troubleshooting) for common failure modes.