opensoyce

Review one exact change, preserve the evidence behind that review, and — when you choose to — hand the exact snapshot into a durable review record. The opensoyce CLI is the developer- and buyer-facing surface of OpenSoyce's evidence spine, in your own shell.

Code Review is the recurring entry point. It is not the whole CLI: the same binary verifies signed evidence packets and review receipts offline, reads dependency and trust posture, captures runtime/CI and crypto-posture observations, and supports compliance-evidence workflows. Those are documented below.

Install

# One-off
npx opensoyce pr-walkthrough https://github.com/owner/repo/pull/123

# Global
npm i -g opensoyce
opensoyce --version

Zero runtime dependencies. Node >= 18.17.

Review a pull request

opensoyce pr-walkthrough https://github.com/owner/repo/pull/123

The pull request's base and head commit OIDs are captured first, and the diff is fetched by an immutable commit-addressed compare of exactly those OIDs — so a force-push during the run cannot change the bytes you reviewed, and nothing is emitted if the pull request moved.

What is verified, and what is not. The artifact's identity (repository, pull-request number, head OID) and its structural honesty checks are verified, and nothing is written if they fail. The clusters, explanations and risk findings are generated inference from the provider model you choose. They are a reviewer's starting point — not observed fact, not approval, and not a correctness, safety, or compliance decision.

What it needs. The GitHub CLI (gh), authenticated for the target repository. Generating a walkthrough additionally requires your own credential for a supported provider, because that is the step which calls a model. --dry-run does not require a provider credential — it makes no AI model call — though it still reads GitHub and is not an offline command. Public repositories are free; private repositories require an active OpenSoyce License Record.

# Size the run first. Needs no provider credential: it makes no AI model call.
# It still reads GitHub — it resolves the pull request and fetches the exact
# base...head compare — so it is not an offline command.
opensoyce pr-walkthrough https://github.com/owner/repo/pull/123 --dry-run

Durable review handoff. With an explicit --vault-submit, a finished walkthrough snapshot can be submitted to one exact durable Vault review instead of staying a local file. It is opt-in, requires a scoped machine credential from opensoyce login --machine, and is bound to the specific review and head it names. Run opensoyce pr-walkthrough --help for the exact arguments and the credential setup — a submit does not succeed without them. A stored snapshot is not approval, evidence, or a reviewer decision.

Verify a review receipt (offline)

Download review-receipt-v3.json from the sample or from a review, then verify its exact local bytes:

opensoyce receipt verify ./review-receipt-v3.json
opensoyce receipt verify ./review-receipt-v3.json --json

This command reads one local file, makes no network request, needs no account or key lookup, and writes no files. It reports schema, canonical-form, digest, attestation, and doctrine states separately. Exit 0 requires a supported schema, canonical bytes, a matching digest, and clean doctrine. Those component states are integrity facts, not a trust, approval, safety, compliance, or merge-readiness verdict.

Verify a signed evidence packet (buyer / auditor workflow)

What verification means — and does not mean: verifying a packet confirms integrity and origin only — that the named producer produced exactly this content and it was not altered. It does not prove software safety, trust, approval, compliance, quantum safety, PQC compliance, or migration completion. Your policy decides sufficiency.

A vendor sends you a signed evidence bundle (or you download one from a packet share link). Verify it offline:

# Resolves the published OpenSoyce signing key from
# https://www.opensoyce.com/.well-known/opensoyce-signing-key.pem
opensoyce verify --packet bundle.json

# Fully offline: supply the public key yourself
opensoyce verify --packet bundle.json --pubkey opensoyce-signing-key.pem

• VALID means the Ed25519 signature matches the canonical packet bytes under the named key — integrity and origin, nothing more.
• Dual signatures: packets signed since dual signing went live also carry an ML-DSA-87 (FIPS 204) co-signature over the same canonical bytes. This zero-dependency build reports the co-signature's presence (algorithm + key fingerprint) and verifies Ed25519; use the offline verifier script or /api/verify-report for per-algorithm co-signature verification. A co-signature covers signature longevity; it is not a quantum-safety claim about the software. Each packet's signature block states exactly which algorithms signed it.
• The published key set (Ed25519 and ML-DSA-87 key ids, fingerprints, lifecycle status) lives at https://www.opensoyce.com/.well-known/opensoyce-signing-keys.json. Key status is provenance context, never a trust verdict.

Read commands

| Command | What it reads | |---|---| | opensoyce check <pkg> | Current gate decision for one package | | opensoyce lockfile [path] | Per-entry gate decision for an npm lockfile (v0 supports package-lock.json) | | opensoyce trust <owner>/<repo> | Per-repo trust posture from the deployed Dashboard | | opensoyce timeline [--package <p>] [--pr <n>] | Recorded trust-decision events | | opensoyce why <pkg> | Current decision plus the timeline events that produced it |

Capture commands (local evidence)

| Command | What it does | |---|---| | opensoyce observe install -- <cmd> | Observe a dependency change at install time (writes only your --out file) | | opensoyce observe ci ... -- <cmd> | Attribute a CI run's dependency change (writes only your --out file) | | opensoyce observe crypto <file...> | Parse-only crypto posture observation over files you explicitly supply | | opensoyce packet share ... | Mint a share link for a signed bundle (requires opensoyce login) | | opensoyce packet share --review-recap <file> | Attach a Review Evidence Recap (an opensoyce-review-recap v1 JSON object) to the minted share; it appears on the workspace's live Review Evidence Recap panel |

Observe commands are OBSERVE-ONLY: they never block, never enforce, never decide, and write only the files you name with --out / --markdown. An observation is evidence for review, never a verdict.

A Review Evidence Recap attached with --review-recap preserves what was observed during a code review — what changed, what was checked, what gaps remain, what questions are open; it is never a code-safety verdict, trust score, approval, or merge gate. The CLI shape-checks the file; the server validates it with the shared recap validator before storing, and an invalid recap refuses the mint.

Claim Support (local validation + export preview)

opensoyce claim-support --packet ./claim-support.json --out ./dist/claim-support

Validates an opensoyce-claim-support-packet v1 JSON file through the shared claim-support core and writes two LOCAL files: claim-support.review.md (a review-safe markdown export) and claim-support.signed-payload.json (a digest-covered signed payload object). Nothing is uploaded, stored server-side, or shared — the command is local-first and offline. The claim-support runtime ships inside the packaged CLI (byte-exact copies of the shared modules), so it works from a plain install as well as a repository checkout.

An invalid packet is refused (exit 1) and nothing is written. The customer claim inside the packet is preserved verbatim; it is never an OpenSoyce statement. A Claim Support Packet is never a compliance determination — evidence may support a claim; evidence never proves a claim by itself. The written payload's signature meaning is integrity and origin only; a reviewer or auditor decides sufficiency. This command never mints a final artifact.

Boundaries

• Verification and reads never write to your filesystem; capture commands write only the output files you explicitly name.
• Read commands are public and unauthenticated. Vault workflows (packet share, exception, findings import) require opensoyce login (device-code flow); the CLI never stores raw tokens beyond its session file.
• The CLI does not run a parallel gate, does not open PRs, and does not modify lockfiles.
• The CLI does not become the trust record.

Flags

| Flag | Purpose | Default | |---|---|---| | --json | Machine-consumable JSON output | off | | --no-color | Disable ANSI color in default output | off (auto-detect TTY) | | --api-base <url> | Override the public API base URL | https://www.opensoyce.com | | --timeout <ms> | Network timeout for remote calls | 10000 | | --quiet / -q | Suppress non-error stdout in default mode | off | | --help / -h | Show help | off | | --version | Print the CLI version | off |

Exit codes

| Code | Meaning | |---|---| | 0 | All evaluated packages returned ALLOW (or read-only command succeeded) | | 1 | At least one package returned BLOCK | | 2 | At least one package returned WARN, no BLOCKs | | 3 | A queried repo or package has no recorded posture (NOT_EVALUATED) | | 4 | Network error or remote failure | | 5 | Usage error (unknown command, missing arg, bad flag) |

License

Proprietary. See LICENSE.md for the full grant and restrictions — use requires an active, valid OpenSoyce License Record. Redistribution, modification, or resale is not granted without permission.

Doctrine

Verification confirms integrity and origin only. A valid signature is not a green trust state, a generated walkthrough is inference rather than observed fact, an observation is not a verdict, and the buyer's policy decides how to evaluate the evidence. The CLI reads the trust record at https://opensoyce.com/opensource-trust; it does not become the trust record.