@contextecf/guardian-cli

Project Guardian CLI

Project Guardian is a local-first Personal Context Fabric for AI prompt governance, local receipts, policy packs, MCP tools, and browser prompt checks.

One-Line Install

Install the CLI globally, CodeLedger-style:

npm install -g @contextecf/guardian-cli
guardian setup

Then open the Control Tower in your default browser:

guardian launch

The same daemon-backed launch path is also available as:

guardian tower
guardian control-tower

Or run setup without a global install:

npx @contextecf/guardian-cli@latest setup

The installed binary is guardian.

Guardian CLI requires Node.js 20.20.0 or newer. The release clean-room install smoke uses a Node 20 bookworm Docker image so native SQLite dependencies are tested against the same Node floor expected for public npm users.

First Run

guardian setup
guardian doctor
guardian readiness
guardian launch
guardian status
guardian open
guardian policy list
guardian marketplace list
guardian posture list
guardian preferences show
guardian privacy show
guardian mcp install
guardian daemon pair --json
guardian desktop execute --input=/path/to/approved-action.json --yes

guardian setup is the one-command first-run path after npm install -g or through npx. It creates or reuses the local profile, keeps local-first privacy defaults, runs doctor/data checks, writes Guardian-owned MCP snippets under the Guardian profile directory, starts or reuses the local daemon, opens the Control Tower unless --print is supplied, and returns browser-extension setup guidance without printing the runtime token. It does not install the native host manifest or write external AI tool config unless the user runs the explicit follow-up commands.

guardian extension native-host install --extension-id=<id> writes the Guardian browser native messaging helper and manifest. On macOS/Linux it writes the browser manifest path directly. On Windows it writes the helper, .cmd launcher, and manifest under GUARDIAN_HOME/native-host, then prints exact HKCU reg add/reg delete commands for reviewed registration. Windows users can run guardian extension native-host install --extension-id=<id> --write-registry --yes to perform the HKCU registration through argv-based reg add and write a token-free proof that guardian extension native-host status --json can verify.

guardian launch, guardian tower, and guardian control-tower start or reuse the local daemon and then open the Control Tower in the default browser. During the MVP, that daemon exposes a lightweight metadata-only status page at the default URL. Re-running guardian launch, guardian tower, guardian control-tower, or guardian start first checks the requested authenticated loopback health endpoint and reuses the existing daemon when it is already reachable. Use guardian daemon serve when you want the foreground developer process instead. Use guardian launch --print, guardian tower --print, or guardian control-tower --print to print the URL without opening a browser.

guardian open launches the already configured local Control Tower URL in the default browser without starting the daemon. It uses the installed profile/default loopback URL unless supplied with a loopback URL through --url or GUARDIAN_CONTROL_TOWER_URL; it refuses non-loopback URLs.

guardian stop sends an authenticated local loopback request to the running daemon and then marks the runtime stopped in the local profile. It does not print the runtime token and it refuses non-loopback stop URLs.

guardian status reports whether Guardian is installed, which Control Tower URL is configured, and whether the daemon answers an authenticated local health probe. It never prints the local runtime token.

guardian readiness separates the CodeLedger-style npm preview install path from the full production release claim. It reports npm preview readiness from the protected package evidence and npm publish dry-run, while keeping full production release blocked until signed native installers, browser-store distribution, high-risk desktop action execution, and autonomous local app execution are proven. SQLite page-level encryption is proven for the local Personal ECL store when GUARDIAN_SQLITE_PAGE_ENCRYPTION_KEY is configured. Use guardian readiness --strict in operator automation when the command should exit nonzero unless both preview and full production claims are ready.

The daemon-served Control Tower includes a Release & Doctor section that mirrors the local guardian doctor and guardian status evidence: doctor pass/warn/fail counts, protected release evidence status, package metadata, checksum count, and source/source-map/workspace-runtime-import boundary state. It remains metadata-only and does not expose the runtime token.

guardian privacy show reports the local-first privacy posture, including metadata-only defaults, raw content capture, cloud sync, local app autopilot, receipt raw-content state, and pending encryption-at-rest controls. It never prints the local runtime token.

guardian key-store install --yes stores a Guardian local-data key through the platform OS credential store using stdin-only secret input: macOS Keychain, Windows DPAPI, or Linux Secret Service. guardian key-store status, guardian data status, guardian privacy show, and guardian doctor surface only token/key-free proof metadata.

guardian policy list, guardian policy enable <pack-id>, and guardian policy disable <pack-id> let users manage preset policy packs after install. Guardian persists the active selection in profile.json and policy-packs.json, rejects unknown pack IDs, and keeps at least one pack active so the local runtime does not accidentally run without guardrails.

guardian marketplace list, guardian marketplace show <pack-id>, and guardian marketplace submit-template --json expose the first browse-only Policy Pack Marketplace metadata surface. Users and administrators can inspect publisher, distribution class, review status, compatibility, price/license, proven/not-proven claims, limitations, and custom-pack submission shape before connecting anything. Marketplace packs cannot bypass Guardian's local policy engine, confirmation gates, provider/source/app revocations, or receipts.

guardian posture list and guardian posture set <calm|balanced|guided|high_assurance|autopilot_lite> let users manage the superordinate Guardian Posture Profile above individual policy packs and preferences. Guardian persists the selected profile in profile.json and posture-profile.json, shows the behavior preview in Control Tower, and does not silently enable raw capture, cloud sync, or local app autopilot.

guardian preferences show, guardian preferences coach <off|quiet|balanced|hands_on>, and guardian preferences learning <on|off> let users decide how often Prompt Coach should tag along and whether the local Learning Graph is enabled. Guardian persists these choices in profile.json and preferences.json; Prompt Coach opt-out is honored by the local daemon without disabling policy checks.

guardian install, guardian doctor, and guardian mcp install do not print the local runtime token. The token is emitted only by the explicit guardian daemon pair --json handoff command so the browser extension can be paired deliberately.

guardian desktop execute --input=/path/to/approved-action.json --yes is the first conservative desktop adapter. It consumes an approved MCP local-action response, verifies the desktop execution plan hash, requires a second local confirmation flag, refuses high-risk action types, opens only bounded http:// or https:// URL targets in the MVP, emits the guardian_desktop_url_open adapter id/version/capability proof, and writes a metadata-only Personal ECL receipt. It does not execute send/delete/pay/publish/system-change actions.

guardian desktop safety-smoke --json is the release-readiness smoke for this surface. It keeps local app autopilot off, blocks a high-risk send action before adapter invocation, exercises the bounded low-risk desktop-browser open adapter path with a simulated open, and emits token-safe metadata-only receipt and event-chain evidence. It does not authorize autopilot or close a production gate.

Privacy Defaults

Guardian starts local-first:

• raw content capture off
• cloud sync off
• learning graph opt-in
• local app autopilot off
• metadata-only receipts by default

Package Boundary

The npm package publishes bundled CLI/runtime JavaScript, TypeScript declarations, and this README. Guardian workspace packages are bundled into the CLI entrypoints so npx @contextecf/guardian-cli@latest setup can run outside the monorepo. The native SQLite adapter remains a normal better-sqlite3-multiple-ciphers runtime dependency.

Source files, source maps, and source-controlled release gates remain in the private repository and should be validated before broad distribution.

Release operators can run npm run guardian:release:doctor from the repo root for the complete protected-release doctor before publishing. For a release candidate artifact, set GUARDIAN_RELEASE_CANDIDATE=/path/to/artifact.zip and run npm run guardian:release:audit; the audit runs the same doctor and scans the candidate with the protected IP scanner. The audit also honors GUARDIAN_RELEASE_CLAIM; it defaults to preview, while GUARDIAN_RELEASE_CLAIM=production fails until every not-proven production gate is closed in release evidence. Before npm publication, run npm run guardian:npm:publish:dry-run to exercise npm publish --dry-run --json against the packed Guardian CLI tarball and add that result to the npm package evidence. For the final pre-publish operator gate, run npm run guardian:npm:publish:ready; it repeats the protected npm doctor with the dry-run enabled, records readiness evidence, and prints the exact npm publish <tarball> --access public command without executing it.

When an installed profile contains release/release-evidence.json, guardian doctor verifies the protected package evidence schema, expected-file allowlist, source/source-map exclusions, unpublished workspace import boundary, and checksum manifest. guardian status --json surfaces the same metadata-only release-evidence state without printing runtime tokens.