Command-line interface (CLI)

Use the CLI when MCP is not available. Run neotoma with no arguments for an interactive REPL (neotoma> prompt).

Data commands (store, entities, relationships, etc.) are offline-first and run via in-process local transport by default. Use --api-only to require the API, or --offline to force local explicitly.

Typical deterministic workflow

# Initialize
neotoma init

# Store one task
neotoma store --json='[{"entity_type":"task","title":"Review API rollout","status":"open"}]'

# Retrieve tasks
neotoma entities list --type task --limit 10

# Inspect provenance for one entity
neotoma observations list --entity-id <entity_id>

Transport flags

--offline: force in-process local transport
--api-only: fail if API server is unavailable
--base-url: target a specific API instance
--env dev|prod: required for server lifecycle commands

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

See MCP reference for agent-native transport and troubleshooting for common failure modes.