@catheadowl/ukp
v0.4.1
Published
Folder as a Service CLI: turn folders into named knowledge endpoints — one stable command surface, on this machine or your own server
Maintainers
Readme
UKP — Unified Knowledge Plane
Folder as a Service: turn folders into named knowledge endpoints — one stable command surface, on this machine or your own server.
Register a folder and it becomes an endpoint for humans and agents alike — nothing is started, the folder stays a folder. Navigate, read, and search it; propose changes back to the owner as reviewable suggestions; refresh the search index behind it (local folders today). No physical paths to memorize, no provider-specific commands to relearn.
[!NOTE] Early-stage CLI (MVP) — commands and behavior may still change.
npm install -g @catheadowl/ukp # or: bun add -g @catheadowl/ukpThe npm package installs the ukp command; the CLI runs on
Bun — install Bun first (the exact version is in
Requirements below; a missing bun gets an install hint, not a stack
trace).
$ ukp init service --name notes && ukp register
initialized Service: notes
registered: notes
$ mkdir -p 2026 && printf '# Q3 Plan\n\nGoals for Q3: ship the knowledge plane.\n' > 2026/q3-plan.md
$ ukp rg "Goals" --endpoint notes # no search provider needed
== notes ==
1. 2026/q3-plan.md:3
Goals for Q3: ship the knowledge plane.
uri: ukp://notes/2026/q3-plan.md#L3
$ ukp read ukp://notes/2026/q3-plan.md # read straight from the reference
# Q3 Plan
Goals for Q3: ship the knowledge plane.
$ echo '[capabilities.propose]' >> .ukp/service.toml # the write path is opt-in: declare propose
$ echo '# typo fix' > typo-fix.md # a proposal is any Markdown draft
$ ukp propose --endpoint notes --id typo-fix --file typo-fix.md
proposal typo-fix created (revision 1)A ukp:// reference is not a web link — it names a registered endpoint
(local or remote); open one with ukp read <uri>.
Why UKP
Knowledge work starts in folders, but repeated use needs stable names, predictable scope, and a single command surface. Use UKP when:
- the right knowledge already lives in folders, and callers should address it by name instead of path;
- you keep re-explaining to people and agents where things live and how they are indexed;
- changes should come back as reviewable proposals for the owner to decide, not as unreviewed edits;
- provider setup should stay with the provider instead of leaking into every caller.
What It Does
- Register local folders as named knowledge endpoints — a registered folder is a Service, addressed by its endpoint name.
ukp inspectshows which endpoints the current scope selects (the nearest.ukp/client.toml; every registered endpoint when there is none) — see what a command will touch before running it.- Navigate the Markdown structure of an endpoint — folders, descriptions, depth — with zero provider dependency.
- Read endpoint files through the built-in
read/filecapability — if a file moves, reference recovery re-finds it best-effort (git history first, then search). The optionalread/qmdgoes through QMD (an external tool — see Requirements).readandnavare derived defaults of every local Service. - Run base lexical search with
rgacross endpoint files — no search provider needed, on by default, shaped intoread-ready references — or enumerate them withrg --files(a tree walk: empty and binary files included, hidden files behind-- --hidden). - Search indexed content, QMD-backed: one endpoint, the workspace default
scope, or the whole local Registry.
--recursiveadditionally searches the endpoints a Service declares in its manifestdependencies— nothing recurs unless declared. - Propose changes as an idempotent, reviewable suggestion — the proposal lands in the endpoint's inbox and the verdict stays with its owner.
- Update provider-owned indexes through a stable UKP command (QMD-backed).
- Serve an endpoint over HTTP — a single endpoint, a
--selected subset, or every local binding as a host door — when you want it reachable from other machines. - Want a read-only endpoint? Declare zero capabilities — an empty
[capabilities]table still registers one (derivedread/navonly). - Writing a manifest by hand? Every legal key and its grammar ship in the
package — read them with
ukp guide manifest full(ukp guide manifestis the five-line cheat sheet). - Give agents machine-readable results (
--json;ukp readuses--format json): each search result carries adocid— the machine address the next command (ukp read) consumes — plus a verifiedukp://reference in a sidecar field (a separateukp_urifield carried next to thedocid, not inside it), so handoffs stay replayable in any session.
UKP owns endpoint names, Registry bindings, scope, and output shape; the provider owns collection setup, indexes, ranking, and maintenance. UKP points you at the provider's own setup — it does not rewrite provider config for you.
Install
Requirements:
- Bun
1.3.14or newer, installed by you — the npm package installs theukpcommand, but the CLI runs on Bun; whenbunis missing the command says how to install it instead of showing a stack trace. - ripgrep (
rg) onPATHforukp rgand the provider-free lexical search tier — install it from ripgrep's own releases or your package manager. A missing binary skips the affected command with a warning instead of failing the run. - QMD on
PATHonly for the QMD-backed capabilities (search/qmd,read/qmd,update/qmd). QMD is an external indexing tool maintained as a separate project —ukp guide service qmdhands off to its provider-owned setup path. UKP installs and runs without it — those capabilities report as unavailable untilqmdis available.
npm install -g @catheadowl/ukp
ukp --version
ukp guide serviceOne-off execution: npx @catheadowl/ukp --version (or pnpm dlx / bunx).
First Run
For a human or agent starting from a folder:
ukp init servicecreates the minimum Service Manifest (.ukp/service.toml).ukp guide serviceshows the provider-agnostic path. For the current QMD provider,ukp guide service qmdhands off the provider-owned setup.ukp diagnosechecks that the folder is wired correctly.ukp registeradds the folder to the Host Registry (~/.ukp/registry.toml).ukp inspect --endpoint <name>shows the current binding, manifest, and provider availability.ukp nav,ukp rg, andukp readgive the provider-free baseline.ukp search "<query>" --endpoint <name>finds indexed matches after provider setup.
No QMD installed? Stop at step 6 — nav, read, and rg work on any
endpoint without it; propose works wherever it's declared.
An agent can carry out the same flow on your behalf.
For workspace defaults, run ukp use <endpoint> (see ukp guide client) —
it writes .ukp/client.toml and keeps it committable in one step.
Commands
Grouping below follows ukp --help; primary capability commands stay a flat
ukp <verb>, while multi-verb capability families appear as object command
groups (ukp init service, ukp guide <topic>). --endpoint <name>
is the canonical endpoint selector (ukp unregister <name> still takes the
endpoint as a positional legacy form); -g selects the full local Host
Registry where supported.
The same five commands — search, read, nav, rg, propose — work on local and remote endpoints; consuming a remote endpoint is a one-command gesture (see below).
Endpoint commands:
| Command | What it does |
|---|---|
| ukp search | Indexed search through the endpoint's provider (QMD today); --recursive expands the manifest's declared dependencies. Results hand off a docid (the machine address ukp read consumes) and verified ukp:// references. |
| ukp read | Reads an endpoint-scoped resource — exact path, ukp:// URI, or a docid handed off by search results. |
| ukp nav | Markdown outline of an endpoint (--depth, respects .gitignore); on by default, configurable via [capabilities.nav]. |
| ukp rg | Lexical grep (ripgrep) across endpoint files — provider-free, on by default; --files enumerates them instead of searching. Results become read-ready ukp:// references. A missing rg binary skips the endpoint with a warning. |
| ukp propose | Submits an idempotent change proposal (suggestion box — the owner decides what happens next). Created/unchanged/updated; the revision bumps only on updated. |
Registry commands:
| Command | What it does |
|---|---|
| ukp init service | Creates a minimal .ukp/service.toml and a .ukp/.gitignore that ignores machine-local state only — the declarations themselves are committable by design (a fresh clone re-registers in one ukp register). |
| ukp use <endpoint> [endpoint...] | One-step consumer gesture: sets this workspace's default_endpoints (.ukp/client.toml, idempotent — every name must be registered). ukp inspect confirms the active scope. |
| ukp register / ukp unregister --endpoint <name> | Manages Host Registry bindings — local folders and remote endpoints alike (ukp register --url, see Remote in 60 seconds). On a remote registration --name <handle> disambiguates collisions; a folder that moved re-binds in one step (ukp register --rebind). |
| ukp list | Lists endpoint bindings and capabilities under the workspace scope by default (nearest .ukp/client.toml; -g for the full Host Registry). --json emits the offline machine snapshot (ukp.list.v1, zero network). New endpoints on a host door show as a stderr note — importing stays an explicit gesture, and a key-carrying binding sees the door's admission for its own key. |
A legacy .ukp/.gitignore carrying the exact retired self-ignore template
migrates to this posture in passing whenever ukp register (local folders)
or ukp use meets one; anything else in that file is operator-owned and
left untouched (a stderr note names it).
Operations commands:
| Command | What it does |
|---|---|
| ukp diagnose | Checks a Service folder or endpoint scope for wiring problems. |
| ukp inspect | Explains current scope, bindings, manifest capabilities, and provider availability. |
| ukp update | Runs provider-owned maintenance when update/qmd is declared (local endpoints today). |
| ukp serve | Serves one endpoint — or, without --endpoint, local bindings as a host door (every one of them, or a --selected subset) — over HTTP, loopback by default. ukp serve token add|list|revoke issues scoped door keys; ukp serve status self-describes the door; ukp serve share <name> --to <label> --at <url> [--rw] prints the consumer's paste-ready register command. The wire details live in ukp guide remote and the deployment guide. |
Help commands:
| Command | What it does |
|---|---|
| ukp version / ukp --version / ukp -V | Shows the package version. |
| ukp guide service | Provider-agnostic Service setup path. |
| ukp guide service qmd | Provider-owned setup for the QMD provider. |
| ukp guide client | How a workspace uses registered Services by default. |
| ukp guide rg | The rg quickstart: modes, glob semantics, visibility tiers. |
| ukp guide remote | How to serve and consume endpoints across machines. |
| ukp guide propose | The propose quickstart. |
Remote in 60 seconds
ukp serve exposes an endpoint over HTTP. Authentication is deny-by-default:
serving with a --host beyond loopback requires a credential — the
UKP_SERVE_TOKEN env token (full power) or a labeled key issued into
the ~/.ukp/tokens file. Tokenless serving needs an explicit
--allow-anonymous, is refused off loopback, and stays tokenless only
while the tokens file holds no keys — any issued key arms the bearer
gate for every caller. Transport is equally deny-by-default: a bind
beyond loopback without TLS is refused at startup, because bearer keys
must not travel unencrypted — --allow-http is the explicit opt-in for
a door whose TLS is terminated by a fronting component (proxy on
another host, container sidecar); that hop stays plaintext. The two fastest
paths — each block notes where its commands run:
# From the consumer machine — SSH between two personal machines; the door is
# woken on demand, nothing to start on the host (prerequisites: ssh
# reachable + ukp on its PATH):
ukp register --url ssh://<host> # once; trust-on-first-use pinned
ukp read --endpoint <name> notes/x.md # just works, like local
# Native TLS on a bare IP — self-signed, pinned automatically at registration.
# The serve line runs ON THE HOST (keep it under your process manager); the
# register line runs on the consumer machine:
UKP_SERVE_TOKEN=<token> ukp serve --endpoint <name> --host 0.0.0.0 --port 8570 --tls
ukp register --url https://<ip>:8570 --endpoint <name> --token <token>Handing a second machine or an agent a narrower key? Issue labeled, scoped, revocable keys instead of sharing the env token (ON THE HOST):
ukp serve token add liku "notes:ro,cad:rw" # prints the raw key ONCE
ukp serve token list # labels, key ids, scopes
ukp serve token revoke liku # next request is a 401Scopes are name:ro|rw comma-separated (full power is the explicit *:rw;
a read-only scope has no propose route); the file stores hashes only, and
the door re-reads it on every request — deleting a line revokes without a
restart. What a scoped key can and cannot see — the route denial, the
admission face, and the env-token precedence — is the Security section
below.
NAT/EIP cloud host (public IP on no NIC)? Name it with
ukp serve --tls --tls-san <public-ip> — the persisted certificate re-signs
over the same key, so the pin (and every registration) survives; details in
the deployment guide.
Registration mechanics: a host door url imports every endpoint it declares
(--endpoint <name> checks the served name and narrows the import to that
one, --select narrows to a subset); --token is stored with the binding;
re-running a registration refreshes it idempotently. A host whose registry
mixes shareable knowledge with internal projects can serve
ukp serve --select a,b,c — one port for exactly those endpoints; everything
the door does not select behaves as if it did not exist (discovery, routes,
and 404 rosters alike).
Remote endpoints take the same commands as local ones — search, read, nav, rg, propose. The full guide — the host door (one port for the whole registry), Caddy and Tailscale fronting, the certificate pinning lifecycle, and the hardening posture — lives in the deployment guide.
Security
UKP is local-first: nothing listens on the network until you run
ukp serve. When you do, the surface is deny-by-default — serving beyond
loopback without a credential is refused, and anonymous serving is an
explicit flag that only works on loopback. Credentials come in two forms:
the UKP_SERVE_TOKEN env token (full power, takes precedence while set)
and labeled keys in the 0600 ~/.ukp/tokens file (hash-only storage,
required per-key scopes, revocation by deleting the line — effective on
the next request). Transport is https://, pinned
automatically at registration (a certificate that renews on the same key
re-pins silently; a different key hard-blocks with both fingerprints), or
ssh://, where SSH carries both encryption and authentication. Plain
http stops at loopback: a door bound beyond loopback without TLS is
refused at startup — --allow-http is the explicit opt-in when TLS is
terminated in front of the door (that hop stays plaintext, and the
startup banner says so). A
--select door neither routes, declares, nor lists unselected endpoints —
excluded and unknown names return byte-identical 404s, and a scoped key
probing an endpoint it cannot touch gets a route denial (no route for
'<name>' under your key) — still 404-shaped, never 403, and uniform across
a read-only scope, an absent scope, and an undeclared write route.
Accepted tradeoffs, disclosed rather than hidden: tokens are long-lived
static bearer secrets stored client-side — in the OS credential store by
default (Windows DPAPI, macOS Keychain, Linux Secret Service; the registry
keeps only a token_ref pointer), or in the 0600 registry file with its
crash-safety .bak copy when no store exists (the register output says
so — never a silent downgrade), or in an environment variable; the
Windows door generator (ukp serve --print-task) embeds the token in a
0600 start-door.cmd it never prints; identity pinning is
trust-on-first-use (an SSH-style first-connect window). Hardening
guidance — token strength, reverse proxies and their same-machine
blind spot, firewalls — is in the
deployment guide.
Found something? Report it privately — see SECURITY.md; please don't use public issues for security reports.
Not Yet
- remote operation of
update, and a formally specified network protocol beyond the current ukp-remote wire v1; - semantic search tier, query rewrite, reranking, or deduplication;
- full Client Scope with aliases, visibility, inheritance, or profiles;
- automatic artifact browsing, cleanup, or "select result N" references;
- standalone binary distribution.
Documentation
- Remote deployment — serving endpoints across machines: the full guide.
Also ships inside the npm package (
docs/remote-deployment.mdin the installed package); the other docs live in the GitHub repository. - Contributing — development setup and release packaging.
- Changelog — what changed per release (one file per version; the npm tarball carries the same files).
- Repository: https://github.com/CatheadOwl/ukp · Issues: https://github.com/CatheadOwl/ukp/issues
