npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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

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/ukp

The 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 inspect shows 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/file capability — if a file moves, reference recovery re-finds it best-effort (git history first, then search). The optional read/qmd goes through QMD (an external tool — see Requirements). read and nav are derived defaults of every local Service.
  • Run base lexical search with rg across endpoint files — no search provider needed, on by default, shaped into read-ready references — or enumerate them with rg --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. --recursive additionally searches the endpoints a Service declares in its manifest dependencies — 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 (derived read/nav only).
  • Writing a manifest by hand? Every legal key and its grammar ship in the package — read them with ukp guide manifest full (ukp guide manifest is the five-line cheat sheet).
  • Give agents machine-readable results (--json; ukp read uses --format json): each search result carries a docid — the machine address the next command (ukp read) consumes — plus a verified ukp:// reference in a sidecar field (a separate ukp_uri field carried next to the docid, 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.14 or newer, installed by you — the npm package installs the ukp command, but the CLI runs on Bun; when bun is missing the command says how to install it instead of showing a stack trace.
  • ripgrep (rg) on PATH for ukp rg and 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 PATH only 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 qmd hands off to its provider-owned setup path. UKP installs and runs without it — those capabilities report as unavailable until qmd is available.
npm install -g @catheadowl/ukp
ukp --version
ukp guide service

One-off execution: npx @catheadowl/ukp --version (or pnpm dlx / bunx).

First Run

For a human or agent starting from a folder:

  1. ukp init service creates the minimum Service Manifest (.ukp/service.toml).
  2. ukp guide service shows the provider-agnostic path. For the current QMD provider, ukp guide service qmd hands off the provider-owned setup.
  3. ukp diagnose checks that the folder is wired correctly.
  4. ukp register adds the folder to the Host Registry (~/.ukp/registry.toml).
  5. ukp inspect --endpoint <name> shows the current binding, manifest, and provider availability.
  6. ukp nav, ukp rg, and ukp read give the provider-free baseline.
  7. 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 401

Scopes 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.md in 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