CLI Reference

The cognee-cli command-line binary: subcommands, flags, config, retries, and logging.

The command-line binary, built from the cognee-cli crate. It drives the full pipeline and is also the on-device (Android) runner. Run cognee-cli <command> --help for the authoritative flag list; the clap definitions are in crates/cli/src/cli.rs.

cargo build --release          # produces target/release/cognee-cli

Subcommands

The memory API verbs (remember / recall / improve / forget) are the primary surface; the add / cognify / memify / search commands below them are the lower-level pipeline they compose. All of these are always built (not feature-gated).

Command	Purpose	Notable flags	Feature gate
remember <data…>	Store memory: add + cognify + (by default) improve. <data…> is inline text and/or file paths	-d/--dataset-name (main_dataset), --session-id, --no-improve (default OFF — improve runs by default), --tenant-id	—
recall <query>	Query memory with auto-routing (session-aware + graph-backed)	-t/--query-type (optional — omit to auto-route), -d/--datasets (repeatable), -k/--top-k (10), --session-id, -f/--output-format (pretty/json/simple, default pretty)	—
improve	Enrich memory / bridge sessions (feedback + enrichment stages)	-d/--dataset-name (main_dataset), --session-id (repeatable), --node-name (repeatable), --feedback-alpha (0.1), --tenant-id	—
forget	Remove memory (a dataset, a single data item, or everything)	-d/--dataset-name | --data-id (UUID; requires --dataset-name; conflicts with --all) | --all, --tenant-id	—
add <inputs…>	Ingest text / file paths / HTTP(S) URLs into a dataset	-d/--dataset-name (main_dataset), --tenant-id	—
cognify	Build the knowledge graph from one or more datasets	-d/--datasets, --chunk-size, --chunker (TextChunker/LangchainChunker/CsvChunker), --ontology-file, -b/--background, --llm-max-retries, --llm-max-parallel-requests, --temporal-cognify	—
add-and-cognify <inputs…>	add then cognify in one step	union of the above	—
memify	Enrich an existing graph with triplet embeddings	-d/--datasets, --node-type, --node-name, --batch-size (100)	—
search <query>	Query the graph/vectors	-t/--query-type (GRAPH_COMPLETION), -d/--datasets, -k/--top-k (10), --system-prompt / --system-prompt-path, --session-id, -f/--output-format (pretty/json/simple), --llm-max-retries	—
export	Write the graph as a COGX archive that Python cognee can re-import (cognee.remember(COGXArchiveSource(path)), or upload the packed tarball to /api/v1/remember with content_type=cogx-archive)	-o/--output (dir; default <dataset>_cogx, or cognee_cogx without -d), -d/--dataset (label only — does not scope the export; the whole graph store is written), --pack (also write <output>.cogx.tar.gz), --format (default cogx; any other value is rejected)	—
delete	Remove data/datasets across all backends	-d/--dataset-name | --dataset-id, --data-id, --all, -u/--user-id, --mode (soft/hard, default soft), --dry-run, -f/--force, --delete-dataset-if-empty (with --data-id), --enforce-acl	—
pipeline-unblock	Report, and with --clear remove, what a killed run left behind — the unfinished pipeline_runs row (checked first, never expires outside an HTTP-server restart) and the exclusive-run claim (expires after 24h). Reports only unless --clear is passed, because nothing can tell a dead holder from a live run	-d/--dataset (required), --pipeline (cognify_pipeline/temporal-cognify/memify_pipeline; omit to check all three; required with --clear so clearing one wedged pipeline cannot retire a live run on another), --clear	—
vector-reindex	Build the ANN index on every vector collection missing one. pgvector only — a collection can lack its HNSW index because it predates the index or because its best-effort build failed (pgvector without the hnsw access method, a restricted role, too little maintenance_work_mem), which is logged and leaves a working but sequential-scan collection. Online (CREATE INDEX CONCURRENTLY) and idempotent, so it does the work rather than reporting first; on any other backend it says so and does nothing	— (no flags)	—
edge-reindex	Report, and with --apply write, the EdgeType_relationship_name vector rows the graph implies but the vector store lacks — the orphans left by a run killed between cognify’s graph write and its vector write (a retry never re-emits them, and the rollback sweeper only runs on in-process failures). Reporting is free (id probes only); applying bills one embedding per missing row. Counts are per distinct EdgeType point, not per edge. Not a crash-damage count: DLT foreign-key edges and structural edges (is_part_of, contains, made_from, is_a) cognified before edge_text stamping have no row on a healthy graph either, so expect a small constant floor (applying writes it too, as Python’s index_graph_edges does). The scan always loads the whole graph into memory. All backends	--apply, --dataset-id (label only — cannot scope the scan: the point id is hashed from the retrieval text alone, so one row is shared across datasets), --limit (writes only; needs --apply; must be >= 1), --resume-after (cursor from a previous run; narrows the reported counts too)	—
config get|set|unset|list|reset	Read/write the persisted JSON config	—	—
run-sequence <files…>	Run a scripted add/cognify/search sequence from JSON file(s)	—	—
visualize	Render the graph to a single-file multi-tab HTML page	-o/--output (~/graph_visualization.html)	visualization
bench	Phase-timed benchmark driver	--memories, --mock-llm, --output	bench

The feature-gated commands are enabled in the default build of cognee-cli (except platform-specific ones). See Architecture: feature strategy.

Cloud serve / disconnect are not part of OSS.

Memory API

The four primary verbs cover the common workflow end-to-end:

# Store memory (add + cognify + improve). Inline text and/or file paths.
cognee-cli remember "Cognee turns data into a knowledge graph" ./notes.txt -d my_dataset

# Scope a turn to a session (session-backed memory) instead of permanent graph memory
cognee-cli remember "follow-up note" --session-id chat-42

# Query memory — omit -t to let recall auto-route the retrieval strategy
cognee-cli recall "what did we learn about X?" -d my_dataset -k 10

# Enrich memory / bridge sessions
cognee-cli improve -d my_dataset --session-id chat-42

# Remove memory
cognee-cli forget --all
cognee-cli forget -d my_dataset
cognee-cli forget --data-id 00000000-0000-0000-0000-000000000000 -d my_dataset

remember with a --session-id records session memory; without one it persists permanent, graph-backed memory. recall is session-aware and graph-backed; with no -t/--query-type it auto-routes to a suitable retrieval strategy.

Lower-level pipeline

The memory verbs compose add → cognify → search, which you can also drive directly for fine-grained control (remember ≈ add + cognify + improve; recall ≈ auto-routed search):

cognee-cli add ./notes.txt "some inline text" -d my_dataset
cognee-cli cognify -d my_dataset
cognee-cli search "what did we learn about X?" -t GRAPH_COMPLETION -d my_dataset -k 10

A cognify run that the configured failure policy let complete despite per-document failures prints one extra WARN line per dataset (cognify completed with failures — …), naming the counts and the first ten failed data ids (… (first 10 of N) beyond that), and saying whether a re-run would pick the outstanding documents up. A clean run prints nothing extra. The same numbers — with the untruncated id list — are persisted under pipeline_runs.run_info.cognify_failures. Which failures are tolerated at all is the failure policy in Configuration: cognify failure handling; the default errors the run instead.

-t/--query-type on search / recall accepts GRAPH_COMPLETION, RAG_COMPLETION, CHUNKS, SUMMARIES, CODE, CYPHER and TEMPORAL (the QueryTypeArg enum in crates/cli/src/cli.rs; see also cognee-cli search --help). The library’s SearchType enum is larger (16 types, including HYBRID_COMPLETION — see Operations: search), but the other types are not exposed as CLI values yet. The hybrid retriever’s tuning knobs are not exposed as CLI flags either — see Configuration: hybrid retriever knobs.

config subcommand

Reads/writes ~/.config/cognee-rust/config.json. Keys are the snake_case Settings field names plus the keys of the component config sections compiled into this build. set and get take the canonical key (such as llm.model) or its Python flat alias (such as llm_model); cognee-cli config list prints the canonical keys only. See Configuration: CLI config.

cognee-cli config set llm_max_retries 4
cognee-cli config get llm_model
cognee-cli config unset embedding_endpoint

LLM retries

--llm-max-retries N (accepted by cognify, add-and-cognify, search) overrides the retry count for that run; the persistent default is the llm_max_retries config key (default 3). The CLI flag wins over the config value, which in turn is set by LLM_MAX_RETRIES.

It governs the structured-output retry loop only — the strict-schema, function-call and JSON-fallback parsing paths — and counts attempts, not re-asks: 3 is three attempts, so at most two corrective re-asks. The transport retry loop underneath it is a separate knob, LLM_NETWORK_RETRIES (config key llm_network_retries, default 2), which has no CLI flag. They used to share one value, which multiplied the two ladders into each other.

0 is accepted for consistency with the env var; every adapter floors the structured count at 1, so it means “one attempt, no re-ask”. To shorten a transport ladder that would otherwise keep waiting out its time floor, set LLM_MIN_RETRY_SECONDS=0.

A run-sequence step may carry the flag; it applies to that step, and steps without it fall back to the configured value.

cognee-cli cognify --llm-max-retries 4
cognee-cli search "What is TechCorp?" --llm-max-retries 4

Logging

The CLI calls cognee_logging::init_logging at startup. Console logs go to stderr instead of stdout whenever stdout is machine-readable — -f json / -f simple on search / recall, and always for export, visualize and bench — so that output stays parseable (a -f json step inside run-sequence is not detected and keeps stdout). The env-var surface (COGNEE_LOG_*, RUST_LOG/LOG_LEVEL, LOG_FILE_NAME) is shared with the HTTP server and bindings and documented canonically in Configuration: logging. Example — JSON logs to a custom directory:

COGNEE_LOG_FORMAT=json COGNEE_LOGS_DIR=/var/log/cognee cognee-cli cognify -d main_dataset