CLI reference
You use the Executor entirely through one command-line tool, oee, a single static Rust executable. It has nine subcommands.
| Subcommand | What it does |
|---|---|
| oee init | Detects your project and scaffolds an annotated oee.yaml, or runs the guided configuration. |
| oee validate | Validates a manifest before you build. |
| oee keygen | Generates an Ed25519 signing key pair. |
| oee build | Packages the application, its runtime and the signed policy into one executable. |
| oee run | Runs any local command under the sandbox and exit events, without building first. |
| oee inspect | Verifies a built binary and prints what it contains. |
| oee status | Reports on running Executor instances. |
| oee stop | Stops a running instance cleanly. |
| oee runtime | Lists, pre-fetches and verifies the portable runtimes in the build cache. |
The standard workflow
# 1. Scaffold a configuration for a Python uvicorn project
oee init --lang python --sandbox
# 1b. Or answer guided questions instead (application, runtime, start command,
# exit events, CPU/memory caps, auto-scaling) to produce the same oee.yaml
oee init --interactive
# 2. Validate sandbox path policies and exit-event JSONPath expressions
oee validate -f oee.yaml --strict
# 3. Generate Ed25519 manifest signing keys
oee keygen --out-dir ./certs
# 4. Build a standalone single-binary executable for Linux x86_64
oee build \
-f oee.yaml \
--target linux-x86_64 \
--sign-key ./certs/oee.key \
-o ./dist/my-service
# 5. Inspect and verify the signature of the built binary
oee inspect ./dist/my-service --verify-key ./certs/oee.pub
# 6. Run the single binary directly (CLI flags pass through when configured)
OEE_API_KEY="sec_live_98a7bc..." ./dist/my-service --log-level info
oee init
oee init [--lang <auto|python|go|java|node|binary>] [--sandbox] [--interactive]
Detects the project structure (pyproject.toml, requirements.txt, go.mod, pom.xml, package.json) and scaffolds an annotated oee.yaml.
| Flag | Meaning |
|---|---|
--lang <value> | The application's language: auto (detect it), python, go, java, node or binary (any compiled executable). |
--sandbox | Scaffold the manifest with the sandbox enabled. |
--interactive | Run the guided configuration: application, runtime, start command, exit events, CPU and memory capping, auto-scaling and sandbox. It validates every answer, writes no secret unless you choose a sealed static token, and prints the exact oee build command to run next. |
oee init --lang python --sandbox
oee init --interactive
oee validate
oee validate [-f <oee.yaml>] [--strict]
Validates the manifest's syntax, sandbox path permissions, cron expressions, JSONPath queries and environment variable references before you build.
| Flag | Meaning |
|---|---|
-f <oee.yaml> | The manifest to validate. |
--strict | Validate in strict mode. |
oee validate -f oee.yaml --strict
oee keygen
oee keygen [--out-dir <dir>]
Generates an Ed25519 key pair: oee.key, the private key that signs the policy, and oee.pub, the public verification key that is embedded into oee-stub.
| Flag | Meaning |
|---|---|
--out-dir <dir> | The directory to write oee.key and oee.pub to. |
oee keygen --out-dir ./certs
oee build
oee build [-f <oee.yaml>] [--target <triple>] [-o <binary>] [--sign-key <path>]
Packages the guest workload, its portable language runtime and the signed policy atop oee-stub into a single standalone executable, choosing the smallest supervisor variant that satisfies the manifest. It builds for other platforms than the one it runs on, for example windows-x86_64 from a Linux CI runner.
| Flag | Meaning |
|---|---|
-f <oee.yaml> | The manifest to build from. |
--target <triple> | The platform the binary runs on, such as linux-x86_64 or windows-x86_64. |
-o <binary> | The output file. |
--sign-key <path> | The Ed25519 private key that signs the policy, such as ./certs/oee.key. |
oee build -f oee.yaml --target linux-x86_64 --sign-key ./certs/oee.key -o ./dist/my-service
oee build -f oee.yaml -o order-service-oee
oee run
oee run [-f <oee.yaml>] -- <cmd> [args...]
Development supervisor mode: runs an arbitrary local command directly under the Executor's sandbox and exit events, without building a packaged binary first.
| Flag or argument | Meaning |
|---|---|
-f <oee.yaml> | The manifest whose policy applies. |
-- <cmd> [args...] | The command to run and its arguments, after --. |
oee run -f oee.yaml -- python -m uvicorn app.server:api --port 8000
oee inspect
oee inspect <oee-binary> [--verify-key <oee.pub>]
Verifies the OEE! footer, the BLAKE3 Merkle root and the Ed25519 signature, and prints the embedded policy summary, the target operating system and architecture, and the bundled runtime versions.
| Flag or argument | Meaning |
|---|---|
<oee-binary> | The binary to inspect. |
--verify-key <oee.pub> | The public key to verify the signature with. |
oee inspect ./dist/my-service --verify-key ./certs/oee.pub
oee status
oee status [--instance <id>] [--json]
Queries the Executor instances running locally through authenticated, user-scoped control sockets. It reports the process-tree count, the sandbox state, uptime, the status of the last exit-event poll, the resolved CPU and memory caps with current usage, the replica count, each replica's port, readiness and usage, and the health and active connections of each load-balancer backend.
| Flag | Meaning |
|---|---|
--instance <id> | Report on one instance only. |
--json | Machine-readable output. |
oee status
oee status --instance <id> --json
oee stop
oee stop <instance-id | --all> [--mode <graceful|immediate>]
Sends an authenticated local operator stop command to a running supervisor, which runs the state-preserving stop of its whole process tree. The instance exits with code 143.
| Flag or argument | Meaning |
|---|---|
<instance-id> | The instance to stop. |
--all | Stop every running instance. |
--mode <mode> | graceful: signal, bounded drain, then hard termination. immediate: terminate the tree at once. |
The local control socket can stop an instance, but it can never raise or disable a sealed CPU or memory cap.
oee stop <instance-id> --mode graceful
oee stop --all --mode immediate
oee runtime
oee runtime list
oee runtime fetch
oee runtime verify
Manages the portable runtimes that oee build bundles, in the local build cache.
| Action | Meaning |
|---|---|
list | Lists the portable CPython, jlink JDK and Node.js distributions in the cache. |
fetch | Pre-fetches them, so builds do not wait for downloads. |
verify | Checksum-verifies them. |
Running a built binary
A built binary is run directly, like any program:
./dist/my-service --log-level info
With workload.passthrough_cli_args: true, its command-line arguments reach your application. Environment variables named by from_env are read by the supervisor at startup and, with scrub_from_guest_env: true (the default), never reach the application.