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.	`—`

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 for agent-native transport, REST API reference for HTTP endpoints, and troubleshooting for common failure modes.