Command line¶
The wasi-python command runs one program in a fresh sandbox and prints its result as one line of JSON, so any language can call the runner as a subprocess. It adds no power the Python function run does not have: each option is one of run's arguments, and an option not given keeps run's default.
$ wasi-python run -- -c "print(1)"
{"exit_code": 0, "fuel_used": null, "stderr": "", "stdout": "1\n", "trapped": null, "truncated": []}
Everything after -- is the guest's own command line: -c, -m, a script, or - for standard input. The table below is generated from the command's parser by uv run python tests/harness/cli_doc.py --write, and a check fails when it differs.
Options¶
wasi-python run¶
Run one program in a fresh sandboxed CPython and print its result as JSON.
wasi-python run [OPTIONS] [--] ARG...
| option | value | default | description |
|---|---|---|---|
--env |
KEY[=VALUE] |
none | an environment variable for the guest: KEY=VALUE, or KEY alone to pass this command's own value, which keeps a secret off the command line; a repeated key keeps its last value (repeatable) |
--stdin |
PATH |
none | a file, or - for this command's own input |
--deadline-s |
SECONDS |
run's default |
the wall-clock seconds the call may run; none for no limit |
--memory-bytes |
BYTES |
run's default |
the most linear memory the guest may hold, in bytes; none for no limit |
--output-bytes |
BYTES |
run's default |
the most bytes kept per stream; the rest is dropped and the stream is named in truncated; none for no limit |
--fuel |
N |
run's default |
a cap on the guest's executed instructions; past it the call ends "out of fuel"; none for no cap |
--max-open-files |
N |
run's default |
the most files and folders the guest holds open at once; none for no limit |
--no-snapshot |
off | run the plain reactor, python.wasm, instead of the snapshot | |
--grant |
GUEST=HOST |
none | a host folder the guest sees at GUEST, read-only (repeatable) |
--grant-writable |
GUEST=HOST |
none | a host folder the guest sees at GUEST, writable (repeatable) |
--import-path |
GUEST |
none | a guest path put on the import path after the stdlib zip; a read-only --grant must serve it (repeatable) |
--root |
HOST |
run's default |
the guest's /, writable; made if missing |
--private-root |
off | a fresh private /, writable, removed after the call | |
--no-root |
off | no / at all, the default |
At most one of --root, --private-root and --no-root.
Exit codes and output¶
The exit code says whether there is a result, not how the program ended:
| code | meaning |
|---|---|
| 0 | the call returned; the JSON says how the program ended |
| 1 | run raised; the JSON has error and kind |
| 2 | a usage error; argparse's message is on standard error |
| 130 | interrupted by Ctrl-C |
On a result the JSON has exit_code, fuel_used, stderr, stdout, trapped and truncated. A stream that is not UTF-8 comes as stderr_base64 or stdout_base64 instead. See Python API for what each field means.