LibraLibra
LibraLibra
DocsBlogLibra
Getting Started
Architecture
Design
Commands
libra addlibra agentlibra alternateslibra applylibra archivelibra authlibra automationlibra bisectlibra blamelibra branchlibra bundlelibra cachelibra cat-filelibra check-attrlibra check-ignorelibra check-mailmaplibra checkoutlibra cherry-picklibra cleanlibra clonelibra cloudlibra code-controllibra codelibra commit-treelibra commitlibra completionslibra configlibra credentiallibra depslibra describelibra diff-fileslibra diff-indexlibra diff-treelibra difflibra dirtylibra fast-exportlibra fast-importlibra fetchlibra filelibra for-each-reflibra format-patchlibra fscklibra gclibra graphlibra greplibra hash-objectlibra hookslibra hydratelibra index-packlibra initlibra investigatelibra layerlibra lfslibra loglibra logfilelibra loginlibra logoutlibra ls-fileslibra ls-remotelibra ls-treelibra maintenancelibra medialibra merge-baselibra merge-filelibra mergelibra metadatalibra mvlibra noteslibra oplibra openlibra pack-objectslibra packagelibra prunelibra publishlibra pulllibra pushlibra read-treelibra rebaselibra refloglibra remotelibra repacklibra replacelibra rererelibra resetlibra restorelibra rev-listlibra rev-parselibra revertlibra reviewlibra revisionlibra rmlibra sandboxlibra servicelibra shortloglibra show-reflibra showlibra sparse-viewlibra stashlibra statslibra statuslibra switchlibra symbolic-reflibra taglibra update-indexlibra update-reflibra usagelibra verify-packlibra whoamilibra worktreelibra write-tree
API Reference
Policy
Commands

libra service

Command reference for `libra service`

Headless local service: notification bus + dirty-mark ingestion (a Libra extension, lore.md §1.11). Git has no equivalent.

Synopsis

libra service run [--host <LOOPBACK-IP>] [--port <PORT>]
libra service status
libra service events

Description

libra service run starts a foreground, local-only HTTP service:

  • --host must be a literal loopback IP (127.0.0.0/8 or ::1) — hostnames and non-loopback IPs are refused (exit 129). The service never opens an outward TCP port; every endpoint additionally rejects non-loopback peers.
  • --port defaults to 0 (OS-assigned); the real address is published in .libra/service/service.json. One instance per repository (service.lock); stale locks from dead processes are reclaimed.
  • Stop with Ctrl-C (or SIGTERM on Unix) — shutdown removes the discovery file and releases the lock.

Endpoints (all loopback-checked; data-carrying ones require the X-Libra-Service-Token header matching the 0600 file .libra/service/service-token — other local users are not trusted):

EndpointAuthPurpose
GET /api/healthloopbackLiveness probe.
GET /api/service/eventstokenSSE notification stream.
POST /api/service/dirty/marktoken{"paths":[...]} — advisory dirty marks through the validated owner API (whole batch refused if any path escapes the repo; over-report-only).
POST /api/service/notifytoken{"type":"...","data":{...}} — publish a custom notification (automation triggers).

Notification v1 semantics: events are {seq,type,at,data} with seq monotonic per service run. Delivery is at-most-once — a lagging consumer receives a resync event and should re-read authoritative state (libra dirty --list, libra status); seq restarts when the service restarts. The durable facts (the marks) live in SQLite and survive kill -9; everything on the bus is derivable. Request bodies are capped at 256 KiB.

libra service status reports the running instance (pid, URL, health; exits 1 when none). libra service events tails the stream (human lines; NDJSON under --json; exits cleanly when the server goes away).

Exit codes

CodeMeaning
0Success.
1status with no running instance.
128Not a repository.
129Usage errors (non-loopback --host).

Examples

libra service run                      # loopback, OS-assigned port
libra service status                   # pid, URL, health
libra service events                   # tail notifications
TOKEN=$(cat .libra/service/service-token)
URL=$(libra --json service status | jq -r .data.base_url)
curl -H "X-Libra-Service-Token: $TOKEN" -X POST "$URL/api/service/dirty/mark" \
     -H 'content-type: application/json' -d '{"paths":["src/main.rs"]}'

Comparison with Git

Git has no local service surface (git daemon serves the wire protocol to the network — the opposite of this design). Classified intentionally-different in COMPATIBILITY.md.

libra sandbox

Command reference for `libra sandbox`

libra shortlog

Command reference for `libra shortlog`

On this page

SynopsisDescriptionExit codesExamplesComparison with Git