Cognee CLI

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

cognee-cli config set writes to a .env file too — it saves the value into .env in the directory you run it from, so the setting survives across CLI invocations. See Manage Configuration for details.

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 datasets lists datasets, inspects their contents, and reports processing status
cognee-cli forget removes stored data when you no longer need it
cognee-cli config reads and updates saved settings
cognee-cli push uploads a local dataset’s knowledge graph to Cognee Cloud
cognee-cli report writes a Graph Insight Report describing what a dataset’s graph contains
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

Remember Command Options

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
--dry-run: Estimate LLM token usage and cost without ingesting data or making LLM calls. Prints a stage-level token/cost summary and exits

Estimate cost before running (--dry-run)

Add --dry-run to remember (or the legacy cognify command) to print a stage-level estimate of LLM token usage and rough cost without ingesting data, making LLM calls, or writing the graph.

# Estimate the cost of ingesting a note
cognee-cli remember "Kickoff call notes: customer wants faster onboarding" --dry-run

# Estimate the cost of (re-)processing an existing dataset
cognee-cli cognify --datasets onboarding --dry-run

Dataset resolution is read-only for a dry run, so a typo’d dataset name fails instead of creating an empty dataset. Only local text, local files, and file:// URIs are supported for estimation — remote URLs, S3 paths, directories, and binary formats (PDF, images, audio) are rejected because a real run would fetch, walk, or transcribe them.

Ingesting a Folder

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

Improve Command Options

--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

Recall Types

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, CODE, CYPHER, and GRAPH_REPORT. Other search types (like GRAPH_SUMMARY_COMPLETION, CODING_RULES, and TEMPORAL) are available in the Python API.GRAPH_REPORT ignores the question you pass and returns a whole-graph Graph Insight Report; use the dedicated cognee-cli report command if you also want the Markdown written to a file.

Recall Command Options

--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)

Generate a Graph Insight Report

Not sure what actually ended up in your graph? cognee-cli report writes a Markdown Graph Insight Report covering the graph’s hub nodes, connections that cross node-set boundaries, an edge-provenance breakdown, and a few LLM-suggested questions to try with recall.

# Report on the default dataset, writing ./graph_report.md
cognee-cli report

# Report on a named dataset
cognee-cli report --datasets onboarding

# Surface more hubs and connections, and choose the output file
cognee-cli report -d onboarding -n 25 -o reports/onboarding-graph.md

The command prints a confirmation, the output path, and the first 500 characters of the report as a preview.

Report Command Options

--datasets (-d): Dataset name(s) to analyse (default: main_dataset). Only the first dataset you have access to is analysed — run the command once per dataset
--output (-o): Output file path for the Markdown report (default: graph_report.md)
--top-n (-n): Number of hub nodes and surprising connections to surface (default: 10)

The report is read-only — it computes everything from the existing graph and changes nothing. It makes a single LLM call for the suggested-questions section and falls back to a generic question if that call fails. report is not supported in --api-url mode — run it without --api-url and it executes in-process against your local databases. See the cognee.report() SDK reference for the programmatic equivalent and a breakdown of each report section.

Inspect Datasets

Forgot what you already stored? cognee-cli datasets answers “which datasets do I have?” and “did processing finish?”.

# List every dataset you can access (ID, name, created date)
cognee-cli datasets list

# Create an empty dataset up front
cognee-cli datasets create onboarding

# List the data items in a dataset
cognee-cli datasets data 123e4567-e89b-12d3-a456-426614174000

# Check processing status for one or more datasets
cognee-cli datasets status 123e4567-e89b-12d3-a456-426614174000

# Check several pipelines at once
cognee-cli datasets status <dataset-uuid> --pipelines cognify_pipeline memify_pipeline

# Export a dataset's knowledge graph as JSON
cognee-cli datasets graph <dataset-uuid> -o graph.json

# Delete a dataset and everything in it
cognee-cli datasets delete <dataset-uuid>

status prints one line per dataset, for example 123e4567-…: PipelineRunStatus.DATASET_PROCESSING_COMPLETED (in --api-url mode the status arrives as a plain string, without the PipelineRunStatus. prefix). Datasets with no recorded pipeline run are omitted (or shown as <no pipeline runs found> when you pass several --pipelines).

Datasets Subcommands

list: List all datasets you have read access to, with ID, name, and creation date
create <name>: Create an empty dataset and grant yourself read, write, share, and delete on it. Re-running with an existing name prints that dataset’s ID instead of creating a duplicate
data <dataset_id>: List the data items in a dataset (ID, name, MIME type, creation date)
status <dataset_ids...>: Show pipeline status for one or more datasets. --pipelines selects which pipelines to check (default: cognify_pipeline)
graph <dataset_id>: Export the dataset’s knowledge graph as JSON. -o/--output writes to a file instead of stdout
delete <dataset_id>: Delete the dataset and all of its data. -f/--force skips the confirmation prompt

Every subcommand except create takes a dataset UUID, not a dataset name — run cognee-cli datasets list first to look the ID up. Use the global --user-id flag to act as a specific user (status checks pipeline runs directly and ignores it). For the programmatic equivalent, see cognee.datasets; for the browser view, see the Brain page.

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

Forget Command Options

--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
cognee-cli config get llm_model

# Show every known setting (secrets masked)
cognee-cli config get

# 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

Settings Persist to `.env`

config set and config unset write the resolved value into a .env file in the current working directory, creating the file if it does not exist yet. This is the same file Cognee reads at startup, so a value you set is picked up by the next CLI invocation or script started from that directory:

$ cognee-cli config set llm_model gpt-4o-mini
Success: Set llm_model = gpt-4o-mini
Note: Created new .env file at /home/you/project/.env
Note: Persisted LLM_MODEL to /home/you/project/.env

Because the .env file lands in whatever directory you happen to run the command from, cognee-cli config set llm_api_key ... can drop a plaintext API key into a source tree. Add .env to your .gitignore, restrict its permissions (chmod 600 .env), and run config set from the directory you actually want the settings to apply to.

Secrets Are Masked by Default

config get masks secret values — llm_api_key, embedding_api_key, and vector_db_key — showing only the first three and last four characters (values of eight characters or fewer are replaced entirely with *). Pass --show-secrets to print them in plaintext:

$ cognee-cli config get llm_api_key
llm_api_key: sk-...c3d4

$ cognee-cli config get llm_api_key --show-secrets
llm_api_key: sk-proj-9f2a7b41c3d4

Config Command Options

list: Print the common keys
get [key]: Show the saved value; omit the key to list every known setting. Secrets are masked unless you add --show-secrets
set <key> <value>: Save a new value and persist it to .env in the current directory. JSON strings such as {} or true are parsed automatically
unset <key>: Reset to the default and persist that default to .env. Add --force to skip confirmation
reset: Placeholder for a future “reset everything” command

Useful Configuration Keys

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

Manage Agents

The agents command creates and manages agents and their connections. Each agent is backed by its own agent user with a one-time API key, and every action is scoped to the acting user (see the global --user-id flag below).

# Create an agent and grant it read/write on one or more datasets
cognee-cli agents create my-agent --datasets onboarding sales_calls

# List the agents you own
cognee-cli agents list

# Show details for a single agent
cognee-cli agents get <agent-uuid>

# Delete an agent (use -f to skip the confirmation)
cognee-cli agents delete <agent-uuid>

# Register and unregister an agent connection (session)
cognee-cli agents register session-1 --dataset-names onboarding
cognee-cli agents unregister session-1

# List active agent connections and their memory sources
cognee-cli agents connections --range 7d --status active

agents create prints the agent’s API key once. It is a one-time secret and cannot be retrieved again — store it immediately.

Agents Subcommands

create <name>: Create a new agent. --datasets accepts dataset names or UUIDs to grant the agent read/write access to
list: List all agents you own
get <agent_id>: Show an agent’s id, email, and API key label
delete <agent_id>: Delete an agent. -f/--force skips the confirmation prompt
register <agent_session_name>: Register an agent connection. Options: --type (default api), --memory-mode (default unknown), --session-id, --dataset-ids, --dataset-names
unregister <agent_session_name>: Unregister an agent connection and report the remaining active count
connections: List active connections. Options: --agent-id, --range (default 30d), --status, --limit (default 50), --offset (default 0)

The agents command resolves --user-id strictly: a valid-but-unknown UUID is a hard error rather than a silent fallback to the default user, because falling back would break the isolation the flag promises. Create the user first, or omit --user-id to act as the default user.

For the equivalent Python SDK, see cognee.agents.

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. It also tries to launch the Cognee MCP server in Docker. If Docker is not reachable, the CLI skips MCP startup and leaves the UI and backend running. The launcher runs the UI in local mode (it defaults NEXT_PUBLIC_IS_CLOUD_ENVIRONMENT=false). In this mode an LLM API key is optional at startup: if none is configured, you can enter one from the dashboard, and Cognee saves it to the running backend for the rest of the session — the equivalent of setting LLM_API_KEY. Because the key lives only in the running process, it is not persisted after you stop the UI; add it to your .env if you want it to survive a restart.

MCP Docker Networking

cognee-cli -ui supports Docker Desktop, Colima, or any OCI-compatible runtime with a working docker CLI. Before pulling the MCP image, it runs a docker info preflight check and logs setup guidance if the daemon is unavailable.When the backend starts with the UI, the MCP container receives API_URL=http://localhost:<backend-port> (default backend port 8000). The launch command does not add an explicit --add-host host.docker.internal:host-gateway mapping; instead, the MCP image rewrites localhost by trying Docker Desktop, Colima/Lima, and the container gateway fallback automatically.If the container logs say host-address auto-detection failed, use the manual networking workarounds in the MCP API mode notes. See Docker & Colima Setup for Docker 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. --api-url works against Cognee Cloud tenants as well as self-hosted servers: the CLI follows HTTP redirects and normalizes dataset endpoints so both cloud (slash-canonical) and local OSS installs resolve. The CLI runs your command directly against the endpoint rather than pinging /health first, so a reachable server is never mis-reported as offline.

Connection and HTTP errors

If the CLI can’t reach the server (wrong URL, server down, DNS or timeout failure), it reports the attempted URL so you can spot a typo quickly:

Could not reach the Cognee API at https://your-api.example.com: <transport error>
Check the --api-url value and that the server is reachable
(local server: uvicorn cognee.api.client:app --port 8000).

If the server responds with an HTTP error — for example 401/403 (bad or missing credentials) or 404 (wrong path) — the CLI shows the status code and the server’s actual response instead of masking it as a generic connection failure. Use this detail to distinguish an unreachable server from an authentication or routing problem.

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 Mode Options

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

Push to Cloud

Already built a knowledge graph locally and want it on Cognee Cloud? cognee push exports the dataset’s graph as a COGX archive and imports it on the remote instance, preserving the entities and relationships you extracted locally instead of re-deriving them from the raw files.

# Log in once (saves credentials for reuse)
cognee serve

# Push the default dataset (main_dataset)
cognee push

# Push a named dataset
cognee push my_dataset

# Push into a different dataset name on the remote instance
cognee push my_dataset --target-dataset prod_dataset

# Preserve the graph AND re-cognify the raw content remotely
cognee push my_dataset --mode hybrid

# Large graph: schedule the remote import and return after the upload
cognee push my_dataset --background

# Push to an explicit instance without a prior serve login
cognee push --url https://my.cognee.ai --api-key ck_...

Push Command Options

dataset: Local dataset name to push (default: main_dataset)
--target-dataset: Dataset name on the remote instance (default: same as local)
--mode: Remote import mode (default: preserve)
- preserve — map exported entities/facts directly, zero LLM calls
- hybrid — preserve the graph and also cognify the raw content
- re-derive — ignore the exported graph and rebuild from raw content remotely
--url: Remote instance URL. Falls back to the active serve connection, COGNEE_SERVICE_URL, or saved serve credentials
--api-key: API key for the remote instance. Falls back to COGNEE_API_KEY
--background, -b: Schedule the remote import in the background and return after the upload (recommended for large graphs); prints the pipeline run id

The dataset must already have a knowledge graph — run cognee remember (or cognee cognify) first. Authentication reuses your cognee serve login; alternatively pass --url/--api-key or set COGNEE_SERVICE_URL and COGNEE_API_KEY. This is the graph-preserving counterpart to syncing, which instead ships raw data for the remote instance to rebuild. See the cognee.push() SDK reference for the programmatic equivalent.

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.

Getting Started

Core Concepts

Setup Configuration

Guides

Examples

CLI

Rust SDK

TypeScript SDK

OSS

Install the CLI

Setup

Quick Tour of Commands

Remember Data

Improve Memory

Recall Memory

Generate a Graph Insight Report

Inspect Datasets

Forget Data

Manage Configuration

Settings Persist to `.env`

Secrets Are Masked by Default

Manage Agents

Launch the UI

Talk to a Running Cognee API

Authenticate Against the API

Push to Cloud

Next Steps

Installation Guide

Quickstart Tutorial

​Install the CLI

​Setup

​Quick Tour of Commands

​Remember Data

​Improve Memory

​Recall Memory

​Generate a Graph Insight Report

​Inspect Datasets

​Forget Data

​Manage Configuration

​Settings Persist to .env

​Secrets Are Masked by Default

​Manage Agents

​Launch the UI

​Talk to a Running Cognee API

​Authenticate Against the API

​Push to Cloud

​Next Steps

Installation Guide

Quickstart Tutorial

Install the CLI

Setup

Quick Tour of Commands

Remember Data

Improve Memory

Recall Memory

Generate a Graph Insight Report

Inspect Datasets

Forget Data

Manage Configuration

Settings Persist to `.env`

Secrets Are Masked by Default

Manage Agents

Launch the UI

Talk to a Running Cognee API

Authenticate Against the API

Push to Cloud

Next Steps