CLI

Sync graded artifacts into your repo with npx.

One npm package wraps the Rubrkit API: pull approved artifact bundles into your project, then validate, test, audit, and eval them locally or in CI.

View on npm Browse commands

rubrkit

npx rubrkit

Node >= 22

RUBRKIT_API_KEY

Quickstart

rubrkit on npm

# Pull approved artifacts into your project
npx rubrkit pull all --yes

# Validate locally — no API, no credits
npx rubrkit validate "prompts/**/*.md"

# Audit in CI with a quality gate
npx rubrkit audit team-agent-kit --ci --fail-under 85

Quickstart

Up and running in three steps.

No build step and no global install. Run it with npx, point it at a key, and pull.

Run it with npx

No install required. Run any command with npx rubrkit <command>, or add rubrkit as a dev dependency to pin a version.

Set your API key

Export RUBRKIT_API_KEY for commands that call Rubrkit (pull, test, audit, eval, report). Keys are never written to disk, logs, or bundles.

Pull approved artifacts

Run npx rubrkit pull all --yes to place bundles where your agent expects them and track them in .rubrkit/manifest.json.

Commands

Six commands, one workflow.

Pull artifacts in, check them locally for free, and run scored audits and evals when you want the API to weigh in. Expand any command for its syntax, scopes, and examples.

pull

Download artifact bundles from Rubrkit and write them into your local project, tracked in .rubrkit/manifest.json.

Syntax

rubrkit pull [all|<bundle>] [options]

Required scopes

artifacts:pull

Examples

rubrkit pull
rubrkit pull all --yes
rubrkit pull team-agent-kit --destination ./agents
rubrkit pull --label prod --label api --yes
rubrkit pull all --yes --dry-run

validate

Check artifact syntax and structure locally. No API calls and no credits.

Syntax

rubrkit validate <path|glob> [options]

Access

Runs locally · no API key

Examples

rubrkit validate docs/example.rubr_flow
rubrkit validate "prompts/**/*.md" --format json

test

Validate artifacts locally, or submit them to Rubrkit for remote testing and quality scoring.

Syntax

rubrkit test <path|glob|selector> [options]

Required scopes

artifact_bundles:write

files:write

audits:run

jobs:read

credits:read

Examples

rubrkit test "prompts/**/*.md" --local --format json
rubrkit test team-agent-kit --remote
rubrkit test team-agent-kit --remote --fail-under 80

audit

Submit artifacts to Rubrkit and run audit checks with quality gates for CI.

Syntax

rubrkit audit <selector> [options]

Required scopes

artifact_bundles:write

files:write

audits:run

jobs:read

credits:read

Examples

rubrkit audit team-agent-kit --fail-under 85 --ci
rubrkit audit team-agent-kit --format junit --output results.xml --ci

eval

Evaluate artifacts against rubrics with detailed scoring and reporting.

Syntax

rubrkit eval <selector> [options]

Required scopes

artifact_bundles:write

files:write

audits:run

jobs:read

credits:read

Examples

rubrkit eval team-agent-kit --format junit --output rubrkit-junit.xml

report

Fetch results from a completed async job.

Syntax

rubrkit report <job-id> [options]

Required scopes

jobs:read

Examples

rubrkit report job-abc-123 --format json

Flags

Options, grouped by what they do.

Flags are shared across commands; each command ignores the ones that do not apply.

Output and formatting

--format <text|json|junit>

Output format for test, audit, and eval results. Defaults to text.

--output <path>

Write results to a file instead of stdout.

Artifact selection

--artifact-bundle <id|name>

Select a specific artifact bundle to pull or test.

--artifact <id|path>

Select a specific artifact file within a bundle.

--label <name>

Select every bundle carrying a label. Repeatable and comma-separated, with OR semantics.

--rubric <id|path>

Select a specific evaluation rubric for audits.

--all

Pull all available bundles. Requires --yes for safety.

Quality gates

--fail-under <score>

Exit 1 if the quality score falls below this threshold (0 to 100).

--fail-on <level>

Exit 1 if any finding at this severity or higher is detected (critical, high, medium, low).

Execution mode

--local

Run checks locally with no API calls or credits. Cannot be combined with --remote.

--remote

Submit artifacts to Rubrkit for scoring. Requires an API key. Default for test, audit, and eval.

--ci

Non-interactive CI mode with structured output and CI-appropriate exit codes.

--no-ai

Skip AI-powered analysis to reduce cost where supported.

Pull-specific

--agent <auto|codex|claude|generic>

Target agent type for artifact placement. auto detects from project structure.

--destination <path>

Target directory for pulled artifacts. Defaults to the current directory.

--force

Overwrite protected local changes. By default pull stops if a tracked file differs.

--prune

Remove manifest-tracked files that are no longer selected.

--update-only

Only update files already tracked in the manifest. Skip new files.

--yes, -y

Skip the interactive confirmation for unambiguous pulls.

Debugging and configuration

--dry-run

Preview planned actions without changing files or calling the API.

--watch

Re-run checks when local files change.

--changed

Only test files changed since the last run.

--config <path>

Load options from a JSON config file. API keys are not allowed in config files.

--api-url <url>

Override the API endpoint. Defaults to https://rubrkit.com/api/v1.

--api-key <key>

Provide the API key explicitly. Prefer the RUBRKIT_API_KEY environment variable.

Authentication

One environment variable, scoped per command.

Commands that call Rubrkit read a bearer key from RUBRKIT_API_KEY. Keys are never written to the manifest, logs, or client bundles.

Set your key

Export the key for the session, or pass --api-key for a one-off. Create scoped keys in the dashboard.

Shell

export RUBRKIT_API_KEY=rubrkit_live_...
npx rubrkit pull all --yes

Scopes per command

pullartifacts:pull

test · audit · evalartifact_bundles:write, files:write, audits:run, jobs:read, credits:read

reportjobs:read

validatenone (runs locally)

Artifact placement

Pull writes artifacts where your agent expects them.

The --agent flag decides where the primary artifact lands. Supporting files always go to .rubrkit/artifacts/<bundle>/, and a manifest tracks everything pull manages.

Agent

Primary artifact

Auto-detect

auto

Detected from project structure

Recommended for new projects

codex

AGENTS.md

Looks for AGENTS.md

claude

CLAUDE.md (or .claude/CLAUDE.md)

Looks for CLAUDE.md or .claude/

generic

Preserves original paths

Default fallback

Exit codes

Predictable codes for scripts and CI.

Every command exits with a stable code so pipelines can branch without parsing output.

Success. Checks passed or the command completed without errors.

Validation or quality checks failed (threshold not met, findings detected).

Invalid CLI usage or configuration error.

Authentication or authorization failure (missing or invalid API key).

Rate limited, usage blocked, or circuit breaker active.

Network, API, or server failure.

Pull your first artifact bundle.

Create a scoped key, then run npx rubrkit pull all --yes. When you are ready to call the API directly, the full reference is one click away.

Create API keys Read the API reference

Run an audit from the dashboard to see what the audit and eval commands return.