Skip to content

CLI Usage

Initialize the workspace: creates config file, database directory, and seeds the 80-control audit catalog.

Full sync cycle: fetches GitHub org metadata, scans local directories, and rebuilds the FTS index.

Terminal window
# Sync a single org
rk sync --owners my-org
# Sync multiple orgs with local scanning
rk sync --owners org1,org2 --local /path/to/repos
# Cap local scan recursion (default: 4)
rk sync --owners my-org --local /path/to/repos --local-depth 4
# Include release history (slower)
rk sync --owners my-org --releases
# Include forked repos
rk sync --owners my-org --forks
# Archive repos absent from the GitHub listing
rk sync --owners my-org --prune-vanished

--local-depth sets the max recursion depth for --local scanning (default: 4).

--prune-vanished archives repos absent from the GitHub listing. Without the flag, vanished repos are detected and warned only. Use only with a fully-scoped token.

Scan a single local repository directory for tech fingerprints, docs, and facts.

Terminal window
rk scan /path/to/my-project

Display full knowledge for a repo: metadata, tech stack, notes, relationships, and audit posture.

Terminal window
rk show my-org/my-repo

The Relationships section always appears. When no edges are stored it prints No relationships recorded — that is engine state (nothing mapped yet), not a verdict that the repo is isolated or enrichment-complete. rk show never invents relationship edges.

List all repos with optional filters:

Terminal window
rk list # all repos
rk list --language typescript # filter by language
rk list --shape mcp-server # filter by app shape
rk list --status active # filter by status

Full-text search across all indexed content: READMEs, changelogs, notes, descriptions. Use --limit (-n) to control the number of results (default: 10).

Terminal window
rk find "authentication middleware"
rk find "react component testing" --limit 20

Show repos related to a given repo via mapped relationships.

Terminal window
rk related my-org/my-repo
rk related my-org/my-repo --json

When no edges are recorded, the text path prints No relationships recorded for: <slug> and exits successfully. --json emits [] so machine consumers never hit the human sentinel. Both are honest engine state (zero stored rows), not Isolated-OK folklore and not a finished enrichment signal.

MCP related_repos keeps the same empty collection as { "slug": "<slug>", "relationships": [] } so agents can treat [] as incompleteness without a schema break.

Add (or --delete) a note on a repo. --type (-t) is required. --content (-c) is required when adding, not when deleting. Optional: --title (defaults to the note type).

--delete deletes the note identified by --type + --title (the title default is the same as when adding).

Note types: thesis, architecture, convention, warning, next_step, drift_risk, release_summary, command, pain_point, general.

Terminal window
rk note my-org/my-repo --type thesis --content "Core auth service for all org APIs"
rk note my-org/my-repo -t warning -c "Rate limiter is hardcoded" --title "Rate limit config"
rk note my-org/my-repo --type thesis --title "..." --delete

Record a relationship between two repos. Optional: --note to add context.

Types: depends_on, related_to, supersedes, shares_domain_with, shares_package_with, companion_to, wraps, collaborated_in_mission.

Terminal window
rk relate my-org/api-gateway depends_on my-org/auth-service
rk relate my-org/new-api supersedes my-org/legacy-api --note "Migration planned Q2"

Show database statistics: repo count, notes, docs, facts, relationships, audit runs.

Rebuild the FTS5 full-text search index. Use when search results seem stale.

Seed or update the 80-control canonical audit catalog. Safe to run multiple times.

Import audit results from a directory containing JSON contract files (run.json, controls.json, findings.json, metrics.json).

Show audit posture for one repo or the full portfolio. Posture levels: healthy, needs_attention, critical.

Terminal window
rk audit posture # portfolio overview
rk audit posture my-org/my-repo # single repo

List open findings across the portfolio:

Terminal window
rk audit findings # all open findings
rk audit findings --severity critical
rk audit findings --domain secrets

List canonical controls, optionally filtered by domain:

Terminal window
rk audit controls
rk audit controls --domain security_sast

List repos that have never been audited.

List repos that have failing controls in a specific domain.

Sync dogfood evidence from dogfood-lab/testing-os into repo facts. One-way read — testing-os remains the write authority.

Terminal window
# Fetch from GitHub raw URLs (default)
rk sync-dogfood
# Use a local testing-os checkout
rk sync-dogfood --local /path/to/testing-os

Get dogfood intelligence suggestions for a repo or a product surface. Specify exactly one of --repo or --surface.

Terminal window
rk suggest-dogfood --repo mcp-tool-shop-org/shipcheck
rk suggest-dogfood --surface cli

Hard-delete a repo and all child rows (cascade). Irreversible. Pass --yes (-y) to skip the confirmation prompt.

Terminal window
rk delete my-org/old-repo
rk delete my-org/old-repo --yes

Mark a repo archived (lifecycle_status=archived). Preserves notes and findings. Optional: --reason (recorded as a warning note).

Terminal window
rk archive my-org/old-repo --reason "Superseded by my-org/new-repo"

Verify each repo local_path exists on the current rig. Optional: --rig (default: RK_RIG_ID env or hostname), --strict (exit non-zero if any drift detected).

Terminal window
rk verify-local
rk verify-local --rig my-rig --strict

Register the current rig in the rigs table. Optional: --id (default: RK_RIG_ID env or hostname), --hostname (default: OS hostname), --root (default: cwd).

Terminal window
rk init-rig
rk init-rig --id studio --hostname studio-box --root /path/to/workspace

Hard-delete repos archived longer than --days (default: 30). Without --apply, candidates are listed only. Pass --dry-run to show candidates without deleting, or --apply to delete. Do not combine --dry-run and --apply.

Terminal window
rk prune --days 30
rk prune --days 30 --apply

Publish-state is not a registry publish. These commands read npm / PyPI / GitHub Releases and update local inventory. They do not npm publish or upload packages. MCP repo_versions is DB-only (no network refresh); CLI rk versions --refresh may GET registries.

Show the cross-channel published-version dashboard (npm, pypi, github_release). Optional: --refresh (sync from registries before rendering), --strict (exit non-zero if the --refresh sync surfaced errors), --channel (npm|pypi|github_release).

Terminal window
rk versions my-org/my-repo
rk versions my-org/my-repo --refresh --channel npm

Compare source-of-truth version (package.json / pyproject.toml) vs registry latest. Optional: --strict (exit non-zero if any drift detected).

Terminal window
rk drift my-org/my-repo
rk drift my-org/my-repo --strict

Bind npm / PyPI package names and publisher_method on a repo. Specify at least one of --npm, --pypi, --publisher-method. Publisher methods: pypi_trusted, pypi_token, npm_token, npm_trusted, github_release_only, none.

Terminal window
rk bind-package my-org/my-repo --npm @scope/my-repo
rk bind-package my-org/my-repo --pypi my-repo --publisher-method pypi_trusted

Change feed since last sync (default health surface). Optional: --refresh (run build-health sync before rendering), --strict (exit non-zero if the --refresh sync surfaced errors), --rig, --json.

Terminal window
rk health
rk health feed --json

Single-repo deep-dive: dep audit, CI, actions, and toolchain. Optional: --refresh, --strict, --rig, --json.

Terminal window
rk health doctor my-org/my-repo
rk health doctor my-org/my-repo --json

Portfolio health table. JSON is the default output. Optional: --refresh, --strict, --rig, --text (pretty-text instead of JSON).

Terminal window
rk health table
rk health table --text

Manage the rk.config.json owners list:

Terminal window
rk owners list
rk owners add my-org
rk owners remove my-org

Run DB integrity checks and write a db_health_runs audit row. Optional: --strict (exit non-zero if any check returns count > 0), --json.

Terminal window
rk fsck
rk fsck --strict --json

Show DB-entry change history for a repo over a time window (notes, audit runs, dep-audit snapshots, published versions). Optional: --since (default: 7 days ago), --until (default: now), --json.

Terminal window
rk diff my-org/my-repo
rk diff my-org/my-repo --since 2026-06-01 --json

List recent operational runs (db_health_runs from rk fsck, sync_runs from rk sync). Optional: --db-health, --sync, --limit (default: 10), --json.

Terminal window
rk runs
rk runs --sync --limit 5 --json

Snapshot the database to a vacuumed copy under data/backups/ (or --out).

Terminal window
rk backup
rk backup --out /path/to/snapshot.db

Restore the database from a backup file. Confirm-gated; refuses a newer-schema backup. Pass --yes (-y) to skip the confirmation prompt.

Terminal window
rk restore data/backups/snapshot.db
rk restore /path/to/snapshot.db --yes

Environment preflight: config, DB, schema version, gh auth, current rig, recent sync/fsck runs. Distinct from rk health doctor <slug>. Optional: --json, --strict (exit non-zero when any check is red).

Terminal window
rk doctor
rk doctor --json --strict

Show the resolved effective config with per-field provenance. Optional: --json.

Terminal window
rk config
rk config show --json

Validate rk.config.json. Exits non-zero on placeholder owners, bad shapes, or unresolvable paths. Optional: --json.

Terminal window
rk config validate

Set curated status, stage, and category. These fields are not populated by sync or scan. Status: active, paused, archived, unknown. Category: product, tool, library, experiment, blueprint, marketing. Pass "" to clear stage or category.

Terminal window
rk classify my-org/my-repo --status active --stage shipped --category tool
rk classify my-org/my-repo --stage ""

Score a REMEDIATION-WORKLIST.md file and display a leaderboard. The scoring engine parses the markdown table and awards points for fixed findings.

Terminal window
rk games score REMEDIATION-WORKLIST.md
rk games score REMEDIATION-WORKLIST.md --json
rk games score REMEDIATION-WORKLIST.md --markdown
Option Description
--version Show the current version
--debug Show stack traces and verbose output on errors
--help Show help for any command