CLI Reference

All commands accept --help for full flag documentation.

Global flag: --log <level> (default: warn). Set LIP_LOG=debug for verbose output.

lip daemon

Start the LIP daemon — persistent query graph server with per-file filesystem watcher.

lip daemon [OPTIONS]

The daemon replays its journal on startup — the graph is warm immediately without re-indexing.

Embedding environment variables (optional):

LIP_EMBEDDING_URL=http://localhost:11434/v1/embeddings \
LIP_EMBEDDING_MODEL=nomic-embed-text \
lip daemon --socket /tmp/lip.sock

lip index

Index a directory with the Tier 1 tree-sitter indexer and emit deltas.

lip index [OPTIONS] [PATH]

# Index current directory, human-readable
lip index .

# Index and emit JSON (pipe to push)
lip index ./src --json | lip push --registry https://registry.lip.dev

lip query

Query a running daemon. All subcommands accept --socket <path>.

lip query --socket /tmp/lip.sock <subcommand>

lip query definition

Find the definition of the symbol at a position.

lip query definition <uri> <line> <col>

• uri: file URI or LIP symbol URI
• line, col: 0-based, UTF-8 byte offsets

lip query definition file:///src/auth.rs 42 10

lip query references

Find all references to a symbol across the workspace.

lip query references <symbol_uri> [--limit <n>]

lip query references "lip://local/src/auth.rs#AuthService.verifyToken"

lip query hover

Get type signature and documentation for a symbol at a position.

lip query hover <uri> <line> <col>

lip query blast-radius

Compute the blast radius of a symbol — direct and transitive dependents.

lip query blast-radius <symbol_uri>

lip query blast-radius "lip://local/src/auth.rs#AuthService"
# direct dependents:     3
# transitive dependents: 12
# affected files:
#   file:///src/middleware/auth_guard.rs
#   file:///src/handlers/login.rs
#   ...

lip query symbols

Search workspace symbols by name.

lip query symbols <query> [--limit <n>]

lip query symbols "verify"        # fuzzy match
lip query symbols "AuthService"   # exact prefix match

lip query dead-symbols

Find symbols defined but never referenced.

lip query dead-symbols [--limit <n>]

lip query similar

Trigram fuzzy-search across all symbol names and documentation. Useful when you don’t know the exact name.

lip query similar <query> [--limit <n>]

lip query similar "verif"       # matches verifyToken, verifySession, …
lip query similar "auth" --limit 5

Results are ranked by Jaccard trigram score (score ≥ 0.2 shown).

lip query stale-files

Merkle sync probe — given a JSON array of [uri, sha256_hex] pairs, returns the URIs that the daemon hasn’t seen or whose content hash differs.

lip query stale-files [FILE]

# From stdin
echo '[["file:///src/main.rs","abc123..."]]' | lip query stale-files

# From file
lip query stale-files ./hashes.json

lip query embedding-batch

Compute and cache dense embedding vectors for one or more file URIs. Requires LIP_EMBEDDING_URL to be set.

lip query embedding-batch <uri> [<uri>...] [--model <model>]

lip query embedding-batch file:///src/auth.rs file:///src/session.rs
lip query embedding-batch file:///src/auth.rs --model text-embedding-3-large

Already-cached embeddings are returned without a network call. A new file upsert invalidates the cached vector.

lip query nearest

Find the top_k files most semantically similar to a given file, ranked by cosine similarity. The file must have a cached embedding.

lip query nearest <uri> [--top-k <n>]

lip query nearest file:///src/auth.rs
lip query nearest file:///src/auth.rs --top-k 10

Output:

score=0.9412  file:///src/session.rs
score=0.8871  file:///src/middleware/auth_guard.rs
...

lip query nearest-by-text

Find the top_k files most semantically similar to a free-text query. The daemon embeds the text on the fly.

lip query nearest-by-text <text> [--top-k <n>] [--model <model>]

lip query nearest-by-text "authentication token validation"
lip query nearest-by-text "payment processing fraud detection" --top-k 10

lip query index-status

Report overall daemon health: indexed file count, pending embedding count, last upsert timestamp, and configured embedding model.

lip query index-status

Output:

indexed=142  pending_embeddings=38  last_updated=1744400123000ms  embedding_model=nomic-embed-text

lip query file-status

Report the indexing status of a single file.

lip query file-status <uri>

lip query file-status file:///src/auth.rs
# file:///src/auth.rs  indexed=true  has_embedding=true  age=42s

age is seconds since the file was last indexed.

lip query batch

Execute multiple queries in a single round-trip. Reads a JSON array of query objects from a file or stdin.

lip query batch [FILE]

lip query batch <<'EOF'
[
  {"type":"query_blast_radius","symbol_uri":"lip://local/src/auth.rs#AuthService"},
  {"type":"query_references",  "symbol_uri":"lip://local/src/auth.rs#AuthService","limit":50},
  {"type":"annotation_get",    "symbol_uri":"lip://local/src/auth.rs#AuthService","key":"lip:fragile"}
]
EOF

Output is a BatchResult with one entry per input query.

lip query reindex-files

Force a targeted re-index of specific file URIs from disk, bypassing the directory scan. Useful after out-of-band changes (selective git checkout, generated files, etc.).

lip query reindex-files <uri> [<uri>...]

lip query reindex-files file:///src/auth.rs file:///src/session.rs

Each URI is read from disk, its language detected from the extension, and upsert_file is called. Returns a DeltaAck.

lip query similarity

Pairwise cosine similarity of two stored embeddings. Returns a score in [0.0, 1.0], or null when either URI has no cached embedding — call embedding-batch first.

lip query similarity <uri-a> <uri-b>

lip query similarity file:///src/auth.rs file:///src/session.rs
# score=0.9214

lip query similarity lip://local/src/auth.rs#verifyToken lip://local/src/session.rs#validateSession
# score=0.8847

Both lip:// (symbol) and file:// (file) URIs are accepted.

lip query query-expansion

Expand a short query string into related symbol names by finding the nearest symbols in the embedding store. Designed for use before lip query symbols to discover related terms.

lip query query-expansion <text> [--top-k <n>] [--model <model>]

lip query query-expansion "token validation" --top-k 5
# verifyToken
# validateSession
# checkJwt
# parseBearer
# refreshToken

Requires LIP_EMBEDDING_URL. The daemon embeds text on the fly, searches the symbol embedding store, and returns display names in descending similarity order.

lip query cluster

Group a list of file or symbol URIs into clusters based on embedding proximity.

lip query cluster [--radius <float>] <uri> [<uri>...]

lip query cluster --radius 0.85 \
  file:///src/auth.rs \
  file:///src/session.rs \
  file:///src/payments.rs \
  file:///src/invoices.rs
# Group 1: file:///src/auth.rs  file:///src/session.rs
# Group 2: file:///src/payments.rs  file:///src/invoices.rs

--radius is the cosine-similarity threshold (default: 0.8). Two URIs land in the same group when their similarity is ≥ the radius. URIs without a cached embedding are silently excluded.

lip query export-embeddings

Return the raw stored embedding vectors for a list of URIs as JSON. Useful for external pipelines (re-ranking, custom clustering, visualization).

lip query export-embeddings <uri> [<uri>...] [--output <file>]

lip query export-embeddings file:///src/auth.rs file:///src/session.rs
# {"file:///src/auth.rs":[0.021,-0.044,...],"file:///src/session.rs":[0.019,-0.051,...]}

lip query export-embeddings file:///src/auth.rs --output vectors.json

URIs with no cached embedding are omitted from the output map.

lip lsp

Start a standard LSP server that bridges to the LIP daemon.

lip lsp [--socket <path>]

Reads from stdin, writes to stdout (stdio transport). Configure your editor to launch this as a language server — no custom plugin needed.

Supported LSP methods: textDocument/definition, textDocument/references, textDocument/hover, workspace/symbol, textDocument/documentSymbol.

lip mcp

Start a Model Context Protocol server backed by the LIP daemon.

lip mcp [--socket <path>]

Reads JSON-RPC 2.0 from stdin, writes to stdout (stdio transport).

{
  "mcpServers": {
    "lip": { "command": "lip", "args": ["mcp"] }
  }
}

See MCP Integration for the full tool reference.

lip import

Import an existing SCIP index file, upgrading all symbols to Tier 2 confidence (score 90).

lip import --from-scip <path.scip> [--socket <path>]

lip import --from-scip ./index.scip

Use this to bootstrap LIP on a repo that already has a SCIP pipeline. After import, LIP maintains freshness incrementally — SCIP never needs to run again unless you want a full Tier 2 refresh.

lip export

Export the current daemon state as a SCIP index file.

lip export --to-scip <output.scip> [--socket <path>]

lip fetch

Download a dependency slice from the registry.

lip fetch <sha256-hash> [OPTIONS]

# Download and print JSON
lip fetch abc123def456…

# Download and immediately mount into the running daemon
lip fetch abc123def456… --mount

lip push

Publish a dependency slice to the registry.

lip push [slice.json] [--registry <url>] [--cache-dir <path>]

Reads from file or stdin. Prints the content hash on success.

lip push ./my-package.json --registry https://registry.lip.dev

# From stdin (pipe from index)
lip index ./src --json | lip push

lip slice

Build pre-computed dependency slices from your package manager lockfiles.

lip slice [OPTIONS]

All symbols in a slice are stamped at Tier 3 confidence (score=100).

# Build and share with team
lip slice --cargo --push --registry https://registry.lip.dev

# Monorepo with multiple package managers
lip slice --cargo --npm --pub

See Registry & Slices.

lip annotate

Read and write persistent key/value annotations on symbols. Annotations survive daemon restarts, file changes, and re-indexes — stored in the WAL journal.

lip annotate [--socket <path>] <subcommand>

lip annotate set

lip annotate set <symbol_uri> <key> <value> [--author <id>]

lip annotate set "lip://local/src/payments.rs#processCharge" \
  "lip:fragile" \
  "Uses deprecated Stripe v1 API — do not refactor without platform review" \
  --author "human:alice"

lip annotate get

lip annotate get <symbol_uri> <key>

lip annotate list

List all annotations on a symbol.

lip annotate list <symbol_uri>

lip annotate search

Search annotations workspace-wide by key prefix. Pass an empty string to list all annotations.

lip annotate search <key_prefix>

lip annotate search "lip:fragile"     # all fragile symbols
lip annotate search "agent:"          # all agent annotations
lip annotate search ""                # every annotation in the workspace