cli

glean-cli

Single binary glean: the workspace default-run target for the Glean local-first knowledge engine.

Business logic (daemon loop, MCP JSON-RPC routing, config editor, status) lives in glean-host. This crate is a thin shell: Clap routing, stdio MCP framing, tracing-subscriber, and human-readable output.

See also glean-core (engine) and the repository root README.md.

MCP debugging: stdio lines must be JSON-RPC (examples in the root README). For iteration, run cargo test -p glean-host mcp::router first; use cargo test -p glean-cli --test mcp_subprocess for a real glean binary + temp storage smoke test.

CLI vs host vs core

Layer	Crate	Responsibility
Shell	glean-cli	main, Clap, stdin/stdout MCP loop, glean logs, logging install
Host	glean-host	daemon, mcp, config, status, workspace, parsers
Engine	glean-core	GleanEngine, LanceDB, pipeline, config merge (read)

Tauri or other desktops should depend on glean-core + glean-host, not on glean-cli.

Commands

Command	Role
glean daemon	Watch the workspace; sync into <workspace>/.glean/ (SQLite + Lance). Config from $GLEAN_STORAGE_ROOT/config.toml.
glean mcp	Short-lived JSON-RPC 2.0 MCP server on stdin/stdout. Do not write logs to stdout.
glean logs	Tail rolling logs under {GLEAN_STORAGE_ROOT}/logs/.
glean config	list / init / set — global $GLEAN_STORAGE_ROOT/config.toml only.
glean status	Version, global storage, workspace index paths, legacy layout warnings.
glean index	Enqueue walk when daemon is running (sidecar), or one-shot drain when daemon is stopped. Optional --wait.

Run glean --help and glean <command> --help for full Clap help.

Hidden paths: by default, any workspace-relative path segment starting with . is skipped for indexing and browse/search APIs (no opt-in flag yet).

Binary extensions: archives, disk images, installers, and similar suffixes (e.g. zip, dmg, pkg, jar) are skipped entirely at discover time — they never enter fs_entries.

Indexing scheduler (glean daemon)

When [indexing].scheduler_enabled is true (default), the daemon adjusts per-tick budgets for scan slices, FTS ingest, and vector backfill from platform signals (macOS ioreg idle + battery, Windows GetLastInputInfo + power status). MCP search_semantic appends path keys to metadata/search_boost.jsonl; only the daemon drains that queue into SQLite vector_priority_boost.

Key TOML keys (also via glean config set indexing.<key> <value>): ingest_max_paths_per_tick, ingest_max_ms_per_tick, backfill_max_files_idle, backfill_max_files_active, idle_threshold_secs, defer_initial_backfill_until_idle, scan_budget_entries, scan_budget_ms, embedder_idle_secs, auto_index_git_repos.

Git repository discovery

When [indexing].auto_index_git_repos is false (default), walk skips Git repository roots (directories containing .git), registers them in SQLite discovered_projects, and writes manual jobs to metadata/index_requests.jsonl. The daemon drains requests and indexes each repo at <repo>/.glean/ with highest scheduler priority.

Environment

Variable	Used by	Meaning
GLEAN_STORAGE_ROOT	daemon, MCP, logs, config, rerank cache	Global home (default ~/.glean). Not the per-project index.
GLEAN_WORKSPACE_ROOT	daemon (--workspace alternative), MCP	Project root; index at <workspace>/.glean/.
GLEAN_LOG	all	tracing filter; overrides [log].level when set. For indexing debug, tail ~/.glean/logs/daemon.log.* or set GLEAN_LOG=glean_core::pipeline=info,glean_host::daemon=info.

Versioning

pnpm tag (repo root) bumps Desktop and CLI together: apps/desktop/package.json, Tauri config, apps/desktop/src-tauri/Cargo.toml, apps/cli/Cargo.toml, apps/cli/package.json, and Cargo.lock. glean --version reads the CLI crate version via glean_core::VERSION.

GitHub Releases attach standalone CLI assets (glean-aarch64-apple-darwin, glean-x86_64-pc-windows-msvc.exe) alongside Desktop installers on the same tag.

Build

From the repository root (workspace):

cargo build -p glean-cli --release

Binary: target/release/glean.

Prerequisites match the workspace: Rust stable and protoc (see root README.md).

npm / pnpm shim (bin/glean.cjs)

package.json exposes a bin named glean that runs bin/glean.cjs. That file is a small Node launcher, not the Rust executable: it finds the repo workspace root and spawns:

cargo run -q --manifest-path <repo-root>/Cargo.toml -p glean-cli -- <args>

Use it when the package is linked in a JS monorepo (e.g. pnpm exec glean …). Editors and production setups should still point at the cargo build --release binary when you want a fixed path and no compile step on each invocation.

Cargo feature: enterprise

Forwards to glean-host/enterprise, which augments the parser registry via glean-enterprise:

cargo build -p glean-cli --features enterprise --release

Default builds omit it; behavior matches community parsers only.

Library

glean-cli is also a library (glean_cli) for integration tests and the main binary entrypoint.

License

Apache-2.0, same as the rest of the workspace.