Skip to content

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.

sh
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.

OptionEnvironment variableDefault
--endpointPREWORLD_GUARD_ENDPOINThttp://127.0.0.1:8765
--tokenPREWORLD_GUARD_TOKEN
--token-filePREWORLD_GUARD_TOKEN_FILE
--project-idPREWORLD_GUARD_PROJECT_ID
--agent-idPREWORLD_GUARD_AGENT_IDpython-agent
--cachePREWORLD_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 ​

CommandWhat it doesNeeds a token
connection-checkChecks a connection packageYes (executor)
registerRegisters an executor onceYes (executor)
policyFetches and caches the current policyYes (executor)
heartbeatSends one heartbeatYes (executor)
policy-validateCompiles a policy fileNo
policy-schemaPrints the policy JSON SchemaNo
policy-replayReplays actions against a policy, locallyNo
mcp-proxyRuns the MCP proxyYes (executor)
mcp-origin, mcp-manifestShow and approve MCP upstream and tool digestsYes
mcp-authConnects, checks or removes a user's OAuth grant to an MCP upstreamA user access token
sandboxRuns a command in srt, or checks the hostNo
siem-exportExports events and the audit log to NDJSONYes (viewer)
diagnoseWrites a diagnostics bundleYes (executor)
trial-initCreates starter files for a frameworkNo
trial-checkChecks that a self-hosted setup is readyYes
onboardCreates an organization and project on a self-hosted control planeThe bootstrap token

connection-check ​

sh
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 ​

sh
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 ​

sh
preworld-guard policy-validate policy.yaml

Compiles a YAML or JSON policy and prints it with its policy_hash. Fails on any schema error.

policy-schema ​

sh
preworld-guard policy-schema [--output guard-policy.schema.json]

policy-replay ​

sh
preworld-guard policy-replay --policy candidate-policy.json --records actions.json --output replay-report.json

Replays 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 ​

sh
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 ...]
OptionDefaultMeaning
--upstream ...The stdio server command. Must come last
--upstream-transportstdiostdio, streamable-http or sse
--upstream-urlFor HTTP and SSE
--header KEY=VALUEUpstream header (repeatable)
--timeout, --sse-read-timeout10, 300 sUpstream timeouts
--configA multi-upstream registry. Can't be combined with the single-upstream options
--downstream-transportstdiostdio or streamable-http (registry only)
--listen-host, --listen-port127.0.0.1, 8766For the HTTP downstream
--downstream-tokenPREWORLD_GUARD_DOWNSTREAM_TOKENBearer token clients must send to the HTTP downstream
--allowed-host, --allowed-originPREWORLD_GUARD_ALLOWED_HOSTS, PREWORLD_GUARD_ALLOWED_ORIGINSHost and Origin allow lists for the HTTP downstream (repeatable)
--subject-idPREWORLD_GUARD_SUBJECT_IDA trusted service subject, needed for approvals
--sandbox and --sandbox-*Run a stdio upstream in srt; see Sandbox

See MCP proxy.

mcp-origin ​

sh
preworld-guard mcp-origin --config ./mcp.json --server NAME [--approve SHA256]

Shows an upstream's identity digest. With --approve, approves it.

mcp-manifest ​

sh
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 ​

sh
preworld-guard mcp-auth connect --upstream finance \
  --endpoint https://guard-proxy.example.com --token-file /private/employee-access-token

connect, 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 ​

sh
preworld-guard sandbox verify --executable tooling/node_modules/.bin/srt
preworld-guard sandbox run --workspace ./workspace --deny-read ~/.ssh -- python agent.py

verify exits 0 only if every probe passes. run passes on the command's exit code. Options are in Sandbox.

siem-export ​

sh
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 ​

sh
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 ​

sh
preworld-guard trial-init --framework openai-agents --directory ./guard-trial

Creates 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 ​

sh
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 ​

sh
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.