CLI
Every pie command and flag.
Global flags
Place global flags before the subcommand, as in pie --log-level debug serve.
| Flag | Meaning |
|---|---|
-c, --config <PATH> | Config file path. Otherwise uses $PIE_CONFIG, then $PIE_HOME/config.toml. |
--log-level <LEVEL> | error, warn, info (default), debug, or trace. |
--metrics-listen <ADDR> | Serve Prometheus metrics at this address. |
--json | Print machine-readable JSON output (also accepted after any subcommand). |
Commands
| Command | Effect |
|---|---|
pie serve | Start the server (gateway, controller, and worker in one process). SIGHUP reloads policies. |
pie run [INFERLET] [-- ARGS] | Run one inferlet and exit. INFERLET can be a .py, .js, or .wasm file, an installed name, or an example name in a checkout of the repository. |
pie model list · info · import · remove | Manage imported .zt model files. |
pie cache list · clear | List or clear the Hugging Face download cache. |
pie config list · show · set · unset · edit · init · tune | Inspect, edit, initialize, or tune config.toml. |
pie inferlet list · info · install · remove | Manage installed inferlets. |
pie language list · install · remove | Manage the Python and JavaScript WebAssembly runtimes. |
pie tune [BACKEND] | Benchmark this device and save its kernel profile. |
pie profile schema · list · dump · export | Inspect and export device kernel profiles. |
pie doctor | Check the config file, model artifacts, engine, and GPU drivers. |
pie run
pie run main.py -- --prompt "Hi" --max-tokens 16| Option | Meaning |
|---|---|
-p, --path <PATH> | Path to the inferlet file (alternative to the positional argument). |
-o, --out <DIR> | Directory where files sent with session.send_file() are saved. |
--file <NAME=PATH> | Attach a file readable inside the inferlet via session.file(NAME). Repeatable. |
Arguments after -- become the JSON input object passed to main: --key value pairs become fields (- in a key becomes _), numbers and true/false are parsed as their types, a bare --flag becomes true, and remaining arguments go into _positional.
pie model import
pie model import <hf-id> [--deployment NAME] [--drafter NAME] [--dry-run]| Option | Meaning |
|---|---|
--deployment <NAME> | Import using this deployment. --deployment '?' lists all deployments for the model. |
--drafter <NAME> | Attach a speculative-decoding draft head. |
--out <PATH> | Write the .zt file to this path. |
--dry-run | Print the import plan without downloading or converting. |
--force | Overwrite an existing .zt file. |
--keep-source · --delete-source · --consume-source | How to handle the downloaded Hugging Face shards: keep them (default), delete them after conversion, or delete each shard as soon as it is converted. |
pie tune
| Option | Meaning |
|---|---|
--full | Measure the full kernel grid (about an hour) instead of the quick subset (a few minutes). |
--dry-run | Measure and print the profile without saving it. |
--check <DEPLOYMENT> | Model deployment to validate end to end; defaults to the smallest imported model. |
--no-check | Skip the end-to-end validation check. |
--force | Save the new profile even if end-to-end validation measures lower speed. |
--refit | Refit the profile from the last run's measurements without re-running benchmarks. |
pie config tune
| Option | Meaning |
|---|---|
--for latency|throughput | Optimization target. |
--program <NAME> | Inferlet to run as the benchmark workload. |
--fleet, --tokens, --repeats, --budget | Concurrency, token length, repeat count, and search budget. |
--write | Save the best settings found into config.toml. |
Cluster binaries
| Binary | Main options |
|---|---|
pie-controller | --listen |
pie-gateway | --listen, --worker-listen, --controller |
pie-worker | --host, --port, --controller, --role |
pie-pool | Remote KV page pool; loads no model |
All four binaries accept -c/--config, --log-level, and --metrics-addr.