v3 cli

Agent-first CLI for renketsu, the embedded graph + vector memory engine.

Runs against the v3 API server (default https://renketsu.codespring.app, override via V3_API_URL).

Install

bun add -g @codespring-app/v3-cli
# or per-project
bun add @codespring-app/v3-cli

Requires Bun ≥ 1.3 — the CLI uses Bun.hash and other Bun-native APIs.

Quick start

v3 auth login
v3 project list
v3 project use <id>

# Read-side: sync, returns JSON on stdout.
v3 search "auth flow"
v3 stats
v3 graph --limit 100

# Write-side: ingest local files. Auto-detects format by extension.
v3 ingest-file 'docs/**/*.md' --source docs --wait
v3 ingest-file 'src/**/*.ts'  --source code --wait
v3 ingest-file package.json   --source manifest --wait

ingest-file supports:

| Extension | Projector | What it extracts | |-----------|-----------|------------------| | .md / .markdown | markdown | document + section hierarchy, relative-link edges | | .ts / .tsx / .js / .jsx / .mts / .cts / .mjs / .cjs | code | file + symbol nodes (function, class, method, interface, type, enum, exported const), child_of / member_of / imports edges | | .json / .jsonc | json | hierarchical object nodes addressed by JSON Pointer, $ref → references edges |

Reruns are incremental:

• File-level skip: unchanged content (Bun.hash) → no read, no project, no POST.
• Symbol-level skip: within a changed file, only items whose (text + edges) hash differs from the cached one get posted.
• --force bypasses both caches.

Cache lives at $XDG_CONFIG_HOME/v3/ingest-cache.json.

Inbound webhooks

Renketsu projects can expose public URLs that accept POSTed JSON and ingest it into the graph. Useful for forwarding GitHub events, Linear updates, Stripe webhooks, or your own automation.

Configure them in Settings → Webhooks in the web UI. Each webhook gets a unique URL like https://renketsu.codespring.app/api/hooks/<slug> and an HMAC signing secret (shown once at creation).

# Quick test from your terminal:
SECRET="<the secret>"
URL="https://renketsu.codespring.app/api/hooks/<slug>"
BODY='{"event":"hello","ref":"main"}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "X-Renketsu-Signature: sha256=$SIG" \
  -d "$BODY"

Hit logs (response code, source IP, payload preview, ingested-node count) are visible per webhook in the Settings page. Full contract: limits, status codes, signing format, and roadmap modes documented at docs/webhooks.md in the repo.

Async commands

ingest, ingest-file, ingest-structured, extract, and ask return a job_id immediately. Pass --wait to block on the SSE event stream and exit when the job finishes.

v3 ask "how does session refresh work" --wait

extract

Runs LLM-based entity-and-relationship extraction over arbitrary text and persists the result into the project's graph by default. Pass --preview-only to get the extracted entities back without committing (useful when you want to review before letting the data land):

# Default: extracts and ingests in one step
v3 extract --source my-notes --stdin --wait < notes.md

# Preview only — returns entities, does NOT write to the graph
v3 extract --source my-notes --stdin --wait --preview-only < notes.md

Behavior changed in 0.2.1: prior versions only returned the preview and required a separate /ingest call to persist. The CLI now matches user expectations: extract uploads.

Output contract

• stdout: JSON answer (or NDJSON for streams)
• stderr: errors (JSON); progress lines when V3_VERBOSE=1

Run v3 --help for the full command surface.

License

Private — © codespring.