albok-client (0.1.1)
Installation
pip install --index-url https://gitea.phasefinal.com/api/packages/vh/pypi/simple/ --extra-index-url https://pypi.org/simple albok-clientAbout this package
Albok — the clients: the `albok` CLI and the `albok-mcp` stdio server, stdlib-only HTTP clients over the albok-service read API (unit 3; docs/contracts/unit3_clients.contract.md).
albok-client
The albok CLI and the albok-mcp stdio server: stdlib-only HTTP clients over
albok-service's read API (unit 3; contract at docs/contracts/unit3_clients.contract.md).
The postbox / althing-mcp shape: nothing guessed, an unreachable service is never an empty
result, and the two surfaces expose the same verbs.
Install
uv tool install albok-client --index https://gitea.phasefinal.com/api/packages/vh/pypi/simple
Both commands read two environment variables and nothing else:
export ALBOK_SERVICE=http://albok.nh3.internal:8392 # no default: a guessed address reads the wrong store
export ALBOK_TOKEN=<your per-handle token> # or --token-file PATH; infra-ops mints tokens
albok
albok search QUERY [--wing B/W]... [--top-k N] [--facet KEY=VALUE]... [--include-tombstoned] [--include CLASS]... [--json]
albok read OBJECT_ID [--extracted] [--include CLASS]... the pristine bytes, to stdout
albok sidecar OBJECT_ID [--include CLASS]...
albok buildings | albok wings BUILDING
albok facets B/W [KEY] [--include CLASS]... facet keys, or one key's values with counts
albok objects B/W [--facet KEY=VALUE]... [--include CLASS]...
albok health | albok status aggregate health | the wings this token can read
albok ingest [nemi args] execs `nemi run …` (Nemi owns ingestion)
Exit codes: 0 ok · 1 the service refused (the error on stderr) · 2 unreachable · 3 no token ·
4 no address · 5 something answered that is not albok-service (no X-Albok-Service header, or a
shape this client cannot render; try --json) · 64 usage.
Every sidecar key is a facet: --facet structure.repo=albok, --facet derived.entities=worldtree,
--facet structure.entry_date=2026-10-02, --facet kind=section.
Objects in a sensitivity class (adult, personal, secret) are hidden by default; --include CLASS
asks for one back, and the service honours it only where your token holds that class. When your token
holds a class on a searched wing, the search prints hidden: secret 2, … — including a class may change the answer under the results (service 0.1.13 and later). The MCP tools take the same include array.
albok-mcp
A stdio JSON-RPC 2.0 server (protocol 2025-11-25) with nine read-only tools: albok_search,
albok_read, albok_sidecar, albok_buildings, albok_wings, albok_facets, albok_objects,
albok_health, albok_status. Claude Code registration:
claude mcp add albok -e ALBOK_SERVICE=http://albok.nh3.internal:8392 -e ALBOK_TOKEN=<token> -- albok-mcp
A failure is an isError result carrying unreachable, not_albok or rejected; never an empty list.