rock-kb 0.4.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 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.