rock-kb 0.5.0

Thin CLI client for the public Rock RMS agent knowledge base.

rock-kb

Thin terminal client for the public Rock RMS agent knowledge base.

Quick Start

The published client is available from PyPI as rock-kb.

For one-off use, run it with uvx. uvx is part of the uv Python toolchain; it downloads or reuses a cached copy of the package and runs the command in an isolated environment.

Check whether uvx is installed:

uvx --version

If it is missing, install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or on macOS with Homebrew:

brew install uv

Then run a smoke test:

uvx rock-kb search "check-in labels not printing"

To configure a detected Codex, Claude Code, Cursor, or OpenCode installation with both the hosted MCP server and the Rock KB skill:

uvx rock-kb install-agent --dry-run
uvx rock-kb install-agent

The installer changes only the rock-kb MCP entry and the rock-kb-agent/SKILL.md path. It backs up existing files before writing and reports every path it touched. Use --agent codex (repeatable) to select hosts explicitly, or --scope project --project-dir <path> for project-local setup.

Common commands:

uvx rock-kb get check-in
uvx rock-kb result '<result-id>'
uvx rock-kb claim '<claim-id>'
uvx rock-kb claims workflows --min-tier source_backed
uvx rock-kb model-map list
uvx rock-kb model group
uvx rock-kb recipes list
uvx rock-kb recipes search "registration attendance dashboard"
uvx rock-kb recipe oneall:check-in-status-dashboard
uvx rock-kb recipe verify oneall:check-in-status-dashboard --rock-version 18
uvx rock-kb feedback '<result-id>' --rating -1 --reason outdated
uvx rock-kb dashboard
uvx rock-kb mcp-config

For repeated use on a server or agent host, install the CLI permanently:

uv tool install rock-kb
rock-kb search "check-in labels not printing"
rock-kb mcp-config

rock-kb mcp-config prints the hosted HTTP MCP config. It does not start a local server.

Search output is compact by default. It returns stable IDs, snippets, trust tiers, source URLs, scores, and ranking signals. Use rock-kb result <id> or rock-kb claim <claim-id> for full detail. Use search --full only for compatibility with workflows that still need full rows in one response.

recipe verify checks immutable source hashes and declared compatibility. It uses the hosted service's immutable-byte cache and GitHub Contents API fallback when needed; it does not execute recipe code or change Rock. feedback accepts only a fixed rating and reason; it does not send free-text comments or query text.

To test unreleased client changes directly from GitHub, use:

uvx --from 'git+https://github.com/ONE-ALL-Church/rock-agent-kb#subdirectory=clients/python' rock-kb search "check-in labels not printing"

From a local rock-agent-kb checkout:

uv run --project clients/python rock-kb search "check-in labels not printing"
uv run --project clients/python rock-kb model-map list
uv run --project clients/python rock-kb model group --fields identity,required,relationships,diffs
uv run --project clients/python rock-kb model group --property Members
uv run --project clients/python rock-kb validate bundle.jsonl
ROCK_KB_TOKEN=<issued-token> uv run --project clients/python rock-kb auth-check --org <org-id>
ROCK_KB_TOKEN=<issued-token> uv run --project clients/python rock-kb submit bundle.jsonl --dry-run
ROCK_KB_TOKEN=<issued-token> uv run --project clients/python rock-kb submit bundle.jsonl

Set ROCK_KB_URL to point at a staging service. Set ROCK_KB_TOKEN when submitting bundles. rock-kb submit infers --org from the bundle when all rows use the same org_id.

Secret-file usage is also supported, which is often easier for hosted agents:

rock-kb auth-check --org <org-id> --token-file /run/secrets/rock-kb-token
rock-kb submit bundle.jsonl --token-file /run/secrets/rock-kb-token --dry-run
rock-kb submit bundle.jsonl --token-file /run/secrets/rock-kb-token

Hosted submission is token-gated per organization. If rock-kb submit reports that ROCK_KB_TOKEN is required, ask a Rock KB maintainer to issue a token for the reviewed orgs/<org-id>.yaml registration. Store the token in an environment variable, CI/app secret, mounted secret file, or local secret store such as macOS Keychain; do not save it in repo files.