CLI Usage
Core commands
Section titled “Core commands”rk init
Section titled “rk init”Initialize the workspace: creates config file, database directory, and seeds the 80-control audit catalog.
rk sync
Section titled “rk sync”Full sync cycle: fetches GitHub org metadata, scans local directories, and rebuilds the FTS index.
# Sync a single orgrk sync --owners my-org
# Sync multiple orgs with local scanningrk 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 reposrk sync --owners my-org --forks
# Archive repos absent from the GitHub listingrk 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.
rk scan <path>
Section titled “rk scan <path>”Scan a single local repository directory for tech fingerprints, docs, and facts.
rk scan /path/to/my-projectrk show <slug>
Section titled “rk show <slug>”Display full knowledge for a repo: metadata, tech stack, notes, relationships, and audit posture.
rk show my-org/my-repoThe 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.
rk list
Section titled “rk list”List all repos with optional filters:
rk list # all reposrk list --language typescript # filter by languagerk list --shape mcp-server # filter by app shaperk list --status active # filter by statusrk find <query>
Section titled “rk find <query>”Full-text search across all indexed content: READMEs, changelogs, notes, descriptions. Use --limit (-n) to control the number of results (default: 10).
rk find "authentication middleware"rk find "react component testing" --limit 20rk related <slug>
Section titled “rk related <slug>”Show repos related to a given repo via mapped relationships.
rk related my-org/my-repork related my-org/my-repo --jsonWhen 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.
rk note <slug>
Section titled “rk note <slug>”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.
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 "..." --deleterk relate <from> <type> <to>
Section titled “rk relate <from> <type> <to>”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.
rk relate my-org/api-gateway depends_on my-org/auth-servicerk relate my-org/new-api supersedes my-org/legacy-api --note "Migration planned Q2"rk stats
Section titled “rk stats”Show database statistics: repo count, notes, docs, facts, relationships, audit runs.
rk reindex
Section titled “rk reindex”Rebuild the FTS5 full-text search index. Use when search results seem stale.
Audit commands
Section titled “Audit commands”rk audit seed-controls
Section titled “rk audit seed-controls”Seed or update the 80-control canonical audit catalog. Safe to run multiple times.
rk audit import <dir>
Section titled “rk audit import <dir>”Import audit results from a directory containing JSON contract files (run.json, controls.json, findings.json, metrics.json).
rk audit posture [slug]
Section titled “rk audit posture [slug]”Show audit posture for one repo or the full portfolio. Posture levels: healthy, needs_attention, critical.
rk audit posture # portfolio overviewrk audit posture my-org/my-repo # single repork audit findings
Section titled “rk audit findings”List open findings across the portfolio:
rk audit findings # all open findingsrk audit findings --severity criticalrk audit findings --domain secretsrk audit controls
Section titled “rk audit controls”List canonical controls, optionally filtered by domain:
rk audit controlsrk audit controls --domain security_sastrk audit unaudited
Section titled “rk audit unaudited”List repos that have never been audited.
rk audit failing <domain>
Section titled “rk audit failing <domain>”List repos that have failing controls in a specific domain.
Sync commands
Section titled “Sync commands”rk sync-dogfood
Section titled “rk sync-dogfood”Sync dogfood evidence from dogfood-lab/testing-os into repo facts. One-way read — testing-os remains the write authority.
# Fetch from GitHub raw URLs (default)rk sync-dogfood
# Use a local testing-os checkoutrk sync-dogfood --local /path/to/testing-osrk suggest-dogfood
Section titled “rk suggest-dogfood”Get dogfood intelligence suggestions for a repo or a product surface. Specify exactly one of --repo or --surface.
rk suggest-dogfood --repo mcp-tool-shop-org/shipcheckrk suggest-dogfood --surface cliLifecycle commands
Section titled “Lifecycle commands”rk delete <slug>
Section titled “rk delete <slug>”Hard-delete a repo and all child rows (cascade). Irreversible. Pass --yes (-y) to skip the confirmation prompt.
rk delete my-org/old-repork delete my-org/old-repo --yesrk archive <slug>
Section titled “rk archive <slug>”Mark a repo archived (lifecycle_status=archived). Preserves notes and findings. Optional: --reason (recorded as a warning note).
rk archive my-org/old-repo --reason "Superseded by my-org/new-repo"rk verify-local
Section titled “rk verify-local”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).
rk verify-localrk verify-local --rig my-rig --strictrk init-rig
Section titled “rk init-rig”Register the current rig in the rigs table. Optional: --id (default: RK_RIG_ID env or hostname), --hostname (default: OS hostname), --root (default: cwd).
rk init-rigrk init-rig --id studio --hostname studio-box --root /path/to/workspacerk prune
Section titled “rk prune”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.
rk prune --days 30rk prune --days 30 --applyPublish-state commands
Section titled “Publish-state commands”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.
rk versions <slug>
Section titled “rk versions <slug>”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).
rk versions my-org/my-repork versions my-org/my-repo --refresh --channel npmrk drift <slug>
Section titled “rk drift <slug>”Compare source-of-truth version (package.json / pyproject.toml) vs registry latest. Optional: --strict (exit non-zero if any drift detected).
rk drift my-org/my-repork drift my-org/my-repo --strictrk bind-package <slug>
Section titled “rk bind-package <slug>”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.
rk bind-package my-org/my-repo --npm @scope/my-repork bind-package my-org/my-repo --pypi my-repo --publisher-method pypi_trustedHealth commands
Section titled “Health commands”rk health / rk health feed
Section titled “rk health / rk health feed”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.
rk healthrk health feed --jsonrk health doctor <slug>
Section titled “rk health doctor <slug>”Single-repo deep-dive: dep audit, CI, actions, and toolchain. Optional: --refresh, --strict, --rig, --json.
rk health doctor my-org/my-repork health doctor my-org/my-repo --jsonrk health table
Section titled “rk health table”Portfolio health table. JSON is the default output. Optional: --refresh, --strict, --rig, --text (pretty-text instead of JSON).
rk health tablerk health table --textOperational commands
Section titled “Operational commands”rk owners
Section titled “rk owners”Manage the rk.config.json owners list:
rk owners listrk owners add my-orgrk owners remove my-orgrk fsck
Section titled “rk fsck”Run DB integrity checks and write a db_health_runs audit row. Optional: --strict (exit non-zero if any check returns count > 0), --json.
rk fsckrk fsck --strict --jsonrk diff <slug>
Section titled “rk diff <slug>”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.
rk diff my-org/my-repork diff my-org/my-repo --since 2026-06-01 --jsonrk runs
Section titled “rk runs”List recent operational runs (db_health_runs from rk fsck, sync_runs from rk sync). Optional: --db-health, --sync, --limit (default: 10), --json.
rk runsrk runs --sync --limit 5 --jsonBackup, restore, and preflight
Section titled “Backup, restore, and preflight”rk backup
Section titled “rk backup”Snapshot the database to a vacuumed copy under data/backups/ (or --out).
rk backuprk backup --out /path/to/snapshot.dbrk restore <path>
Section titled “rk restore <path>”Restore the database from a backup file. Confirm-gated; refuses a newer-schema backup. Pass --yes (-y) to skip the confirmation prompt.
rk restore data/backups/snapshot.dbrk restore /path/to/snapshot.db --yesrk doctor
Section titled “rk doctor”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).
rk doctorrk doctor --json --strictrk config / rk config show
Section titled “rk config / rk config show”Show the resolved effective config with per-field provenance. Optional: --json.
rk configrk config show --jsonrk config validate
Section titled “rk config validate”Validate rk.config.json. Exits non-zero on placeholder owners, bad shapes, or unresolvable paths. Optional: --json.
rk config validateClassification
Section titled “Classification”rk classify <slug>
Section titled “rk classify <slug>”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.
rk classify my-org/my-repo --status active --stage shipped --category toolrk classify my-org/my-repo --stage ""Games commands
Section titled “Games commands”rk games score <worklist>
Section titled “rk games score <worklist>”Score a REMEDIATION-WORKLIST.md file and display a leaderboard. The scoring engine parses the markdown table and awards points for fixed findings.
rk games score REMEDIATION-WORKLIST.mdrk games score REMEDIATION-WORKLIST.md --jsonrk games score REMEDIATION-WORKLIST.md --markdownGlobal options
Section titled “Global options”| Option | Description |
|---|---|
--version |
Show the current version |
--debug |
Show stack traces and verbose output on errors |
--help |
Show help for any command |