@repopilotapp/cli

Privacy-first RepoPilot preflight and postflight checks for a local workspace.

Published as @repopilotapp/cli — the @repopilot scope was already taken on npm, so the package lives under the account's own @repopilotapp scope.

Run

Node.js 20 or newer is required.

npx -y @repopilotapp/cli preflight [email protected] --dry-run
npx -y @repopilotapp/cli preflight [email protected] --repo vercel/next.js
npx -y @repopilotapp/cli preflight [email protected] --policy strict
npx -y @repopilotapp/cli postflight --dry-run
npx -y @repopilotapp/cli postflight --base origin/main --no-repo
npx -y @repopilotapp/cli postflight --evaluation repopilot-evaluation.json --checks repopilot-checks.json

preflight accepts at most 10 explicit npm package or owner/repo targets. It reads bounded structured facts from the workspace's root package.json and package-lock.json. An exact name@version uses project-aware evaluate_dependency_change; a bare name falls back to the lean repository-level check. Manifest/lock bodies and local path ranges are never sent. The first exact-version request includes only the target; if its returned metadata names peers, one follow-up may add only locally relevant peer versions. --policy selects permissive, balanced (default), or strict; arbitrary policy objects are not accepted. Registry install-hook evidence contains only the names preinstall, install, and postinstall, never their bodies.

postflight accepts at most 250 files. It uses NUL-delimited Git output and sends repository-relative paths, statuses, additions, deletions, and optional previous paths. It never obtains or sends diff hunks or source content. Untracked and binary files are represented with unknown counts rather than read.

To close an exact dependency proof loop from the command line, save one preflight JSON receipt, make the change, run the requested checks yourself, and pass their bounded receipts to postflight:

npx -y @repopilotapp/cli preflight [email protected] --json > repopilot-evaluation.json
# Update the manifest/lockfile, then run the requested checks locally.
npx -y @repopilotapp/cli postflight \
  --evaluation repopilot-evaluation.json \
  --checks repopilot-checks.json

repopilot-checks.json is an array of caller assertions, not captured command output:

[
  { "id": "test", "command": "npm test", "exit_code": 0, "summary": "Passed" }
]

Receipt paths must be relative to the pinned workspace root. The CLI rejects traversal, symlinks, non-files, oversized inputs, multiple evaluation contexts, unknown verification-context fields, and unknown check fields such as stdout, stderr, or log paths. A full preflight JSON result is accepted, but only its single verification_context is sent. --checks requires --evaluation; omit it when no command receipts are available.

--dry-run performs every local validation and prints the exact proposed remote tool calls without connecting to RepoPilot.

Without --json, the CLI prints a compact receipt instead of dumping the full MCP payload. Preflight receipts name the exact target, recommendation, confidence, blockers/warnings, evidence gaps, required proof commands, and a short evaluation ID. Postflight receipts separate caller-asserted dependency verification from the independent change-shape risk score. Use --json when a machine needs the full evidence object or verification context.

MCP stdio companion

Clients that require a local command can launch:

{
  "mcpServers": {
    "repopilot": {
      "command": "npx",
      "args": ["-y", "@repopilotapp/cli", "mcp"]
    }
  }
}

The server dynamically proxies the hosted MCP tools and adds workspace_preflight and workspace_postflight. The workspace root is resolved and pinned once when the process starts; tools cannot select a different path. In MCP mode stdout is reserved for protocol frames and diagnostics use stderr.

Privacy boundary

Data sent by default:

• Exact npm target versions, runtime/package-manager facts, script names, manifest/lock paths and lock digest, plus only target/relevant-peer versions.
• Explicit normalized GitHub owner/repo targets.
• Relative changed-file paths, statuses, and line counts.
• With --evaluation, the bounded verification context emitted by RepoPilot; with --checks, check IDs, command strings, exit codes, and short summaries.
• The normalized public owner/repo slug for postflight unless --no-repo or includeRepo: false is used.

Never sent:

• Raw diffs, source files, manifest bodies, or lockfile bodies.
• Captured stdout/stderr, test logs, or the outer preflight receipt body.
• Local path-based dependency ranges or unrelated dependency inventory.
• Absolute paths, environment variables, commit messages, or arbitrary Git configuration.
• Git remote URLs or credentials. A recognized GitHub remote is reduced to its owner/repo slug; unrecognized remotes are omitted.

Filenames are metadata and can themselves be sensitive. Use --dry-run to inspect them or --no-repo to omit repository identity.

Configuration

• REPOPILOT_MCP_URL: hosted MCP URL. HTTPS is required, except HTTP on localhost for development.
• REPOPILOT_BASE_URL: base URL fallback; /api/mcp is appended.
• REPOPILOT_API_KEY: optional bearer token. It is used only as an HTTP header.
• REPOPILOT_OWNER_SECRET: optional. Set it to the deployment's RP_MCP_OWNER_SECRET to label this client's calls as the owner's own traffic, so your own usage is not counted as external adoption. Sent as the x-repopilot-owner header, kept separate from REPOPILOT_API_KEY so metering identity and owner labelling stay independent. It selects a telemetry cohort only — it grants no rate-limit, budget, or authorization privilege. Leave it unset if you are not the deployment owner.
• REPOPILOT_TIMEOUT_MS: request timeout from 1,000 to 120,000 ms; default 15,000.

The hosted MCP 2.2 contract accepts the structured files payload used by postflight. Raw-diff and pull-request inputs remain available to hosted clients for compatibility.