lantern-ops

name

lantern-ops

description

Operate Lantern data through the `lantern-cli` CLI — read, write, delete, scan, count, bulk-load, back up/restore, and graph-walk vertices and edges from the command line. Use whenever the request involves manipulating data in a running Lantern server (get/put/delete a vertex or edge, prefix scan or count, bulk NDJSON load, whole-graph dump/restore backup, prefix delete, or a bfs/pagerank/community graph walk), or driving Lantern from an interactive/agentic system. Do NOT use this skill for editing Lantern's own Go source, regenerating protobuf/wire code, server deployment/IaC, or the MCP working-context tools.

Lantern Ops — CLI command reference

This skill is the canonical reference for operating data in a running Lantern server through the official lantern-cli CLI. Read it before issuing any data command so the arguments, flags, output shape, and exit codes are correct without reading server source.

Lantern is an in-memory graph KVS ("key-vertex-store"). Every vertex (a keyed, typed value) and every edge (a directed, weighted tail -> head pair) carries a TTL and decays on its own. The CLI wraps every server RPC as a scriptable subcommand plus an interactive REPL.

Invoking the CLI

On macOS the lowest-friction path is the Homebrew cask — it installs a released, prebuilt lantern-cli binary with no Go toolchain or repo checkout required (first choice):

brew tap anaregdesign/tap
brew install --cask lantern-cli    # installs the `lantern-cli` binary

On Linux/Windows, grab the lantern-cli binary attached to any GitHub Release. The Go-toolchain / in-repo routes below are the build-from-source fallback.

From inside this repo (no install, but needs the Go toolchain):

go run ./cli <args>                 # recompiles each call; fine for one-offs

Build once, then reuse the binary (preferred for repeated calls from a checkout):

go build -o lantern-cli ./cli
./lantern-cli <args>

The Homebrew/release binary and the in-repo build above are all named lantern-cli. All examples below use lantern-cli <args> — substitute go run ./cli <args> or ./lantern-cli <args> as appropriate.

Default target is http://localhost:6380 over plaintext h2c, which matches the primary replica of the deploy/compose stack (replicas are exposed on host ports 6380, 6381, 6382). Override with the global flags below.

Discovering help

The CLI's built-in help is intentionally long-form and example-rich because it is meant to be driven by both humans and agents. Treat --help as the authoritative, version-accurate source of truth — if this skill and the CLI's own help ever disagree, the help output wins (it is generated from the running binary). When unsure about a flag, default, or output shape, ask the binary before guessing.

lantern-cli --help              # top-level: command layout, global flags, exit codes
lantern-cli <verb> --help       # a verb's grammar + examples, e.g. lantern-cli put --help
lantern-cli help [verb]     # same content via cobra's `help` subcommand
lantern-cli <verb> -h           # `-h` is the short alias for `--help`

Examples worth reading before first use:

lantern-cli put --help               # vertex/edge writes: value typing (type=) + ttl_seconds
lantern-cli add --help               # additive vs idempotent edge write semantics
lantern-cli bfs --help               # breadth-first family knobs: step/fan-out + reduction/objective/weighting
lantern-cli pagerank --help          # Personalized PageRank knobs: top-n + restart-prob/epsilon
lantern-cli community --help         # local-community knobs: max-size + reduction/objective/weighting
lantern-cli delete-prefix --help     # the destructive-delete safety gate

Inside the interactive prompt, type help to print the per-verb grammar into the scrollback; lantern-cli repl --help documents the REPL grammar, quoting, and case rules. Shell completion install instructions: lantern-cli completion --help.

Global connection flags

These apply to every subcommand and go before the subcommand (e.g. lantern-cli --tls -H host get vertex k):

Flag	Default	Meaning
-H, --host	localhost	server hostname
-p, --port	6380	server port
--address	—	full host:port; overrides --host/--port
--timeout	5s	per-RPC deadline; 0 disables
--tls	off	dial with TLS instead of plaintext (flips http→https)
--tls-ca	—	PEM bundle to verify the server cert
--tls-cert / --tls-key	—	client cert + key for mTLS (must be paired)
--tls-server-name	—	override the SNI / verification hostname
--insecure-skip-verify	off	skip server cert verification (dev only)
--compression	none	per-call compressor: none or gzip
--chunk-size	1000	batch chunk size for multi-key write/delete

Supplying any of --tls-ca, --tls-cert also implies TLS (https).

Core concepts (read before writing)

• Value typing. put vertex parses the raw arg and, by default, auto-types it (auto): auto tries int → float → bool → RFC3339 datetime → else string. Force the type when the value is ambiguous by appending a type= token (e.g. keep a leading zero with type=string). Supported types: auto|string|int|float|bool|datetime|duration|json. JSON objects and arrays are re-encoded as a compact JSON string on the wire (Lantern has no nested value variant); scalars pass through as their natural type.
• TTL semantics. The optional trailing ttl_seconds is an integer number of seconds, relative to the server's "now" at receipt (30, 300, 3600, 86400). Omit it or pass 0 to store permanently (no decay). Expired entries are reaped lazily.
• Edge add vs put are NOT equivalent.
  • add (AddEdge) is additive — repeated calls sum the weight on the same (tail, head). Not idempotent; excluded from client retry (a retry would double-count). Use for streaming counts/scores/interaction signal.
  • put (PutEdge) replaces the weight wholesale. Idempotent; retried on transient errors. Use when weight is a measured property (similarity, distance, capacity).
• Implicit endpoint upsert. Both edge write verbs materialise the tail and head vertices (with empty values) at the same TTL if they don't exist.
• Lazy edge cleanup. Deleting a vertex does not eagerly delete incident edges — they decay with their own TTL. A GetEdge right after a vertex delete may still briefly return the edge.
• Output & exit codes. Read commands print JSON on stdout; write commands print a single OK line. Errors go to stderr. Exit codes: 0 success, 1 local error (bad args, parse, file I/O), 2 RPC error returned by the server (NotFound, InvalidArgument, …).

Vertex commands

get vertex <key>

Fetch one vertex. Prints a JSON object {key, type, value, expiration}. NotFound (exit 2) when the key is absent or expired.

lantern-cli get vertex alice
lantern-cli get vertex alice | jq .value

put vertex <key> <value> [ttl_seconds] [type=...]

Upsert one vertex. Optional trailing ttl_seconds (integer; default permanent) and a type=<type> token (default auto); the two may appear in either order. Prints OK.

lantern-cli put vertex alice "Alice Smith"                    # string (auto)
lantern-cli put vertex count 42                                # int (auto)
lantern-cli put vertex price 19.99                             # float (auto)
lantern-cli put vertex alice '{"age":30}' 3600 type=json       # JSON value, 1h TTL
lantern-cli put vertex zipcode "01234" type=string             # keep leading zero

delete vertex <key> [<key>...]

Delete one or more vertices. One key → DeleteVertex; multiple keys → batch DeleteVertices (chunked at --chunk-size). Idempotent.

• Single: prints OK existed=true|false.
• Batch: prints OK <n> (number that actually existed and were removed).

lantern-cli delete vertex alice                 # single
lantern-cli delete vertex alice bob carol       # batch
cat keys.txt | xargs lantern-cli delete vertex  # batch from file

scan vertices <prefix> [limit] [all=true]

Enumerate live vertices whose key begins with <prefix> and print them as an indented JSON array on stdout. The optional positional <limit> caps the page size; all=true iterates every page through the SDK helper and concatenates the result into one array. Without all=true a single bounded page is returned (paging is handled internally — pass all=true for a full snapshot rather than resuming by hand).

lantern-cli scan vertices users/
lantern-cli scan vertices users/ all=true > snapshot.json
lantern-cli scan vertices users/ 50                  # first page, up to 50

count vertices <prefix>

Print the number of keys in the prefix index as a single integer. Caveat: counted from the radix index, not cross-checked for liveness, so it may include expired-but-not-yet-reaped keys. For a strictly-live count use lantern-cli scan vertices <prefix> all=true | jq 'length'.

lantern-cli count vertices users/

keys <prefix> [limit]

List vertex keys under <prefix>, one per line on stdout — the Redis-familiar, keys-only counterpart to scan vertices (no values, pipe-friendly). Lantern is prefix-indexed, so the argument is a key prefix, not a glob (no trailing *). A prefix is required (the server rejects an empty prefix); the optional <limit> caps the page (mirrors scan vertices). This is a verb-first one-liner — the same grammar as the lantern-cli repl prompt, backed by the wire-efficient ScanVertexKeys RPC.

lantern-cli keys users/
lantern-cli keys users/ 100
lantern-cli keys users/ | xargs -n1 lantern-cli get vertex   # hydrate values

search <query> — content relevance (BM25)

Full-text search over vertex content (key + value), ranked by BM25 — the content counterpart to scan vertices' lexicographic key walk. Hits print one per line as <key> and <score> (tab-separated), most relevant first. Requires the server's search index (LANTERN_SEARCH_ENABLED, on by default; off ⇒ FAILED_PRECONDITION).

The default is an OR-union over the query words. Flags tune relevance (#892):

flag	meaning
--mode any|all|min-should	term combination: OR (default), AND, or minimum-should-match
--min-should <n>	with --mode min-should, require at least n distinct query words
--phrase	require the words adjacent, in order (highest precision)
--fuzziness 1|2	also match terms within that edit distance (typo tolerance)
--prefix-terms	also match terms that extend a query word (lan → lantern)
--prefix <p>	scope hits to a key namespace
--limit <n>	cap the ranked-hit count (0 = server default)

lantern-cli search "calm concise"
lantern-cli search "rolling update" --mode all
lantern-cli search "rolling update" --phrase
lantern-cli search serach --fuzziness 1          # finds "search"
lantern-cli search lan --prefix-terms            # finds "lantern"
lantern-cli search espresso --prefix user. --limit 20

Unlike get / scan / keys, search is a flag-based command (not part of the shared REPL grammar), because its many relevance controls read better as flags.

delete-prefix vertices <prefix> (DESTRUCTIVE)

Bulk-delete every live vertex under <prefix>, up to limit=<n> per call. Safety gate: running without dry_run=true or confirm=yes is refused — it prints the current match count + suggested next steps to stderr and exits non-zero. Kwargs: dry_run=true (count only, mutates nothing), confirm=yes (perform delete), limit=<n> (cap per call). Prints would delete <n> / deleted <n>. Incident edges are not eagerly removed (lazy GC).

lantern-cli delete-prefix vertices tmp/                  # refused → prints suggestion
lantern-cli delete-prefix vertices tmp/ dry_run=true
lantern-cli delete-prefix vertices tmp/ confirm=yes
lantern-cli delete-prefix vertices tmp/ confirm=yes limit=500

Edge commands

get edge <tail> <head>

Fetch one edge. Prints {tail, head, weight, expiration}. NotFound (exit 2) when the edge never existed, was deleted, or expired.

lantern-cli get edge alice bob
lantern-cli get edge alice bob | jq .weight

add edge <tail> <head> <weight> [ttl_seconds] (additive)

Sum <weight> onto (tail, head). Optional trailing ttl_seconds resets the edge's expiration to now+ttl_seconds each call (default permanent). Weight is float32; NaN/±Inf are rejected. Prints OK.

lantern-cli add edge alice bob 1.5            # weight 1.5
lantern-cli add edge alice bob 0.5            # weight now 2.0
lantern-cli add edge alice bob 0.1 1800       # weight 2.1, TTL reset to 30m

add decaying-edge <tail> <head> <initial_weight> <ratio> <steps> <interval_seconds>

Client-side sugar (no dedicated RPC — it fans out into one additive AddEdges batch) that lays down a geometrically decaying weight curve on (tail, head). The live weight starts at <initial_weight> and is multiplied by <ratio> (open interval 0 < ratio < 1) every <interval_seconds>, reaching zero after <steps> intervals. All six arguments are required; <steps> is capped at 16. The contributions telescope, so they sum to <initial_weight> (a 16 → 8 → 4 → 2 → 1 → 0 staircase is written as {8,4,2,1,1}, not {16,…}). The echo reports the full decay horizon (steps × interval) as the TTL.

# weight 16 now, halving every 60s: 16 → 8 → 4 → 2 → 1 → 0 over 5 minutes
lantern-cli add decaying-edge alice bob 16 0.5 5 60

put edge <tail> <head> <weight> [ttl_seconds] (idempotent)

Replace the (tail, head) weight. Optional trailing ttl_seconds (default permanent). Prints OK.

lantern-cli put edge alice bob 1.5            # weight 1.5
lantern-cli put edge alice bob 0.5            # weight 0.5 (overwritten)

delete edge <tail> <head> [<tail> <head>...]

Delete edges as a flat, whitespace-delimited sequence of <tail> <head> pairs. Exactly one pair → DeleteEdge; two or more pairs → batch DeleteEdges (chunked at --chunk-size). The token count must be even (each edge is two tokens); there is no separator character to configure. Idempotent. Single → OK existed=true|false; batch → OK <n>.

lantern-cli delete edge alice bob                      # single pair
lantern-cli delete edge alice bob bob carol carol dave # batch: 3 pairs
jq -r '.tail, .head' edges.json | xargs lantern-cli delete edge

scan edges <tail-prefix> [limit] [head=<prefix>] [all=true]

Enumerate live edges in ascending (tail, head) order, printed as an indented JSON array on stdout. The required positional <tail-prefix> may be the empty string "" to scan every tail; head=<prefix> narrows by head endpoint; the optional positional <limit> caps the page; all=true iterates every page into one array. A head-only scan (empty tail-prefix) still iterates every tail (no global reverse index), so supplying both a tail-prefix and head= is the most efficient shape.

lantern-cli scan edges user:
lantern-cli scan edges user: 100 head=post:
lantern-cli scan edges "" head=post: all=true > posts.json

Graph walks: bfs, pagerank, community

Run a read-only graph walk from <seed> and emit the visited subgraph as indented JSON {vertices: {...}, edges: {tail: {head: weight}}}. The CLI has one verb per traversal family; each verb also accepts the REPL positional grammar when more than the seed is supplied.

Verb	Main knobs	Meaning
bfs <seed>	--step, --fan-out, --reduction, --objective, --weighting, --prefix	Greedy per-hop top-k breadth-first walk. `reduction=mst
pagerank <seed>	--top-n, --restart-prob, --epsilon, --weighting, --prefix	Personalized PageRank relevance star. No reduction or objective knob; restart_prob must be in (0,1) when supplied and epsilon must be positive when supplied.
community <seed>	--max-size, --restart-prob, --epsilon, --reduction, --objective, --weighting, --prefix	Conductance-cut local community. max_size=0 lets the sweep decide; optional tree reduction renders a backbone view.

lantern-cli bfs alice                                      # depth-5, per-hop top-3 defaults
lantern-cli bfs alice --step 2 --fan-out 5 --weighting tfidf
lantern-cli bfs alice 3 20 reduction=mst objective=min     # same grammar as the REPL
lantern-cli bfs alice --step 2 --fan-out 5 --prefix users/ # frontier restricted to users/
lantern-cli pagerank alice --top-n 8                       # PPR neighbourhood, server-default locality
lantern-cli pagerank alice 8 restart_prob=0.25 epsilon=1e-4
lantern-cli community alice --max-size 30                  # conductance-cut community
lantern-cli community alice 30 reduction=mst objective=min # community as a spanning-tree backbone

bulk — NDJSON bulk load

Stream NDJSON (one JSON object per line) into Lantern via batch RPCs. Input is a file path or - for stdin. Lines are accumulated into batches of --chunk-size (default 1000). Progress prints to stderr (... <n>); OK <total> prints to stdout at end. A malformed line aborts the stream (exit 1); already-sent batches are not rolled back (Lantern has no transactions). Per line, "ttl" is a Go duration string and is permanent when omitted; "value" may be any JSON value.

# vertices: {"key":"alice","value":{"name":"Alice"},"ttl":"1h"}
lantern-cli bulk vertices vertices.ndjson

# edges add (additive): {"tail":"alice","head":"bob","weight":1.5,"ttl":"1h"}
cat edges.ndjson | lantern-cli bulk edges add -

# edges put (idempotent)
lantern-cli bulk edges put edges.ndjson --chunk-size 5000

dump / restore — whole-graph backup

Back up the whole graph and reload it. Unlike bulk (per-type NDJSON load), dump writes a single consistent snapshot of every live vertex and edge — taken under one server-side lock — and restore replays it. Like bulk, these are file-based commands (not part of the shared grammar).

• dump <file|-> — -/omitted = stdout. --format proto (default, length-delimited protobuf, lossless) or --format ndjson (human-readable, one {"kind":"vertex|edge",…} object per line). --prefix <p> restricts to the induced subgraph over vertices with that key prefix (an edge is kept only when both endpoints match). The summary (dumped <V> vertices, <E> edges) prints to stderr so stdout can carry binary protobuf.
• restore <file|-> — -/omitted = stdin. --format must match the dump. Records replay via PutVertices/PutEdges in --chunk-size batches; Put is idempotent, so re-running a restore is safe. A malformed record aborts (exit 1); already-sent batches are not rolled back. OK <total> prints to stdout. Absolute expirations round-trip; an expiration beyond the target server's LANTERN_TOMBSTONE_TTL cap is rejected (whole batch).

lantern-cli dump graph.lbk                  # whole graph -> file (protobuf)
lantern-cli dump - --format ndjson > g.ndjson
lantern-cli dump users.lbk --prefix user:   # partial backup
lantern-cli restore graph.lbk               # reload
cat g.ndjson | lantern-cli restore - --format ndjson

Other commands

• repl — legacy interactive prompt. Same grammar as the admin /cli page; type help inside for the per-verb reference, exit to quit. Use for quick manual poking; prefer the one-shot subcommands above for scripting, batches, typed values, scans, bulk loads, TLS, and compression.
• version — print the client version.
• completion <bash|zsh|fish|powershell> — generate shell completions.

Common recipes

# Snapshot a keyspace to a JSON array, then stream it elsewhere as NDJSON
lantern-cli scan vertices users/ all=true > users.json
jq -c '.[]' users.json | lantern-cli --address other-host:6380 bulk vertices -

# Count then safely purge a temporary keyspace
lantern-cli count vertices tmp/
lantern-cli delete-prefix vertices tmp/ dry_run=true
lantern-cli delete-prefix vertices tmp/ confirm=yes

# Accumulate an interaction signal with decay, then inspect the live sum
lantern-cli add edge userA itemX 1 86400
lantern-cli add edge userA itemX 1 86400
lantern-cli get edge userA itemX | jq .weight     # → 2

# Walk a relevance graph against a non-default replica over TLS
lantern-cli --tls --tls-ca ./ca.pem -H lantern.example.com -p 443 \
  bfs userA --step 2 --fan-out 10 --weighting tfidf

Gotchas checklist

• Choosing add edge vs put edge wrong silently corrupts weights — add accumulates, put overwrites.
• count vertices can over-report vs. live reality; use scan vertices <prefix> all=true | jq 'length' for an exact live count.
• delete-prefix vertices without dry_run=true/confirm=yes is intentionally refused — pass one explicitly.
• Vertex deletes leave incident edges to decay on their own TTL.
• scan returns a single bounded page unless you pass all=true; there is no hand-managed cursor to resume — all=true walks every page for you.
• JSON object/array vertex values round-trip as compact JSON strings, not nested structures.
• NotFound surfaces as exit code 2, distinct from local errors (exit 1) — use it to tell "missing" from "broken".