CLI Reference — @getengram/cli

Command-line interface for Engram. Store, search, and auto-capture AI conversations from your terminal.

Install

Homebrew (recommended)


brew tap get-engram/engram
brew install engram

This installs the engram binary and enables brew services for daemon management.

npm


npm install -g @getengram/cli

Or use without installing:


npx @getengram/cli search "your query"

Account & Authentication

Create an account


engram signup

Creates a free account instantly — no email, no password. Your API key is saved to ~/.engram/config.json automatically. AI agents can run this command to self-provision.


engram login

Prompts for email + password. Use this if you already have an account from the website.

Link your account


engram link

Attach an email + password to an anonymous account. This lets you:

Sign in at getengram.app/dashboard
Upgrade to Pro or Team
Recover your account if you lose your API key

Manual API key entry


engram auth login engram_sk_live_YOUR_KEY

For cases where you already have a key (e.g. from the dashboard or a team admin).

Other auth commands


engram auth status    # Show authentication status
engram auth logout    # Remove stored credentials

Environment variable


export ENGRAM_API_KEY=engram_sk_live_YOUR_KEY

This overrides the saved config — useful for CI, scripts, or per-project keys.

Commands

engram conversations list

List all conversations.


engram conversations list
engram conversations list --agent my-bot --tags prod,api
engram conversations list --sort message_count --order desc
engram conversations list --limit 5 --json

Flag	Description
`--agent ID`	Filter by agent ID
`--tags A,B`	Filter by tags (comma-separated)
`--sort FIELD`	Sort by: `created_at`, `updated_at`, `message_count`
`--order DIR`	Sort direction: `asc`, `desc`
`--limit N`	Max results
`--json`	Output as JSON

engram conversations create

Create a new conversation.


engram conversations create --title "Deploy Log" --tags prod,deploy --agent deploy-bot

Flag	Description
`--title TEXT`	Conversation title
`--agent ID`	Agent identifier
`--tags A,B`	Tags (comma-separated)
`--json`	Output as JSON

engram conversations get

Retrieve a conversation with all its messages.


engram conversations get conv_abc123
engram conversations get conv_abc123 --limit 50
engram conversations get conv_abc123 --json

engram conversations delete

Delete a conversation and all its data.


engram conversations delete conv_abc123 --force

The --force flag is required to confirm deletion.

engram store

Store a message in a conversation.


# Store text
engram store -c conv_abc "Deployed v2.1.0 to production"
 
# Specify role
engram store -c conv_abc --role assistant "Deploy successful"
 
# Tool output
engram store -c conv_abc --role tool --tool deploy "exit code 0"
 
# From stdin
echo "build output" | engram store -c conv_abc --file -
 
# From file
engram store -c conv_abc --file ./deploy.log

Flag	Description
`-c, --conversation ID`	Conversation ID (required)
`--role ROLE`	Message role: `user`, `assistant`, `system`, `tool` (default: `user`)
`--tool NAME`	Tool name (for tool messages)
`--file PATH`	Read content from file (use `-` for stdin)
`--json`	Output as JSON

engram search

Semantic search across all stored conversations.


engram search "when did we deploy v2"
engram search "error handling" --limit 5
engram search "auth issues" --tags prod --conversation conv_abc
engram search "deploy" --json

Flag	Description
`--limit N`	Max results (1–50, default: 10)
`--conversation ID`	Limit to specific conversation
`--tags A,B`	Filter by tags
`--json`	Output as JSON

Output shows relevance score, conversation ID, and matched text:


[80.4%] conv_Y4KAdWuDUTAobIAi3toSC seq 1–3
  [system]: Building Engram Phase 2...
  [assistant]: Codebase analysis complete...
  [user]: User wants npm and brew distribution...

engram log

Show recent AI conversation activity, like git log.


engram log                # Show recent auto-captured sessions
engram log --all          # Include manually-created conversations
engram log --limit 30     # More results
engram log --json         # Output as JSON

Flag	Description
`--all`	Show all conversations, not just auto-captured
`--limit N`	Max results (default: 15)
`--json`	Output as JSON

Output shows project name, branch, timestamp, and message count:


engram main
  2026-04-14 09:32  47 msgs  conv_abc123  [auto]

my-project feature/auth
  2026-04-14 08:15  23 msgs  conv_def456  [auto]

Daemon (Auto-Capture)

The Engram daemon runs in the background and automatically captures every Claude Code conversation. It watches the JSONL transcript files that Claude Code writes to ~/.claude/projects/ and syncs them to your Engram account.

Why this matters

Claude Code stores every message, tool call, and response in JSONL files on your local machine. When Claude Code hits its context window limit, it compresses older messages — but the full uncompressed transcript stays on disk. The Engram daemon captures this complete record before anything is lost.

Without the daemon, memory depends on the AI choosing to store things via MCP. With the daemon, everything is captured automatically — no AI cooperation needed.

Start the daemon

With Homebrew:


brew services start engram

With npm:


engram start              # Start in background
engram install            # Auto-start on login (macOS launchd)

engram start

Start the background daemon.


engram start              # Detached background process
engram start --foreground # Run in foreground (for debugging or launchd)
engram start --install    # Start + enable auto-start on login

Flag	Description
`--foreground`, `-f`	Run in foreground instead of detaching
`--install`	Also install launchd auto-start

engram stop

Stop the running daemon.


engram stop

engram status

Show daemon status and sync statistics.


engram status

Output:


Status: running (pid 12345)
Sessions captured: 47
Pending sync:      0 messages
Files tracked:     128
Log: /Users/you/.engram/daemon.log
Auto-start: enabled (launchd)

engram install

Enable auto-start on login (macOS launchd).


engram install

This writes a LaunchAgent plist so the daemon starts automatically when you log in and restarts if it crashes.

engram uninstall

Remove auto-start.


engram uninstall

How the daemon works

Watches ~/.claude/projects/ for JSONL transcript files using file system events
Parses each line — extracts user messages, assistant responses, and tool calls
Queues messages in a local SQLite database (~/.engram/daemon.db) for offline resilience
Syncs batches to the Engram API in parallel, creating conversations automatically
Tracks byte offsets per file so it only reads new content, even after restarts

Messages are never lost — if you’re offline or the API is unavailable, they queue locally and sync when connectivity returns.

Daemon files

Path	Description
`~/.engram/daemon.pid`	Process ID file
`~/.engram/daemon.db`	Local SQLite queue and state
`~/.engram/daemon.log`	Daemon log output
`~/Library/LaunchAgents/app.getengram.daemon.plist`	macOS auto-start config

engram help

Show help text with all commands and options.


engram help
engram --help

engram version


engram version

Environment Variables

Variable	Description	Default
`ENGRAM_API_KEY`	API key (overrides `~/.engram/config.json`)	—
`ENGRAM_BASE_URL`	Custom Engram endpoint	`https://mcp.getengram.app`

Configuration File

Credentials are stored in ~/.engram/config.json:


{
  "apiKey": "engram_sk_live_...",
  "baseUrl": "https://mcp.getengram.app"
}

Scripting Examples

Create and populate a session


CONV=$(engram conversations create --title "Build $(date +%F)" --json | jq -r '.conversationId')
npm run build 2>&1 | engram store -c $CONV --file -
npm test 2>&1 | engram store -c $CONV --role tool --tool test --file -
engram store -c $CONV --role assistant "Build and tests complete"

Search and pipe to jq


engram search "deploy" --json | jq '.results[] | {score, text: .chunkText[:80]}'

Export a conversation


engram conversations get conv_abc --json > conversation-backup.json