Skip to main content
The cognee-cli command lets you run Cognee from the terminal so you can remember data, enrich memory, and ask questions without opening a Python file. The commands are designed to be short, use friendly defaults, and are safe for people who are just starting out.

​
Install the CLI

The cognee-cli command ships with the cognee package — installing cognee makes it available. To use it inside a project, install Cognee the usual way (see the Installation Guide): 
uv pip install cognee   # or: pip install cognee
To install the CLI globally so the cognee-cli command works from anywhere, use a tool that installs Python applications into isolated environments and puts their commands on your PATH: 
# With pipx
pipx install cognee

# Or with uv
uv tool install cognee
This exposes cognee-cli system-wide without polluting your project’s virtual environment. To add an extra (for example Postgres support) to the global install, include it in the package spec, e.g. pipx install "cognee[postgres]" or uv tool install "cognee[postgres]".

​
Setup

Before using the CLI, you need to configure your API key. The recommended approach is to store it in a .env file: 
# Create a .env file in your project root
echo "LLM_API_KEY=your_openai_api_key" > .env
Alternatively, you can export it in your terminal session: 
export LLM_API_KEY=your_openai_api_key
Use the cognee-cli config set command only for temporary tweaks during a long-running session. For persistent configuration, use .env files or environment variables.

​
Quick Tour of Commands

  • cognee-cli remember <data> ingests data and builds retrieval-ready memory in one step
  • cognee-cli recall "question" retrieves answers from the graph or session memory
  • cognee-cli improve enriches an existing dataset
  • cognee-cli forget removes stored data when you no longer need it
  • cognee-cli config reads and updates saved settings
  • cognee-cli -ui launches the local web app
Add --help after any command (for example, cognee-cli recall --help) to see every option.
The CLI still includes lower-level legacy commands such as add, cognify, search, and delete, but for new workflows the v1.0 remember / recall / improve / forget commands are the preferred interface.

​
Remember Data

Start by loading something the graph can learn from. You can remember files, folders, URLs, S3 paths, or even plain text. 
# Remember a single file into the default dataset
cognee-cli remember docs/company-handbook.pdf

# Pick a dataset name so you can separate topics later
cognee-cli remember docs/policies.docx --dataset-name onboarding

# Remember multiple files at once
cognee-cli remember docs/policies.docx docs/faq.md --dataset-name onboarding

# Remember an entire folder (walks all subdirectories recursively)
cognee-cli remember docs/ --dataset-name onboarding

# Remember a short text note (wrap the note in quotes)
cognee-cli remember "Kickoff call notes: customer wants faster onboarding" --dataset-name sales_calls
  • data: One or more file paths, directory paths, URLs, S3 paths, or text strings. Mix and match as needed
  • --dataset-name (-d): Defaults to main_dataset. Use clear names so the team remembers what each dataset holds
  • --chunk-size: Token limit for each chunk. Leave blank to let Cognee choose
  • --chunker: TextChunker (default), CsvChunker, or LangchainChunker
  • --background (-b): Ingests data, then keeps graph-building running in the background
  • --chunks-per-batch: Number of chunks to process per task batch
Pass a directory path directly to remember (or add) and Cognee walks it recursively, picking up every file in the folder and all of its subdirectories. There is no --recursive flag and no need to shell-expand with globs or find; the ingestion pipeline handles the traversal for you.
# Ingest every file under docs/, at any depth
cognee-cli remember docs/ --dataset-name handbook

# Local paths and S3 prefixes work the same way
cognee-cli remember s3://my-bucket/docs/ --dataset-name handbook
To restrict ingestion to specific files, list them explicitly instead of pointing at the parent folder.

​
Improve Memory

Use improve when you want to enrich an existing dataset after ingestion. This is especially useful for session-bridging or an explicit post-processing pass over memory you already stored. 
# Improve the default dataset
cognee-cli improve

# Improve a named dataset
cognee-cli improve --dataset-name onboarding

# Improve a dataset and bridge selected session histories
cognee-cli improve --dataset-name onboarding --session-ids chat_1 chat_2

# Kick off a long job and return immediately
cognee-cli improve --dataset-name onboarding --background
  • --dataset-name (-d): Dataset to improve. Defaults to main_dataset
  • --dataset-id: Dataset UUID (alternative to --dataset-name)
  • --node-name: Narrow the improvement pass to specific named entities
  • --session-ids (-s): Session IDs whose Q&A and feedback should be bridged into the permanent graph
  • --feedback-alpha: Learning rate for feedback-based weighting updates
  • --background (-b): Handy for large datasets; the CLI exits while the job keeps running

​
Recall Memory

Once remember finishes, you can question the graph. Start with a simple natural-language question, then experiment with search types. The CLI exposes a subset of the available retrieval types; see Recall for the memory-oriented workflow and Search for the lower-level search type reference. 
# Default recall (GRAPH_COMPLETION)
cognee-cli recall "Who owns the rollout plan?"

# Limit the scope to one dataset
cognee-cli recall "What is the onboarding timeline?" --datasets onboarding

# Return three answers at most
cognee-cli recall "List the key risks" --top-k 3

# Save a JSON response for another tool
cognee-cli recall "Which documents mention security?" --output-format json
Try these quick examples to feel the differences:
# Conversational answer with reasoning (default)
cognee-cli recall "Give me a summary of onboarding" --query-type GRAPH_COMPLETION

# Shorter answer based on chunks
cognee-cli recall "Show the onboarding steps" --query-type RAG_COMPLETION

# Raw text passages you can copy
cognee-cli recall "Find security requirements" --query-type CHUNKS --top-k 5

# Summaries only (great for reviews)
cognee-cli recall "Summarise the onboarding handbooks" --query-type SUMMARIES

# Advanced graph query (requires Cypher skills)
cognee-cli recall "MATCH (n) RETURN COUNT(n)" --query-type CYPHER
The CLI supports a subset of search types: GRAPH_COMPLETION, RAG_COMPLETION, CHUNKS, SUMMARIES, and CYPHER. Other search types (like GRAPH_SUMMARY_COMPLETION, CODING_RULES, and TEMPORAL) are available in the Python API.
  • --query-type: Subset of search types (e.g. GRAPH_COMPLETION, RAG_COMPLETION, CHUNKS, SUMMARIES, CYPHER). See Search for the full list.
  • --datasets: Limit search to specific datasets
  • --top-k: Maximum number of results to return
  • --system-prompt: Point to a custom prompt file for LLM-backed modes
  • --session-id (-s): Search session memory directly when used by itself, or add session history to graph-backed recall
  • --output-format (-f): pretty (friendly layout), simple (minimal text), or json (structured output for scripts)

​
Forget Data

Clean up when a dataset is outdated or when you reset the environment. 
# Remove one dataset
cognee-cli forget --dataset onboarding

# Remove a single item from a dataset
cognee-cli forget --dataset onboarding --data-id 123e4567-e89b-12d3-a456-426614174000

# Wipe everything for the current user (--all is an alias for --everything)
cognee-cli forget --everything
  • --dataset: Dataset name or UUID to remove
  • --data-id: Remove a single item from the specified dataset
  • --everything (alias --all): Remove all datasets and data for the current user
forget is the v1.0 deletion interface. If you still need the older delete flow, it remains available as a lower-level legacy command.

​
Manage Configuration

The CLI stores its settings so you do not have to repeat them. Configuration updates line up with the Python API. 
# See the list of supported keys
cognee-cli config list

# Check one value (if implemented)
cognee-cli config get llm_model

# Update your LLM provider and model
cognee-cli config set llm_provider openai
cognee-cli config set llm_model gpt-4o-mini

# Store an API key (quotes are optional)
cognee-cli config set llm_api_key sk-yourkey

# Reset a key back to its default value
cognee-cli config unset chunk_size
  • list: Print the common keys
  • get [key]: Show the saved value; omit the key to list everything
  • set <key> <value>: Save a new value. JSON strings such as {} or true are parsed automatically
  • unset <key>: Reset to the default. Add --force to skip confirmation
  • reset: Placeholder for a future “reset everything” command
  • Language model: llm_provider, llm_model, llm_api_key, llm_endpoint
  • Storage: graph_database_provider, vector_db_provider, vector_db_url, vector_db_key
  • Chunking: chunk_size, chunk_overlap

​
Launch the UI

Prefer a browser view? Launch the UI with one flag. 
cognee-cli -ui
The CLI starts the backend on http://localhost:8000 and the React app on http://localhost:3000. Leave the window open and press Ctrl+C to stop everything.
cognee-cli -ui also launches the Cognee MCP server inside a Docker container, so a running Docker-compatible daemon is required. Docker Desktop, Colima, or any OCI-compatible runtime with a working docker CLI is supported. Before pulling the MCP image the CLI runs a docker info preflight check; if the Docker daemon is not reachable it logs actionable guidance and skips MCP startup, leaving the UI and backend running. See Docker & Colima Setup for setup and troubleshooting.

​
Talk to a Running Cognee API

Add --api-url to delegate any supported command to a running Cognee API server instead of executing it in-process. This is the recommended mode for multi-agent or concurrent usage with file-based databases (SQLite, Ladybug, LanceDB), because it lets a single server own all database connections. 
# Use a locally running API server
cognee-cli --api-url http://localhost:8000 remember docs/handbook.pdf

# Ask the same server for an answer
cognee-cli --api-url http://localhost:8000 recall "Who owns onboarding?"

# Improve a dataset on the remote server in the background
cognee-cli --api-url http://localhost:8000 improve --dataset-name onboarding --background
Commands supported in --api-url mode: add, cognify, search, memify, datasets, delete, remember, recall, improve, and forget. Any other command runs locally; pass --api-url only with commands from this list.

​
Authenticate Against the API

If the target API requires authentication, supply credentials with one of the flags below (or their environment-variable fallbacks). The CLI sends the credentials only when --api-url is set. 
# Cognee Cloud or any backend that uses an API key
cognee-cli --api-url https://your-api.example.com \
           --api-key sk-yourkey \
           recall "What's in the handbook?"

# Self-hosted backend with a bearer token issued by /api/v1/auth/login
cognee-cli --api-url http://localhost:8000 \
           --api-token your_bearer_token \
           remember docs/handbook.pdf
  • --api-url: URL of the Cognee API server (for example http://localhost:8000). When set, supported commands are forwarded over HTTP
  • --api-key: API key sent as the X-Api-Key header. Falls back to the COGNEE_API_KEY environment variable
  • --api-token: Bearer token sent as Authorization: Bearer <token>. Falls back to the COGNEE_API_TOKEN environment variable. Ignored when --api-key is also provided
  • --user-id: Optional UUID forwarded as the X-User-Id header for multi-agent isolation. The server must be configured to honour this header
In --api-url mode the server controls chunking and feedback weighting, so --chunker on remember and --feedback-alpha on improve are ignored.

​
Next Steps

Installation Guide

Set up your environmentInstall Cognee and configure your environment to start using the CLI.

Quickstart Tutorial

Run your first exampleGet started with Cognee by running your first knowledge graph example.