CLI Reference

Shaktiman ships two binaries:

• shaktiman — direct CLI over the index. Every MCP tool is also available as a CLI subcommand that reads the SQLite index without involving the daemon.
• shaktimand — the MCP stdio server. Launched by your MCP client (e.g. Claude Code); you rarely invoke it by hand.

Persistent flags (shaktiman)

--format <json|text>   Output format (default: json)

Every subcommand honors --format. Set --format text for human-readable output (matches the format the MCP server returns); leave the default json when piping to jq or other tools.

Management commands

shaktiman init <project-root>

Initialize a .shaktiman/ config directory. Writes a sample shaktiman.toml if one doesn't already exist; leaves existing config untouched.

shaktiman init /path/to/project

shaktiman index <project-root>

Cold-index a project directory. Refuses to run if a shaktimand daemon is already holding the project lock (the daemon handles indexing automatically).

Flag	Default	Purpose
--embed	false	Also generate embeddings after indexing (requires Ollama).
--vector <backend>	from config	Vector backend: brute_force, hnsw, qdrant, pgvector.
--db <backend>	from config	Metadata backend: sqlite, postgres.
--postgres-url <url>	from config / env	Override the Postgres connection string.
--qdrant-url <url>	from config	Override the Qdrant URL.

Progress is emitted on stdout (Indexing: N/M files (X%) / Embedding: N/M chunks (X%)). On a TTY the lines redraw in place; on a pipe they're emitted every 10 %.

Ctrl-C during embedding flushes progress to disk; the next run resumes from where it left off.

shaktiman reindex <project-root>

Purge all indexed data and reindex from scratch. Keeps configuration. Destructive — prompts for confirmation on TTYs.

All flags from index, plus:

Flag	Default	Purpose
--force	false	Skip the confirmation prompt (required on non-interactive terminals).

shaktiman status <project-root>

Print a minimal index summary (file / chunk / symbol counts + parse errors + per-language file counts). Reads the index directly; no daemon required.

Query commands

Each query command wraps the MCP tool of the same name. Output is JSON by default; use --format text for a human-readable rendering.

shaktiman search <query>

See search MCP tool for result semantics.

Flag	Default	Purpose
--root <path>	.	Project root to read the index from.
--max <int>	from [search].max_results	Maximum results.
--mode <locate|full>	from [search].default_mode	Result mode.
--min-score <float>	from [search].min_score	Minimum relevance score.
--explain	false	Include per-signal score breakdown (text format only).
--path <prefix>	—	Filter results to a file or directory prefix.
--scope <impl|test|all>	impl	Result scope.

shaktiman context <query>

See context MCP tool.

Flag	Default	Purpose
--root <path>	.	Project root.
--budget <int>	from [context].budget_tokens	Token budget (256–32768).
--scope <impl|test|all>	impl	Result scope.

shaktiman symbols <name>

See symbols MCP tool.

Flag	Default	Purpose
--root <path>	.	Project root.
--kind <string>	—	Filter by symbol kind (function, class, method, type, interface, variable).
--scope <impl|test|all>	impl	Result scope.

shaktiman deps <symbol>

See dependencies MCP tool. Note the CLI name is deps, not dependencies.

Flag	Default	Purpose
--root <path>	.	Project root.
--direction <callers|callees|both>	both	Traversal direction.
--depth <int>	2	BFS depth (1–5).
--scope <impl|test|all>	impl	Result scope.

shaktiman diff

See diff MCP tool.

Flag	Default	Purpose
--root <path>	.	Project root.
--since <duration>	24h	Time window. Go duration syntax — no "d" or "w" units. Capped at 720h internally.
--limit <int>	50	Maximum diffs. Out-of-range values (<1 or >500) silently reset to the default.
--scope <impl|test|all>	impl	Result scope.

shaktiman enrichment-status

See enrichment_status MCP tool.

Flag	Default	Purpose
--root <path>	.	Project root.

shaktiman summary

See summary MCP tool.

Flag	Default	Purpose
--root <path>	.	Project root.

shaktiman stats

Query the running daemon's in-memory observability counters over its Unix socket and print a sorted human summary. Requires the daemon to be running for that project; reports a clear hint when the socket is unavailable.

shaktiman stats --root /path/to/project

Flag	Default	Purpose
--root <path>	.	Project root.
--json	false	Force JSON output regardless of --format.
--dial-timeout <duration>	2s	Socket dial timeout.

Counters surfaced today:

• daemon.lock.acquired / daemon.lock.contended — once per leader/proxy startup.
• daemon.promotion.attempt / daemon.promotion.failure — incremented by a proxy when its leader exits and it re-execs.
• mcp.tool_call.<tool>.count / .error_count — per-tool call totals.
• vector.embed.rejected.{zero,nan,inf,empty,dim_mismatch} — silent embed-quality regression signals from sanitizeEmbeddings.

Histograms (count, mean, p50, p95, p99, min, max):

• mcp.tool_call.<tool>.latency_ms
• mcp.tool_call.<tool>.response_bytes

The registry is in-memory and resets on daemon restart. There is no disk rotation or Prometheus exporter today; both are tracked as future phases in docs/planning/11-critique-remediation-plan.md.

shaktimand (MCP daemon)

shaktimand [flags] <project-root>

Takes the project root as its sole positional argument. The daemon:

1. Canonicalizes the project root path (symlinks + relative → absolute) so two daemons can't race by addressing the same directory differently.
2. Creates .shaktiman/ if missing and opens shaktimand.log for structured logs (stdout is reserved for the MCP protocol, stderr for startup errors only).
3. Acquires a flock on .shaktiman/daemon.pid. If the lock is taken, enters proxy mode — forwarding MCP traffic to the leader via /tmp/shaktiman-<hash>.sock — and never rotates the shared log.
4. If it got the lock, loads the TOML config, validates the backend combination (see Backends), opens the socket for future proxies, and serves MCP over stdio.

shaktimand is not normally run by hand. Wire it via your MCP client's configuration (for Claude Code, see Claude Code Setup).

Flags

Flag	Default	Purpose
--help	—	Print usage and exit.
--version	—	Print binary version (with VCS revision when built from a checkout) and exit.
--log-level <debug|info|warn|error>	info	slog level. Falls back to $SHAKTIMAN_LOG_LEVEL if the flag is unset; unknown values log a warning to shaktimand.log and continue at info.
--pprof-addr <host:port>	—	If set, serves net/http/pprof on this address. Disabled when empty. Bind to a loopback address (e.g. 127.0.0.1:6060) unless you explicitly intend external access.

Startup banner

On startup the leader writes one structured slog line at info level summarizing version, VCS revision (with a -dirty suffix when the working tree was modified at build time), Go runtime, pid, project root, db backend, vector backend, embedding config, socket path, and --pprof-addr. Use this line as the anchor when scanning log archives during a post-mortem. Proxy-mode processes log a separate entering proxy mode line instead.

Signals

shaktimand ignores SIGPIPE. The daemon writes to long-lived pipes (stdin/stdout to the MCP client, the proxy socket); a benign reader disconnect would otherwise terminate the process and abort indexing. SIGINT and SIGTERM trigger graceful shutdown.

Endpoints on the Unix socket

Two HTTP endpoints share /tmp/shaktiman-<hash>.sock:

Path	Purpose
/mcp	Streamable MCP HTTP server, used by proxy clients to forward JSON-RPC.
/metrics	JSON snapshot of the in-memory observability registry. Consumed by shaktiman stats.

The socket is local-only by virtue of being a Unix domain socket; no auth is enforced. Do not expose either endpoint over TCP.

Source of truth

• cmd/shaktiman/main.go — init, index, reindex, status.
• cmd/shaktiman/query.go — search, context, symbols, deps, diff, enrichment-status, summary.
• cmd/shaktiman/stats.go — stats.
• cmd/shaktimand/main.go — daemon lifecycle and leader/proxy dispatch.