@imladri/cli

Customer CLI for Imladri Profile setup, agent wrapping, proof runs, scanner upload, and buyer evidence export.

The CLI does not mock the runtime. It calls the same local Glasshouse endpoints used by the Profile console and SDK paths.

Install

Recommended npm install:

npm install @imladri/cli @imladri/sdk
npx imladri doctor --customer --worker-url https://imladri-beta-api.imladri.workers.dev --remediate

For local repository development:

powershell -ExecutionPolicy Bypass -File .\scripts\install-imladri-cli.ps1

To build a local beta tarball instead of linking the working tree:

powershell -ExecutionPolicy Bypass -File .\scripts\package-imladri-cli-beta.ps1
npm install -g .\dist\beta\imladri-cli-0.2.1.tgz

Manual fallback:

npm link .\cli

Then run:

npx imladri init
npx imladri doctor --customer --worker-url https://<worker> --remediate
npx imladri onboard --signup --sandbox --worker-url https://<worker> --email <customer-email> --password <password> --scan-path . --proof-format json --proof-output imladri-proof.json
npx imladri profile login --worker-url https://<worker> --email <customer-email> --password <password>
npx imladri profile rotate-key
npx imladri policy publish
npx imladri sandbox --profile --worker-url https://<worker> --agent-id <profile-agent-id> --sdk-key <profile-sdk-key>
npx imladri start
npx imladri agent init --runtime openclaw
npx imladri agent init --runtime mcp
imladri agent verify --samples 100
imladri scan --format sarif --output imladri-boundary.sarif
imladri scan --path . --fail-on new --upload
imladri monitor
imladri doctor --customer --worker-url https://<worker>
imladri doctor --public --site-url https://imladri.com
imladri proof run --allowed-action ticket.summarize --blocked-action credential.export --stack "LangChain" --proof-need "Show blocked-before-body proof"
imladri proof export --format json --output imladri-proof.json
imladri proof export --format markdown --output imladri-proof.md
imladri proof verify --input imladri-proof.json
imladri proof share --ttl-days 30 --verify-public
imladri demo

Recommended customer path:

1. Run hosted doctor from the customer repo to confirm the Worker, proof registry, and public verifier are reachable.
2. Run imladri onboard --signup --sandbox for the first proof trial account, or omit --signup when the Profile account already exists.
3. Confirm Profile shows the same active agent, monitored activity, scanner evidence, DB sandbox activity when selected, proof readiness, and public buyer/auditor proof share.
4. Use imladri scan --upload or imladri sdk certify --real --upload again when the buyer needs refreshed repository or adapter evidence.

imladri demo runs:

1. doctor
2. wrap
3. sandbox

Proof artifacts are written under tmp/imladri-package/<command>-<timestamp>/.

Commands

• imladri init: write a local non-secret config template and setup checklist.
• imladri onboard: run customer signup/login, SDK key setup, policy publish, runtime evidence, terminal proof run, scanner upload, optional DB sandbox proof, monitor, proof export, public proof share, and optional advanced provider checks from one command.
• imladri profile signup: create the customer Profile account, active agent, and local session for the Free Proof Trial path.
• imladri profile login: authenticate to the customer Profile API and store the local session under ignored .imladri/.
• imladri profile rotate-key: create a customer SDK key and save it locally for CLI proofs without printing the raw key.
• imladri profile status: show the active Profile agent, policy state, SDK key state, and next commands.
• imladri policy publish: save and publish the active agent policy from current Profile state or terminal flags.
• imladri doctor --fix --strict: build missing service artifacts, start local services when needed, and verify service health, SDK config, and DB target wiring.
• imladri doctor --customer --worker-url https://<worker>: check the hosted customer API catalog, advertised rate limits, Profile readiness when logged in, public verifier, and proof trust registry. Add --remediate to print fix notes for every check, including passing/skipped checks.
• imladri doctor --public --site-url https://imladri.com: check only the public proof verifier and static trust registry without requiring a Profile worker.
• imladri start: start Constitution Service, Glasshouse, and GlassPulse locally.
• imladri wrap: run one allowed and one blocked preflight through the wrapper boundary.
• imladri sandbox: run DB sandbox create, transaction, proof export, and destroy.
• imladri agent init --runtime openclaw|hermes|mcp|custom: generate runtime config, print required env vars, test the adapter endpoint, and run a local shared-policy proof.
• imladri agent verify --samples 100 --concurrency 100: run the CI-safe joint OpenClaw, Hermes, MCP, and Generic HTTP parity proof.
• imladri provider validate|deployments|sync|stop: validate customer-owned provider keys and operate provider deployments without storing provider secrets.
• imladri training launch|status|sync|stop: launch and manage provider-backed protected training proof runs.
• imladri monitor: print active agent state, recent activity, provider deployments, boundary scan status, and proof readiness.
• imladri proof export: download JSON, Markdown, PDF, redacted, or auditor proof packets from Profile.
• imladri proof verify: locally verify a JSON proof export or public auditor sample for digest, public signature when present, and hash-chain integrity.
• imladri proof share: create and optionally verify an auditor-redacted public proof link from the Profile proof workspace.
• imladri scan: scan Python/TypeScript/JavaScript agent code for missing Imladri runtime boundaries and detector findings. It emits text by default, --format json, --format sarif, or --format markdown for remediation reports. Detector lanes cover prompt injection, secrets, PII, URL risk, unsafe content, custom topics, and tool-argument risk.
• imladri demo: run the complete packaged proof path.
• imladri stop: stop services managed by start_all.py.

For loopback local demos against http://127.0.0.1:4000, the CLI uses the Glasshouse development auth pair agent-001 / beta-key-001 if no explicit credentials are set. Non-local URLs require explicit credentials.

Agent Runtime Path

Use this path when a partner wants OpenClaw, Hermes, an MCP tool host, or a custom agent wired through the same runtime boundary.

imladri agent init --runtime openclaw
imladri agent init --runtime hermes
imladri agent init --runtime mcp --endpoint http://127.0.0.1:8800/mcp/agent
imladri agent init --runtime custom --endpoint http://127.0.0.1:8799/custom/agent
imladri agent verify --samples 100 --concurrency 100

agent init writes .imladri/agents/<runtime>/agent-runtime.config.json, .imladri/agents/<runtime>/agent-runtime.env.example, .imladri/agents/<runtime>/agent-runtime-local-proof.json, and .imladri/agents/<runtime>/agent-runtime-dashboard-evidence.json. It checks the local adapter endpoint unless --skip-connect is passed, runs a local shared-policy proof unless --skip-proof is passed, and emits a dashboard-ready evidence packet with runtime, endpoint, connection, proof summary, evidence events, and proof digest.

If IMLADRI_AGENT_EVIDENCE_URL and IMLADRI_SDK_KEY are set, agent init also uploads that same dashboard evidence packet to the customer Profile Agent tab. The endpoint is:

$env:IMLADRI_AGENT_EVIDENCE_URL = "https://<worker>/api/customer/agents/<agent-id>/runtime-evidence"
$env:IMLADRI_SDK_KEY = "<profile-sdk-key>"
imladri agent init --runtime openclaw --agent-id <agent-id>

The same sync can be passed as flags when a partner does not want to export environment variables:

imladri agent init --runtime hermes --agent-id <agent-id> --evidence-url "https://<worker>/api/customer/agents/<agent-id>/runtime-evidence" --sdk-key "<profile-sdk-key>"

The CLI never prints the SDK key. If the sync variables are not set, the JSON file remains the manual Profile import fallback.

Customer Profile Path

Use this path when a design partner should install once, run proof from their own repo, and use Profile for monitoring, proof review, and buyer sharing:

imladri onboard --signup --sandbox --worker-url https://<worker> --email <customer-email> --password <password> --scan-path . --proof-format json --proof-output imladri-proof.json

onboard is the recommended first-run path. It writes the local config template, creates or logs into the saved Profile session, uses the local SDK key from signup or rotates one when needed, publishes the active Profile policy, generates runtime evidence, runs one allowed and one blocked-before-body terminal proof, uploads a boundary scan, optionally runs hosted DB sandbox create -> transaction -> proof -> destroy, prints monitoring state, exports proof, and creates a public auditor-redacted proof link. When --sandbox is selected, DB sandbox evidence is recorded before monitor/proof export/share so the buyer packet can include it. By default, onboard skips the live adapter connection probe unless --endpoint or --connect is passed, so a customer can complete Profile-side setup before running a local agent bridge. Pass --skip-proof-share only when the customer wants the proof to stay private.

The same flow can be expanded for advanced provider checks without launching provider workloads:

imladri onboard --advanced --provider runpod --provider-key <runpod-api-key>

Launch provider training only when explicitly requested:

imladri onboard --advanced --launch-training --confirm-paid-provider-run --provider runpod --provider-key <runpod-api-key>

The manual equivalent is:

imladri profile login --worker-url https://<worker> --email <customer-email> --password <password>
imladri profile rotate-key
imladri profile status
imladri policy publish --allow ticket.summarize,db.sandbox.read --block credential.export,file.delete --review cloud.deploy,db.sandbox.review_write
imladri agent init --runtime openclaw --agent-id <profile-agent-id>
imladri proof run --allowed-action ticket.summarize --blocked-action credential.export --stack "OpenClaw" --proof-need "Show the buyer this action is blocked before the function body runs"
imladri scan --path . --config .imladri-scan.json --fail-on new --upload
imladri sandbox --profile --target-id northwind --action-type db.sandbox.read
imladri monitor
imladri proof export --format json --output imladri-proof.json
imladri proof export --format markdown --output imladri-proof.md
imladri proof verify --input imladri-proof.json
imladri proof share --ttl-days 30 --verify-public

profile login stores the customer session in .imladri/customer-session.json, which is ignored by this repository. profile rotate-key stores the one-time SDK key in that same local session so follow-up commands can upload scan evidence, sync runtime evidence, and launch training without pasting the key repeatedly. Set IMLADRI_CUSTOMER_SESSION_PATH when an operator, CI job, or smoke test needs an isolated session file instead of the default project-local session. Provider API keys are different: RunPod and Vast.ai keys stay customer-owned and must be passed through --provider-key, RUNPOD_API_KEY, VAST_API_KEY, or IMLADRI_PROVIDER_API_KEY whenever a provider operation needs them.

Use imladri doctor --customer after login to confirm the API catalog, readiness route, active SDK-key metadata, public verifier, and trust registry are reachable before sending a proof packet to a buyer. Before login, hosted doctor still checks the public and Worker surfaces, and reports authenticated readiness as skipped rather than failed. Use imladri doctor --public when you only need the public verifier and static trust registry.

agent verify checks one shared Imladri constitution across OpenClaw, Hermes, an MCP tool-host adapter, and a Generic HTTP custom-agent adapter: mixed-runtime prohibited actions, cross-runtime delegation, shared halt state, strict-preflight transport failure, clean adapter bootstrap, and one normalized evidence schema. The installed CLI includes a self-contained verifier, so this works from a clean npm folder without repository-local scripts.

For a fresh-folder packaging smoke that also starts the local bridge processes:

node scripts/verify-agent-runtime-clean-install.mjs --samples 100 --concurrency 100

The clean-install smoke packs the CLI, installs it in a fresh npm workspace, starts local OpenClaw, Hermes, MCP, and Generic HTTP bridge processes, runs imladri agent init for all four runtimes, verifies each dashboard evidence packet and profile-sync contract, then runs the shared policy proof. CI uses a TCP OpenClaw gateway stub by default so the package test is stable; pass --start-openclaw-gateway when you want it to launch the local lab gateway. The dedicated GitHub Actions gate is .github/workflows/agent-runtime-installer.yml.

For a recording-friendly local demo that starts the bridge processes, publishes one shared policy, runs allowed and denied actions on the supported runtimes, and writes one proof packet:

node scripts/run-agent-runtime-parity-demo.mjs --samples 100 --concurrency 100

Boundary Scanner

Use this path when a team wants a CI-native guardrail without depending on a GitHub-specific action:

imladri scan --format text
imladri scan --format json --output imladri-boundary-report.json
imladri scan --format sarif --output imladri-boundary.sarif
imladri scan --path . --config .imladri-scan.json --fail-on new
imladri scan --path . --update-baseline
imladri scan --upload --worker-url https://<worker> --agent-id <profile-agent-id>
imladri scan init-ci --provider gitlab --output .gitlab-ci-imladri.yml

The scanner looks for common agent frameworks and risky action patterns, then flags files where it cannot see an Imladri boundary such as SDK adapters, agent.action, tool_call / toolCall, or an explicit preflight(...). Use --fail-on warning when you want CI to fail on advisory findings too, or --fail-on new with a baseline when you want to block only newly introduced findings. Use --fail-on none for onboarding runs where the scan should upload evidence without failing the terminal session.

imladri scan init-ci writes runner-native snippets for GitHub Actions, GitLab, CircleCI, Buildkite, Vercel, Bitbucket, and Azure DevOps. The runner is just the execution environment; the proof upload always lands in the Imladri Profile.

Scanner config lives in .imladri-scan.json by default. It supports:

• baseline: path to an imladri.scan-baseline.v1 file.
• exclude: glob patterns for generated folders and caches.
• allow: scoped suppressions by paths, rules, or levels.

The scanner accepts UTF-8 config files with or without a byte-order mark, which keeps PowerShell-created .imladri-scan.json files usable in clean customer folders.

Provider Training Path

Use this path when a customer wants the advanced GPU/provider proof add-on:

imladri onboard --advanced --provider runpod --provider-key <runpod-api-key>
imladri policy publish
imladri provider validate --provider runpod --provider-key <runpod-api-key>
imladri training launch --provider runpod --provider-key <runpod-api-key> --confirm-paid-provider-run
imladri training sync --provider runpod --provider-key <runpod-api-key>
imladri training status
imladri training stop --deployment-id <profile-deployment-id> --provider-key <runpod-api-key> --delete
imladri proof export --format json --output training-proof.json

training launch uses a safe default manifest unless --manifest is provided, prints the provider, GPU, budget cap, runtime cap, auto-shutdown state, and proof output paths, then refuses to launch provider compute unless the explicit --confirm-paid-provider-run confirmation flag is present. The launch payload includes the Profile SDK key, provider key, workload, image, start command, GPU, budget, runtime cap, and proof output paths. The provider key is sent to the Worker for that one operation and is not stored by Imladri. If cleanup ever fails, use:

imladri training stop --provider runpod --deployment-id <profile-deployment-id> --provider-key <runpod-api-key> --delete

Run imladri scan --path . --update-baseline only when intentionally accepting the current full-repo finding set. Normal CI should run with --fail-on new. With --upload, the scanner posts an imladri.boundary-scan.v1 report into the customer Profile proof workspace. It is Imladri-native: any CI system can run it as long as IMLADRI_AGENT_ID, IMLADRI_SDK_KEY, and either IMLADRI_WORKER_URL or --worker-url are present.

SDK Adopter Matrix

Use the certification matrix when a buyer asks which frameworks are covered:

imladri sdk certify --real --output logs/sdk-certification-profile-proof.json
imladri sdk matrix --input logs/sdk-certification-profile-proof.json --output docs/sdk-adopter-certification-matrix.md
node scripts/write-buyer-proof-packet.mjs --output logs/buyer-proof-packet.md

The matrix separates wrapper-contract lanes from real-package smoke lanes and marks hosted-only or heavyweight lanes as review items instead of failures. The buyer packet generator reads the latest proof/share artifacts and writes a non-committed Markdown packet for sales or security review.

DB Sandbox Design-Partner Path

Use this path when a partner wants to verify governed database branches without touching the Profile UI.

imladri init
imladri doctor --fix --strict
$env:IMLADRI_API_URL = "http://127.0.0.1:4000"
$env:IMLADRI_AGENT_ID = "agent-001"
$env:IMLADRI_SDK_KEY = "beta-key-001"
$env:IMLADRI_DB_TARGET_ID = "northwind"
$env:IMLADRI_DB_ACTION_TYPE = "db.sandbox.write"
$env:IMLADRI_DB_TABLES = "public.customers"
$env:IMLADRI_DB_CLONE_STRATEGY = "storage_branch"
$env:IMLADRI_DB_SQL = "INSERT INTO public.customers (customer_id, company_name, country) VALUES ($1, $2, $3)"
$env:IMLADRI_DB_PARAMS = '["IZ999","Imladri sandbox demo","USA"]'
imladri sandbox

The successful path is:

1. Create a governed branch from the configured DB target.
2. Run the SQL only inside the branch.
3. Export JSON and Markdown proof.
4. Destroy the branch and confirm source mutation count stays zero.

Artifacts are written under tmp/imladri-package/sandbox-<timestamp>/. The local northwind target must be present in the Glasshouse database target config before imladri sandbox can pass against a real backend.