Command line
Installing the Python SDK installs the preworld-guard command. python -m preworld_guard runs the same thing. The TypeScript SDK has connection-check only. See TypeScript SDK.
preworld-guard [global options] <command> [command options]Output is JSON on standard output. Error messages never include secret values.
Global options
Global options go before the command.
| Option | Environment variable | Default |
|---|---|---|
--endpoint | PREWORLD_GUARD_ENDPOINT | http://127.0.0.1:8765 |
--token | PREWORLD_GUARD_TOKEN | |
--token-file | PREWORLD_GUARD_TOKEN_FILE | |
--project-id | PREWORLD_GUARD_PROJECT_ID | |
--agent-id | PREWORLD_GUARD_AGENT_ID | python-agent |
--cache | PREWORLD_GUARD_CACHE | .preworld-guard/policy.json |
--token-file names a file that holds the token, used when --token isn't given. It is refused if it is a symlink or others can read it. connection-check and trial-check don't read it: give them the token with --token or PREWORLD_GUARD_TOKEN.
Commands
| Command | What it does | Needs a token |
|---|---|---|
connection-check | Checks a connection package | Yes (executor) |
register | Registers an executor once | Yes (executor) |
policy | Fetches and caches the current policy | Yes (executor) |
heartbeat | Sends one heartbeat | Yes (executor) |
policy-validate | Compiles a policy file | No |
policy-schema | Prints the policy JSON Schema | No |
policy-replay | Replays actions against a policy, locally | No |
mcp-proxy | Runs the MCP proxy | Yes (executor) |
mcp-origin, mcp-manifest | Show and approve MCP upstream and tool digests | Yes |
mcp-auth | Connects, checks or removes a user's OAuth grant to an MCP upstream | A user access token |
sandbox | Runs a command in srt, or checks the host | No |
siem-export | Exports events and the audit log to NDJSON | Yes (viewer) |
diagnose | Writes a diagnostics bundle | Yes (executor) |
trial-init | Creates starter files for a framework | No |
trial-check | Checks that a self-hosted setup is ready | Yes |
onboard | Creates an organization and project on a self-hosted control plane | The bootstrap token |
connection-check
preworld-guard connection-check --config guard-connection.json [--output report.json]Checks the credential, that the executor is online, that the current policy is loaded and that a first event arrived. It runs no business tool. Exit 0 when all four are ready, otherwise non-zero.
register
preworld-guard --project-id "$PREWORLD_GUARD_PROJECT_ID" --token "$PREWORLD_GUARD_TOKEN" register --name support-agent--name (default python-sdk), --version (default: the SDK version). A long-running agent calls guard.start() instead.
policy
Fetches the current policy, checks it and writes the cache. Prints the policy.
heartbeat
Sends one heartbeat for this executor.
policy-validate
preworld-guard policy-validate policy.yamlCompiles a YAML or JSON policy and prints it with its policy_hash. Fails on any schema error.
policy-schema
preworld-guard policy-schema [--output guard-policy.schema.json]policy-replay
preworld-guard policy-replay --policy candidate-policy.json --records actions.json --output replay-report.jsonReplays 1 to 1,000 complete actions (a file up to 2 MiB) against a policy. No tool runs, nothing is sent, and the report holds decisions only. See Publishing a policy.
mcp-proxy
preworld-guard [global options] mcp-proxy --upstream <command...>
preworld-guard [global options] mcp-proxy --upstream-transport streamable-http --upstream-url <url> [--header KEY=VALUE]
preworld-guard [global options] mcp-proxy --config registry.json [--downstream-transport streamable-http ...]| Option | Default | Meaning |
|---|---|---|
--upstream ... | The stdio server command. Must come last | |
--upstream-transport | stdio | stdio, streamable-http or sse |
--upstream-url | For HTTP and SSE | |
--header KEY=VALUE | Upstream header (repeatable) | |
--timeout, --sse-read-timeout | 10, 300 s | Upstream timeouts |
--config | A multi-upstream registry. Can't be combined with the single-upstream options | |
--downstream-transport | stdio | stdio or streamable-http (registry only) |
--listen-host, --listen-port | 127.0.0.1, 8766 | For the HTTP downstream |
--downstream-token | PREWORLD_GUARD_DOWNSTREAM_TOKEN | Bearer token clients must send to the HTTP downstream |
--allowed-host, --allowed-origin | PREWORLD_GUARD_ALLOWED_HOSTS, PREWORLD_GUARD_ALLOWED_ORIGINS | Host and Origin allow lists for the HTTP downstream (repeatable) |
--subject-id | PREWORLD_GUARD_SUBJECT_ID | A trusted service subject, needed for approvals |
--sandbox and --sandbox-* | Run a stdio upstream in srt; see Sandbox |
See MCP proxy.
mcp-origin
preworld-guard mcp-origin --config ./mcp.json --server NAME [--approve SHA256]Shows an upstream's identity digest. With --approve, approves it.
mcp-manifest
preworld-guard mcp-manifest --config ./mcp.json --server NAME --kind tool --name TOOL [--approve SHA256]--kind is tool, resource or resource_template. Shows the current metadata digest. With --approve, approves it.
mcp-auth
preworld-guard mcp-auth connect --upstream finance \
--endpoint https://guard-proxy.example.com --token-file /private/employee-access-tokenconnect, status or disconnect. --endpoint is your MCP proxy's HTTP downstream, not the control plane. The token file holds the user's own access token from your identity provider, not an executor credential. --no-browser prints a one-time link instead of opening a browser. connect exits 0 when authorized. See MCP proxy.
sandbox
preworld-guard sandbox verify --executable tooling/node_modules/.bin/srt
preworld-guard sandbox run --workspace ./workspace --deny-read ~/.ssh -- python agent.pyverify exits 0 only if every probe passes. run passes on the command's exit code. Options are in Sandbox.
siem-export
PREWORLD_GUARD_TOKEN="$GUARD_VIEWER_TOKEN" preworld-guard \
--endpoint https://guard.example.com --project-id "$PREWORLD_GUARD_PROJECT_ID" \
siem-export --output /var/lib/preworld-guard-siem/events.ndjson \
--state /var/lib/preworld-guard-siem/cursor.json--limit (default 500), --max-pages (default 20). See Events, audit and export.
diagnose
preworld-guard [global options] diagnose --framework langchain --output guard-diagnostics.json [--send-ping]Checks the interpreter, the framework package, where the policy came from, the lifecycle and the event queue, and writes a bundle readable only by you. It lists allowed fields only and never reads argument values or environment variable values. --send-ping also sends a diagnostic event. Exit 0 when everything is fine, 2 otherwise.
trial-init
preworld-guard trial-init --framework openai-agents --directory ./guard-trialCreates starter files for python, langchain, langgraph, claude, openai-agents, pydantic-ai, google-adk, agent-framework, llama-index, agno, dspy or crewai. It never overwrites existing files, and tokens in the templates are placeholders.
trial-check
preworld-guard [global options] trial-check [--mcp-config ./mcp.json] [--sandbox-executable srt] [--output report.json]Checks HTTPS to the control plane, the credential, the policy version and the MCP upstream digests, and with --sandbox-executable runs the sandbox probes. With a viewer token (--viewer-token) and a list of expected exits (--expected-exits), it also reports executor, asset and policy coverage. Exit 0 when ready. It doesn't replace a test from the target network that should fail.
onboard
preworld-guard --endpoint https://guard.example.com \
onboard \
--bootstrap-token "$PREWORLD_GUARD_BOOTSTRAP_TOKEN" \
--organization 'Example' \
--project 'support-agent'Self-hosted only. Creates a new organization and project each time it is called and returns the owner token once. See Self-hosted control plane.