Engram — CLI Reference

The Engram CLI serves two purposes: agent runtime (fetching context for AI tools) and admin tool (managing sources, analysis, generation, and deployment as an alternative to the dashboard).

Built on Bun with Commander.js. Startup time is ~25ms.

Installation

Via npm (Node.js 18+)

npm install -g @engram/cli

Via Bun

bun install -g @engram/cli

From Source

git clone https://github.com/engram-dev/engram.git
cd engram/packages/cli
bun install
bun run build
bun link

After installation, the engram command is available globally.

Configuration

`engram init`

Interactive setup. Configures the API server URL, API key, and workspace.

engram init

Prompts for:

Server URL — the Engram API endpoint (default: http://localhost:8080).
API Key — a workspace-scoped API key (ek_...). Generate one in the dashboard under Settings > API Keys.

The command verifies connectivity (calls /health) and fetches workspace info to confirm the key is valid. Configuration is saved to a local config file managed by the conf package (typically ~/.config/engram-nodejs/config.json on Linux, ~/Library/Preferences/engram-nodejs/config.json on macOS).

`engram status`

Shows current connection status, workspace info, and document counts.

engram status

Output:

Engram Status

  Server:     connected http://localhost:8080
  Version:    0.1.0
  Workspace:  Acme Corp (acme)
  Plan:       team
  Domains:    5
  Documents:  24 total (18 active, 3 draft, 3 needs-review)

Agent Integration Commands

These are the primary commands for AI tool integrations. They output clean markdown to stdout by default (for piping to agents) and support --json and --pretty for other use cases.

`engram context`

Fetch compiled context for the current workspace. This is the hot-path command — what AI agents call to get guidelines.

engram context [options]

Options:

Flag	Description
`-r, --role <role>`	Filter by role (e.g., `backend`, `frontend`, `marketing`). Returns only documents mapped to this role in the routing config.
`-t, --target <target>`	Compilation target: `claude`, `cursor`, `copilot`, `windsurf`, `agents-md`. Determines the output file format.
`-f, --file <path>`	File-aware context. Returns guidelines relevant to this file path (inferred from extension and path patterns).
`-c, --category <category>`	Filter by domain category: `engineering`, `product`, `design`, `marketing`, `sales`, `support`, `operations`, `security`, `other`.
`--json`	Output as JSON (array of `{ target, files: [{ path, content }] }`).
`--pretty`	Human-readable output with colors, headers, and file path separators.

Default output: Clean markdown to stdout. Each file's content is printed with a blank line separator. Designed for piping directly into AI tool context windows.

Examples:

# Get all context for the workspace (agent default)
engram context

# Backend-specific guidelines in Claude format
engram context --role backend --target claude

# Guidelines relevant to a specific file
engram context --file src/api/routes/users.ts

# Only engineering guidelines
engram context --category engineering

# JSON output for programmatic use
engram context --role frontend --json

# Human-readable preview
engram context --pretty

`engram search <query>`

Semantic search across guidelines and source documents using pgvector embeddings.

engram search <query> [options]

Arguments:

Argument	Description
`<query>`	Natural language search query.

Options:

Flag	Description
`-l, --limit <n>`	Maximum number of results (default: `10`).
`-s, --scope <scope>`	Search scope: `all` (default), `documents` (guidelines only), `sources` (ingested source pages only).
`--json`	Output as JSON.
`--pretty`	Human-readable output with similarity scores, types, and domains.

Default output: Plain markdown. Each result is a heading with the title, followed by a content preview and source URL (if available).

Examples:

# Search for API error handling conventions
engram search "how to handle API errors"

# Search only guidelines (not sources), limit to 5
engram search "brand voice" --scope documents --limit 5

# JSON output
engram search "authentication flow" --json

# Human-readable with scores
engram search "deployment process" --pretty

Source Management

`engram sources list`

List all connected sources with their sync status.

engram sources list

`engram sources add <type> [target]`

Connect a new source.

engram sources add <type> [target] [options]

Arguments:

Argument	Description
`<type>`	Source type: `github`, `git_lab`, `bitbucket`, `notion`, `confluence`, `share_point`, `website`, `google_workspace`.
`[target]`	Target URL (required for `website` type, optional otherwise).

Options:

Flag	Description
`--org <org>`	GitHub/GitLab/Bitbucket organization name (for `github`, `git_lab`, `bitbucket` types).

For OAuth-based sources (Notion, Confluence, SharePoint, Google Workspace), the CLI creates the source connection and prints a message to complete the OAuth authorization flow in the dashboard.

Examples:

engram sources add github --org acme-corp
engram sources add website https://www.acme.com
engram sources add notion
engram sources add confluence
engram sources add google_workspace
engram sources add git_lab --org acme-corp
engram sources add share_point

`engram sources sync`

Trigger source ingestion. Fetches pages from connected sources and updates the index.

engram sources sync [options]

Options:

Flag	Description
`-s, --source <id>`	Sync a specific source by ID. Without this flag, all sources are synced.

Sync is an async operation. The command prints the job ID for each source.

`engram sources delete <id>`

Remove a source connection and all its mappings.

engram sources delete src_abc123

Gap Analysis

`engram analyze`

Run a gap analysis on all connected and synced sources. Produces three buckets: topics that can be created, issues found, and missing critical topics.

engram analyze [options]

Options:

Flag	Description
`--status`	Show the latest analysis results instead of triggering a new one.
`--json`	Output as JSON (only with `--status`).

Analysis is an async AI job. The command prints the job ID. Use --status to check results after the job completes.

Examples:

# Start a new analysis
engram analyze

# View latest results
engram analyze --status

# Machine-readable results
engram analyze --status --json

Topic Review

`engram topics list`

List all topics from the latest analysis, grouped by status: pending, confirmed, and dismissed.

engram topics list

`engram topics confirm <title>`

Confirm a pending topic for document generation.

engram topics confirm "API Conventions"

The topic title must exactly match the title from the analysis output.

`engram topics dismiss <title>`

Dismiss a pending topic. It will not be used for generation.

engram topics dismiss "Sales Methodology"

Document Generation

`engram generate <topic>`

Generate a guideline document from a confirmed topic. The topic must exist in the latest analysis (confirmed or pending).

engram generate <topic>

Arguments:

Argument	Description
`<topic>`	The topic title to generate a guideline for (must match exactly).

Generation is an async AI job. The command prints the job ID. The generated document appears in the workspace with status needs-review.

Example:

engram generate "API Conventions"

Validation

`engram validate`

Run validation checks on all guidelines in the workspace.

engram validate [options]

Options:

Flag	Description
`--checks <checks...>`	Run specific checks only. Valid values: `freshness`, `contradictions`, `completeness`, `coverage`, `drift`, `duplicates`.
`--wait`	Poll until the validation job completes and display results.
`--json`	Output results as JSON (requires `--wait`).

Without --wait, the command starts the validation job and exits immediately with the job ID. With --wait, it polls every 2 seconds for up to 2 minutes and then displays the results.

Examples:

# Run all checks, wait for results
engram validate --wait

# Check only freshness and contradictions
engram validate --checks freshness contradictions --wait

# JSON output for CI integration
engram validate --wait --json

Output (with --wait):

Running validation...

  Job ID: job_abc123
  Waiting............

  Health Score: 85/100

  Freshness Issues:
    ! Security Policies — 120 days since update

  Contradictions:
    ! API Conventions vs Architecture Patterns: conflicting naming convention (snake_case vs camelCase)

  Coverage Gaps:
    ! "error handling" referenced in API Conventions but not covered elsewhere

Compilation and Distribution

`engram compile [targets...]`

Compile active guidelines into tool-specific output files. This is a preview — files are returned but not written anywhere.

engram compile [targets...]

Arguments:

Argument	Description
`[targets...]`	One or more targets: `claude`, `cursor`, `copilot`, `windsurf`, `agents-md`. Defaults to all targets if omitted.

The command fetches all active documents, domains, and the routing config, then sends them to the compilation endpoint.

Examples:

# Compile all targets
engram compile

# Compile for Claude Code and Cursor only
engram compile claude cursor

Output:

Compiling...
  Targets: claude, cursor, copilot, windsurf, agents-md

  24 active documents

  claude: 13 file(s)
    .claude/CLAUDE.md
    .claude/docs/engram/api-conventions.md
    .claude/docs/engram/architecture-patterns.md
    ...

  cursor: 12 file(s)
    .cursor/rules/engram-api-conventions.mdc
    .cursor/rules/engram-architecture-patterns.mdc
    ...

Compilation complete.
Run `engram sync` to write files to your repo.

`engram sync`

Fetch compiled context from the server and write files to the current repository directory. This is the local equivalent of deploy — it writes Engram-managed files directly to disk instead of creating a PR.

engram sync [options]

Options:

Flag	Description
`-t, --target <target>`	Write files for a single target only (e.g., `claude`).
`-r, --role <role>`	Filter context by role before writing.
`-n, --dry-run`	Preview which files would be written without actually writing them.

Examples:

# Sync all targets to current repo
engram sync

# Sync only Claude Code files
engram sync --target claude

# Preview without writing
engram sync --dry-run

# Sync backend-specific context
engram sync --role backend

`engram deploy`

Compile guidelines and push them to all connected repositories via GitHub App PRs.

engram deploy [options]

Options:

Flag	Description
`--repos <ids...>`	Deploy to specific repositories only (by repo ID).
`--targets <targets...>`	Compile for specific targets only.

The command triggers an async deploy job, then polls for completion (up to 2 minutes). It displays the result for each repo: PR number, URL, and whether it was auto-merged.

Examples:

# Deploy to all repos with all targets
engram deploy

# Deploy to specific repos
engram deploy --repos repo_abc repo_def

# Deploy only Claude and Cursor targets
engram deploy --targets claude cursor

Output:

Triggering deploy...
Deploy job started: job_xyz789
Polling for completion...
Progress: 50%
Deploy completed successfully!
  + repo_abc: PR #42 (auto-merged)
    https://github.com/acme/backend/pull/42
  + repo_def: PR #18
    https://github.com/acme/frontend/pull/18
  ~ repo_ghi: skipped — no changes detected

Environment Variables

The CLI reads configuration from its config file (set via engram init), but the following environment variables can override config values:

Variable	Description
`ENGRAM_API_KEY`	API key. Overrides the key stored in config.
`ENGRAM_SERVER_URL`	Server URL. Overrides the URL stored in config.
`ENGRAM_WORKSPACE`	Workspace slug. Overrides the workspace stored in config.

These are useful in CI/CD pipelines where you don't want to run engram init interactively:

export ENGRAM_API_KEY=ek_abc123...
export ENGRAM_SERVER_URL=https://engram.example.com
export ENGRAM_WORKSPACE=acme
engram validate --wait --json

Common Workflows

CI: Validate Guidelines on Every PR

Add to your CI pipeline to catch guideline issues early:

engram validate --wait --json > validation.json
# Parse health_score from JSON, fail if below threshold

CI: Sync Context Files Into Repo

Keep Engram-managed files in sync without using the GitHub App:

engram sync --target claude
git add .claude/
git diff --cached --quiet || git commit -m "chore: update engram guidelines"

Agent Integration: Feed Context to Claude Code

In a CLAUDE.md file or agent startup script:

# Fetch role-specific context
engram context --role backend --target claude

Agent Integration: Semantic Search in Agentic Workflows

# Search for relevant guidelines before generating code
engram search "how to handle pagination in our API" --scope documents --limit 3 --json

Full Bootstrap (New Workspace)

engram init
engram sources add github --org acme-corp
engram sources add website https://www.acme.com
engram sources add notion
# Complete OAuth for Notion in the dashboard
engram sources sync
engram analyze
# Wait for analysis to complete, then:
engram analyze --status
engram topics list
engram topics confirm "API Conventions"
engram topics confirm "Brand Voice"
engram topics confirm "Design System"
engram generate "API Conventions"
engram generate "Brand Voice"
engram generate "Design System"
# Review and approve docs in the dashboard, then:
engram compile
engram deploy