Skip to main content

CLI

RetriCo includes a command-line interface for building knowledge graphs, querying them, managing graph data, and more — without writing any Python code.

Installation​

The CLI is available as retrico after installing the package:

pip install retrico
retrico --version

Commands Overview​

CommandDescription
retrico connectSave database connection to .retrico.yaml
retrico buildBuild a knowledge graph from text
retrico queryQuery the knowledge graph
retrico ingestIngest structured JSON data
retrico communityDetect communities in the graph
retrico modelTrain KG embeddings
retrico initGenerate a pipeline config YAML interactively
retrico graphDirect graph database operations (CRUD)
retrico shellInteractive query REPL

Three Modes of Operation​

Most commands (build, query, community, model) support three modes:

  1. Argument mode — pass all options as flags (scriptable, CI-friendly)
  2. Config mode — pass a YAML pipeline config with --config
  3. Interactive mode — a step-by-step wizard (use --interactive to force)

If you provide enough flags, the CLI runs in argument mode. If not, it falls back to the interactive wizard automatically.

connect​

Save a database connection to .retrico.yaml in the current directory. All subsequent commands will use this connection by default.

Interactive setup​

retrico connect

The wizard prompts for store type and connection details.

Flag-based setup​

# FalkorDB Lite (default, zero-config)
retrico connect --store-type falkordb_lite --falkordb-lite-db-path retrico.db

# Neo4j
retrico connect --store-type neo4j --neo4j-uri bolt://localhost:7687 \
  --neo4j-user neo4j --neo4j-password password

# FalkorDB (server)
retrico connect --store-type falkordb --falkordb-host localhost --falkordb-port 6379

# Memgraph
retrico connect --store-type memgraph --memgraph-uri bolt://localhost:7687

Managing the saved connection​

# Show current connection (passwords masked)
retrico connect --show

# Clear saved connection
retrico connect --clear

The .retrico.yaml file looks like:

store:
  store_type: neo4j
  neo4j_uri: bolt://localhost:7687
  neo4j_user: neo4j
  neo4j_password: password
tip

Any command can override the saved connection with explicit flags. CLI flags always take precedence over .retrico.yaml.

build​

Build a knowledge graph from text. This is the CLI equivalent of retrico.build_graph().

From a YAML config​

retrico build --config build_config.yaml --text "Einstein was born in Ulm."
retrico build --config build_config.yaml --file paper.txt --file notes.txt

With flags​

retrico build \
  --text "Albert Einstein was born in Ulm, Germany." \
  --text "Marie Curie worked at the University of Paris." \
  --entity-labels "person,organization,location" \
  --relation-labels "born in,works at" \
  --verbose

From files​

retrico build \
  --file document.txt \
  --file article.txt \
  --entity-labels "person,organization,location" \
  --relation-labels "born in,works at"

LLM-based extraction​

retrico build \
  --text "Einstein developed relativity at the Swiss Patent Office." \
  --entity-labels "person,concept,organization" \
  --relation-labels "developed,works at" \
  --method llm \
  --api-key sk-... \
  --llm-model gpt-4o-mini

The API key can also be set via the LLM_API_KEY environment variable.

Saving the pipeline config​

retrico build \
  --text "..." \
  --entity-labels "person,location" \
  --save-config my_pipeline.yaml

This runs the pipeline and saves its configuration for reuse with --config.

Interactive wizard​

retrico build --interactive

The wizard walks through each step: input source, database connection, chunking method, NER method, labels, embeddings, and config saving.

All options​

OptionDescription
--config FILEYAML pipeline config file
--text TEXTInput text (repeatable)
--file FILEInput text file (repeatable)
--entity-labelsComma-separated entity labels
--relation-labelsComma-separated relation labels
--methodNER/relex method: gliner or llm
--chunk-methodChunking: sentence, paragraph, or fixed
--ner-modelNER model name
--relex-modelRelex model name
--api-keyLLM API key (or LLM_API_KEY env var)
--llm-modelLLM model name
--json-outputSave extracted data as JSON
--embed-chunksGenerate chunk embeddings
--embed-entitiesGenerate entity embeddings
--verboseVerbose output
--interactiveForce interactive wizard
--save-config FILESave pipeline config to YAML
--store-typeGraph store backend
--neo4j-*Neo4j connection options
--falkordb-*FalkorDB connection options
--memgraph-*Memgraph connection options

query​

Query the knowledge graph. CLI equivalent of retrico.query_graph().

With flags​

retrico query "Where was Einstein born?" \
  --entity-labels "person,location" \
  --api-key sk-... \
  --llm-model gpt-4o-mini

With a retrieval strategy​

# Entity lookup + k-hop subgraph (default)
retrico query "Where was Einstein born?" \
  --entity-labels "person,location" \
  --strategy entity --max-hops 2

# Path-based retrieval
retrico query "How are Einstein and Curie related?" \
  --entity-labels "person" \
  --strategy path

# Community-based retrieval
retrico query "What research groups exist?" \
  --entity-labels "person,organization" \
  --strategy community

# Multiple strategies (comma-separated)
retrico query "Tell me about Einstein" \
  --entity-labels "person,location" \
  --strategy entity,path,community

Available strategies: entity, community, path, chunk_embedding, entity_embedding, tool, keyword.

From a YAML config​

retrico query "Where was Einstein born?" --config query_config.yaml

Interactive wizard​

retrico query --interactive

All options​

OptionDescription
QUERY_TEXTThe query (positional argument)
--config FILEYAML pipeline config
--entity-labelsComma-separated entity labels
--strategyRetrieval strategy (comma-separated for multi)
--methodNER method for query parsing: gliner or llm
--api-keyLLM API key
--llm-modelLLM model name
--max-hopsSubgraph expansion depth
--verboseVerbose output
--interactiveForce interactive wizard

Output​

The query command displays:

  • Answer — LLM-generated answer (if an API key is provided)
  • Entities — retrieved entities with types and IDs
  • Relations — discovered relationships
  • Source chunks — relevant text passages from the original documents

ingest​

Ingest structured JSON data into the graph. The JSON file must contain a list of objects with entities (required), and optionally relations, text, and metadata.

retrico ingest data.json
retrico ingest data.json --json-output backup.json --verbose

Expected JSON format​

[
  {
    "entities": [
      {"text": "Einstein", "label": "person", "properties": {"birth_year": 1879}},
      {"text": "Ulm", "label": "location"}
    ],
    "relations": [
      {"head": "Einstein", "tail": "Ulm", "type": "born_in"}
    ],
    "text": "Einstein was born in Ulm.",
    "metadata": {"source": "wikipedia"}
  }
]

This is the same format produced by --json-output on the build command, so you can extract data once and re-ingest it into different databases.

Options​

OptionDescription
FILEJSON file to ingest (positional, required)
--json-outputSave data as JSON
--verboseVerbose output

community​

Detect communities in the knowledge graph using Louvain or Leiden algorithms.

With flags​

retrico community --method louvain --levels 2 --resolution 1.0

With LLM summarization​

retrico community --method leiden --api-key sk-... --llm-model gpt-4o-mini

From a YAML config​

retrico community --config community_config.yaml

Interactive wizard​

retrico community --interactive

Options​

OptionDescription
--config FILEYAML pipeline config
--methodlouvain or leiden
--levelsHierarchical levels
--resolutionResolution parameter
--api-keyLLM API key for community summarization
--llm-modelLLM model name
--verboseVerbose output
--interactiveForce interactive wizard

model​

Train knowledge graph embeddings using PyKEEN models (RotatE, TransE, ComplEx).

With flags​

retrico model --kg-model RotatE --embedding-dim 128 --epochs 100 --model-path kg_model

Interactive wizard​

retrico model --interactive

Options​

OptionDescription
--config FILEYAML pipeline config
--kg-modelPyKEEN model: RotatE, TransE, or ComplEx
--embedding-dimEmbedding dimension
--epochsTraining epochs
--batch-sizeBatch size
--lrLearning rate
--devicecpu or cuda
--model-pathPath to save the trained model
--verboseVerbose output
--interactiveForce interactive wizard

init​

Generate a pipeline YAML config file through an interactive wizard. Useful for creating reusable configs without running a pipeline.

retrico init build       # Build pipeline config
retrico init query       # Query pipeline config
retrico init community   # Community detection config
retrico init model       # KG embedding config

If no pipeline type is provided, the wizard prompts for it.

The wizard walks through each component step by step and writes the final config to a YAML file.

graph​

Direct graph database operations. The graph command is a group of subcommands for CRUD operations on the knowledge graph.

List entities​

retrico graph entities
retrico graph entities --type person --limit 20

Show relations​

retrico graph relations "Einstein"
retrico graph relations <entity-id>

Looks up by label first, then by ID.

Full-text search​

retrico graph search "theory of relativity" --top-k 5

Add an entity​

retrico graph add-entity "Albert Einstein" --type person
retrico graph add-entity "MIT" --type organization --properties '{"founded": 1861}'

Add a relation​

retrico graph add-relation "Einstein" "Ulm" "BORN_IN"

Update an entity​

retrico graph update <entity-id> --label "A. Einstein"
retrico graph update <entity-id> --properties '{"field": "physics"}'

Delete entities or relations​

retrico graph delete --entity <entity-id>
retrico graph delete --relation <relation-id>

Merge entities​

Merge a source entity into a target entity (moves all relations):

retrico graph merge <source-id> <target-id>

Graph statistics​

retrico graph stats

Displays total entity count and breakdown by type.

Run raw Cypher​

retrico graph cypher "MATCH (n:Entity) RETURN n.label, n.entity_type LIMIT 10"

Clear all data​

retrico graph clear
retrico graph clear --yes  # skip confirmation
danger

This permanently deletes all data from the graph.

shell​

Interactive query REPL. Type natural-language queries and get answers without restarting the CLI.

retrico shell --entity-labels "person,location" --api-key sk-...

Shell commands​

CommandDescription
:entities [type]List entities, optionally filtered by type
:relations ENTITYShow relations for an entity
:search TEXTFull-text search chunks
:cypher QUERYRun raw Cypher query
:labels person,org,...Set default entity labels
:helpShow available commands
:quitExit the shell

Anything that isn't a :command is treated as a query_graph() call using the configured entity labels and LLM settings.

Example session​

$ retrico shell --entity-labels "person,location" --api-key sk-...
retrico interactive shell
Type a query or :help for commands. :quit to exit.

retrico> Where was Einstein born?

Answer:
Albert Einstein was born in Ulm, Germany.

Entities (2):
  - albert einstein [person] (id: a1b2c3d4...)
  - ulm [location] (id: e5f6g7h8...)

Relations (1):
  - albert einstein --[BORN_IN]--> ulm

retrico> :entities person
id        label              entity_type
--------  -----------------  -----------
a1b2c3d4  albert einstein    person
f9g0h1i2  marie curie        person

retrico> :relations "marie curie"
...

retrico> :quit

Environment Variables​

VariableDescription
LLM_API_KEYDefault LLM API key (used by --api-key options)

Common Workflows​

Quick local graph (no server needed)​

retrico connect --store-type falkordb_lite
retrico build --file paper.txt --entity-labels "person,org,location" --relation-labels "works at,born in"
retrico query "Where was Einstein born?" --entity-labels "person,location"

Full pipeline with Neo4j​

retrico connect --store-type neo4j --neo4j-uri bolt://localhost:7687 --neo4j-password secret
retrico build --file corpus.txt --entity-labels "person,org,concept" \
  --relation-labels "works at,studies,developed" --embed-chunks --embed-entities
retrico community --method leiden --levels 2
retrico query "What did Einstein develop?" --entity-labels "person,concept" \
  --strategy entity,community --api-key sk-...

Config-driven pipeline​

retrico init build                          # generate build_config.yaml
retrico build --config build_config.yaml --file data.txt
retrico init query                          # generate query_config.yaml
retrico query "my question" --config query_config.yaml

Extract and re-ingest​

# Extract to JSON (also writes to DB)
retrico build --file paper.txt --entity-labels "person,location" --json-output extracted.json

# Re-ingest into a different database
retrico connect --store-type neo4j --neo4j-uri bolt://production:7687
retrico ingest extracted.json