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

Open Knowledge Format

Download, inspect, and verify full or compact core read-only OKF releases without cloning the repository:

uvx rock-kb okf download
uvx rock-kb okf inspect rock-agent-kb-okf-vX.Y.Z.zip
uvx rock-kb okf conformance third-party-okf.zip
uvx rock-kb okf verify rock-agent-kb-okf-vX.Y.Z.zip
uvx rock-kb okf download --profile core

Use --profile full|core, --format tar.gz, --version X.Y.Z, or --destination <path> with okf download. Downloads require published SHA-256 evidence. conformance handles generic OKF bundles; verify applies Rock release integrity and safety rules. The client does not import OKF into trusted knowledge.

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 issues search "Azure blob CPU issue"
uvx rock-kb issues list --repository core --state open --version 19.2
uvx rock-kb issue 6919
uvx rock-kb issues assess instance-profile.json
uvx rock-kb issues plan 6919
uvx rock-kb feedback '<result-id>' --rating -1 --reason outdated
uvx rock-kb report-issue --failure-type retrieval --operation search --error-code search_unavailable --description "Search returned a temporary service failure." --redaction-attested
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. report-issue is for failures in the KB service, MCP, CLI, schema, authentication, or retrieval path. Its description is limited and must be redaction-attested; never include logs, queries, secrets, private paths, or private Rock data. It returns a stable report ID and does not create a GitHub issue automatically.

Rock product issue commands are read-only and separate from report-issue, which reports a malfunction in the KB itself. Product issue reports are routing evidence, not proof of local impact or cause. issues assess accepts only a bounded JSON profile containing versions, platforms, concept IDs, and capability names; never include logs, queries, private identifiers, or person data.

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.