The eklavya CLI

Use the CLI for installation, settings, diagnostics and memory outside a Claude Code conversation. Run a command with npx eklavya, or install it on your PATH:

npm install -g eklavya
eklavya doctor

On a terminal, command output is coloured: results green, warnings amber, failures red, paths and notes dimmed. Piped output stays plain, NO_COLOR turns colour off and FORCE_COLOR keeps it on in a pager. Output meant for scripts, such as --json, db-path and the path artifacts new prints, is never coloured.

Installation and maintenance

Command	Purpose and options
eklavya install	Installs the runtime, Claude Code plugin, database and two chat skills. Uses the defaults without asking questions; later runs preserve saved settings. --settings opens an optional settings walkthrough. --memory eklavya or --memory claude-mem chooses the recorder when Claude Mem is present. See Installing and Migration.
eklavya update	Checks npm and installs a newer release, then refreshes the plugin registration. Runs the normal background update in the foreground so errors are visible. Never downgrades.
eklavya uninstall [--purge]	Removes the installation and keeps your history unless --purge is passed. Reports any remaining project installation or git hook. See Uninstalling.
eklavya doctor	Checks installation and memory health, reports repairs and applies concept packs. See diagnostics below.
eklavya serve	Runs the MCP server over standard input/output. Claude Code starts this automatically.
eklavya db-path	Prints the active database path.
eklavya --version	Prints the installed version and exits (-v is the same).
eklavya telemetry [status|on|off|show]	The anonymous daily usage counts. status (the default) says whether they are sent and why; on and off set telemetry in your global config; show prints the exact next ping. See Usage analytics.
eklavya export-rules [--out <file>]	Exports the complete tutor text as a Markdown rules file, or prints it without --out. This exports instructions only; it does not install another editor’s hooks or the automatic learning loop.

install --auto is used internally by the updater: it skips the runtime installation step and interactive questions. Normal installs repair missing files without resetting history.

Settings and browsing

Command	Purpose and options
eklavya config get [key]	Prints effective settings and global/project file paths. With a dotted key such as quiz.enabled, prints only that value; an unknown key is an error. Warns about malformed files or global-only settings ignored in a project file.
eklavya config set <key> <value>	Sets one key globally. Add --project (legacy alias --repo) for this codebase; add --topic <topic> when setting focus learn with no topic already set. Refuses a value outside the key’s accepted range and writes nothing.
eklavya config unset <key>	Removes one key from your global file, so it falls back to the default. With --project, removes it from this codebase’s file, so your global setting applies again.
eklavya dashboard [--port <n>] [--no-open]	Opens the local dashboard, starting it in the background if it is not running. --no-open prints the URL without opening a browser. --port serves in the foreground on that port. Its Settings pages make the same changes as config set and config unset.
eklavya dashboard status / stop	Shows the background dashboard’s version, process id and database, or stops it. The next session starts it again unless dashboard_autostart is false.
eklavya feedback generate [--background]	Reviews one of your prompts from an earlier session, using what your later prompts had to add to show what it left out, if feedback.enabled, memory and providers.observer are all set and nothing is waiting. Prints one line: reviewed 1 prompt from <date>, nothing to review, a feedback item is waiting: acknowledge it first, needs memory, needs providers.observer or off. It prints couldn't review that session when the model’s answer was unusable (that session is not retried), and couldn't review right now: it will try again at a later start when the model is unavailable. --background prints nothing. generate exits 0 whatever happens; any other subcommand prints usage and exits 1. It reviews sessions of the project you run it in. Session start runs it for you, detached and at most every 30 minutes; the result is on the dashboard’s Feedback page.
eklavya statusline [--no-color]	Prints one line for a terminal status bar. See below.
eklavya artifacts <subcommand>	Creates, lists and opens saved pages. See below.

eklavya config set cadence end --project
eklavya config set focus learn --topic caching
eklavya config set memory.capture minimal
eklavya config unset cadence --project

Settings are backed up to config.json.eklavya-bak before a change. Unknown keys, values Eklavya would ignore (such as cadence bogus), malformed files, focus learn without a topic, and --project outside a git repository are rejected with a repair message. See Configuration for every key and default.

eklavya memory

Run project-specific commands from inside the checkout. Memory maintenance does not change quiz attempts, mastery or gates; move only re-files them under the new folder.

Subcommand	Purpose and options
status	Shows entries, pending evidence, queue status, provider configuration, worker processes and heartbeat, imported/unplaced history, dropped events, estimated reuse and explicit memory reads. Start here when memory seems empty.
search <query>	Finds titles and IDs. Options: --mode keyword|semantic|hybrid, --limit <n>, --all-projects.
timeline	Lists recent entries, newest first. Options: --limit <n>, --since <iso date>.
show <id>	Reads one entry and its raw evidence.
replay [--limit <n>]	Backfills this checkout’s Claude Code transcripts, including sessions before installation or missed by hooks.
process [--max <n>] [--no-resume]	Processes queued observations now. Normally resumes paused jobs; --no-resume leaves them paused.
stop	Cancels the recorded worker and its model call; unfinished work returns to the queue. Future session activity can start a worker again.
backlog	Lists unfinished jobs by project and status, plus Eklavya observer helper sessions in any state, marked as such.
backlog quarantine|discard|restore	Changes selected jobs. Requires --helpers, --project <key>, --session <id> or --batch <id>. Quarantine preserves jobs without processing; restore re-enables them; discard deletes unfinished jobs and their raw evidence, plus any helper sessions the selector matches, finished or not, with the memories they produced. Your own finished sessions are never selected.
prune	Applies this project’s memory.retention_days now, removing old summarised evidence, finished jobs, reuse receipts and memory read log rows. Keeps observations; does nothing when retention is unset.
move [<old> [<new>]]	Re-files the history of a moved or renamed checkout, including its answers, level, project settings and pages, under <new> (default: this checkout). With no path, lists folders that have history but no longer exist. Refuses an <old> that still exists without --force, because that is a separate checkout. Session start already does this by itself when it can tell which folder moved; see moved checkouts.
import <source.db>	Imports Claude Mem history. Options are below.
export <file> [--force]	Writes a private, versioned JSON memory backup. Refuses to replace an existing file without --force.
restore <file>	Adds missing memory from an export and rebuilds its search data. Repeating the restore adds no duplicates.
sync push|pull|status [--target <dir>]	Exchanges memory entries, tags, corrections and deletions through a shared folder. Requires sync.enabled and a target. A record that arrives late is still applied; pull and status report what other devices still owe. Learning history, raw evidence and receipts do not sync.

If processing paused because of login, quota or a missing claude command, fix that problem and run eklavya memory process to resume now. Otherwise, automatic seams check at most every 30 minutes and resume once the login is back or an hour has passed since a usage limit; meanwhile they write local observations for waiting work. See when the model is unavailable. Only one worker runs at a time; it handles up to four batches before handing remaining ready jobs to a fresh worker. To keep model processing off, clear providers.observer.

eklavya memory search "refresh cookie"
eklavya memory status
eklavya memory export ~/eklavya-memory-backup.json

eklavya memory status starts with a health: line, ok, warn or stalled, followed by one line per reason. eklavya doctor shows the same verdict and exits nonzero when it is stalled. The checks are listed under the memory health verdict.

A memory export contains entries, tags, evidence and its links, and reuse receipts. It is not a backup of quiz history or a full database rollback. Restore is additive: it does not remove existing entries or undo later edits. For a complete backup, see Your data. A restore from an unsupported newer format stops with a version error.

Importing Claude Mem history

eklavya memory import ~/.claude-mem/claude-mem.db --dry-run

Option	Effect
--dry-run	Reads the source without writing; reports schema, row counts, project names and field mapping, including dropped or unknown fields.
--verify	Checks every source row by ID and reports project placement. Writes nothing; exits 1 if anything is missing.
--resume	Reuses the snapshot from an interrupted import.
--map <name>=<path>	Assigns a named source project to a checkout. Overrides transcript-based mapping.
--map-here <name>	Assigns it to the checkout you are in.

Imports preserve original dates, do not duplicate rows, and never count imported concepts as assessed knowledge. Re-running with a better map moves unplaced rows to their checkout. Unplaced history remains searchable with --all-projects. Unsupported newer source schemas are rejected. See Moving from Claude Mem for the installer flow and rollback.

eklavya artifacts

Subcommand	Purpose and options
new <title>	Starts an HTML page from the template and prints its path. Options: --description <text>, --kind artifact|explainer (default artifact), --concept <slug>, --attempt <attempt_id> (the missed answer an explainer is for, a positive integer from record_attempt), --open.
list [--json] [--here]	Lists pages newest first. --here selects this project; --json includes the IDs used by the dashboard.
open <path|id>	Opens a page by path or an ID from list --json, and prints what it opened. A page in the artifacts folder opens as a tab in the dashboard’s viewer, starting the background dashboard if needed; it opens the file instead when the file is outside that folder, dashboard_autostart is off or no background dashboard for this database answers, for example when another program holds the port. new --open follows the same rule.

Files live under ~/.eklavya/artifacts/<project>/, named with the local date and title. Repeated titles receive a suffix instead of overwriting a file. A worktree uses its main checkout’s folder; outside git, the current directory identifies the project. See the artifacts skill to have Claude write the content.

eklavya statusline

Prints your focus, cadence and current level, with enforced when the commit gate is enabled:

[EKLAVYA concept · as-you-go · easy]

The installer adds this only if Claude Code’s status-line slot is empty. To configure it yourself:

~/.claude/settings.json

{
  "statusLine": {
    "type": "command",
    "command": "eklavya statusline"
  }
}

If you already have a status-line script, append the output of eklavya statusline there. It exits successfully with one line or no output. Uninstall preserves a composed status line.

It stays silent when questions are disabled, quiet is true, or the session is silenced. Use --no-color or NO_COLOR for plain text. It shows the project level rather than an individual question’s tier; past tiers are in the dashboard. Claude Desktop has no terminal status bar, so its questions use an [Eklavya] signature instead.

What doctor looks like

Run this when Eklavya is unexpectedly quiet:

eklavya doctor

The report checks the runtime, SQLite driver, plugin registration, both chat skills, update status, usage ping, version alignment, configuration, database, concept packs, project level, memory queue and gate dependencies. Marks distinguish healthy (▣), warning (!), skipped (◌) and failed (▤) checks, including without colour.

Finding	Repair
Missing runtime, incompatible SQLite driver, missing registration or skill	Run eklavya install. A conflicting user-owned skill must first be moved by you.
Failed automatic update	Run eklavya update; inspect ~/.eklavya/update.log.
Plugin/runtime versions differ	A behind runtime normally catches up next session; an older plugin needs updating through Claude Code’s plugin controls.
Malformed configuration	Fix the named file; the installer will not overwrite it.
Broken concept pack	Fix that pack; the rest still loads.
Installed terminal gate lacks jq or sqlite3	Install the missing dependency. Until then, that gate lets commits through.
Memory health is stalled	Read the reason under it; work is being captured but not summarised. Fix the cause it names (often login or quota), then eklavya memory process.
Paused memory queue	Fix the reported login, quota or command problem. It resumes by itself within 30 minutes, or run eklavya memory process to resume now.

doctor exits nonzero for failed checks and names the repair. A broken pack is reported without failing the run. It also opens/initialises the database and applies packs, so it is a diagnostic command with those limited writes. Hooks fail open to protect your session; this report distinguishes a quiet session from a broken installation.