Skip to main content

Pie CLI

pie-cli is the primary command-line tool for interacting with the Pie engine. It allows you to start the engine, run inference programs (inferlets), and manage models and configurations.

These are the main commands you can run directly from your terminal.

pie serve​

Starts the Pie engine in server mode and opens an interactive shell session for running inferlets and querying the engine's state.

Syntax​

pie serve [OPTIONS]

Options​

OptionDescriptionType
--config <PATH>Path to a custom TOML configuration file.Path
--host <HOST>The network host to bind to (e.g., 0.0.0.0).String
--port <PORT>The network port to use.Integer
--no-authDisables authentication for the engine.Flag
--log <PATH>A file path to write logs to.Path
-v, --verboseEnables verbose console logging (INFO level).Flag

Example​

# Start the server on port 8081 with verbose logging
pie serve --port 8081 --verbose

pie run​

Starts a temporary, one-shot Pie engine to run a single inferlet and then shuts down. This is useful for scripting and single-task execution.

Syntax​

pie run [OPTIONS] <INFERLET> [-- <ARGUMENTS>...]

Arguments & Options​

Argument/OptionDescriptionType
<INFERLET>Path to the .wasm inferlet file to execute.Path (Required)
-c, --config <PATH>Path to a custom TOML configuration file.Path
--log <PATH>A file path to write logs to.Path
<ARGUMENTS>...Arguments to pass to the inferlet. Must come after --.String[]

Example​

# Run an inferlet and pass arguments to it
pie run ./my_inferlet.wasm -- --input data.csv --mode process

pie model​

Provides a suite of commands for managing local models and interacting with the model registry.

pie model list​

Lists all models that have been downloaded to your local machine.

Syntax

pie model list

pie model add​

Downloads a model and its metadata from the official model registry.

Syntax

pie model add <MODEL_NAME>

Arguments

  • <MODEL_NAME>: The name of the model to download (e.g., qwen-3-0.6b).

Example

pie model add qwen-3-0.6b

pie model remove​

Deletes a model's files and metadata from your local machine.

Syntax

pie model remove <MODEL_NAME>

Arguments

  • <MODEL_NAME>: The name of the model to remove.

Example

pie model remove qwen-3-0.6b

Searches the official model registry for available models. You can optionally filter the results with a regular expression.

Syntax

pie model search [PATTERN]

Arguments

  • [PATTERN]: An optional regex pattern to filter model names.

Example

# Search for all models containing "qwen"
pie model search "qwen.*"

pie model info​

Displays detailed architecture information and local download status for a specific model from the registry.

Syntax

pie model info <MODEL_NAME>

Arguments

  • <MODEL_NAME>: The name of the model to inspect.

Example

pie model info qwen-3-0.6b

pie config​

Manages the pie-cli configuration file.

pie config init​

Creates a default config.toml file in the Pie home directory ($PIE_HOME or ~/.cache/pie).

Syntax

pie config init <BACKEND_TYPE> <EXEC_PATH>

Arguments

  • <BACKEND_TYPE>: The type of the backend (e.g., python, metal).
  • <EXEC_PATH>: The full path to the backend executable.

Example

pie config init python /path/to/my/backend/main.py

pie config update​

Modifies specific values in the default config.toml file.

Syntax

pie config update [OPTIONS]

Engine Options

  • --host <HOST>
  • --port <PORT>
  • --enable-auth <true|false>
  • --auth-secret <SECRET>
  • --cache-dir <PATH>
  • --verbose <true|false>
  • --log <PATH>

Backend Options

  • --backend-type <TYPE>
  • --backend-exec-path <PATH>
  • --backend-model <MODEL>
  • --backend-device <DEVICE>
  • --backend-dtype <DTYPE>
  • --backend-kv-page-size <INT>
  • --backend-max-batch-tokens <INT>
  • And many more... Use pie config update --help for a full list.

Example

# Change the engine port and the backend model
pie config update --port 9000 --backend-model llama3-8b

pie config show​

Displays the contents of the default config.toml file.

Syntax

pie config show

Interactive Shell Commands​

When you run pie serve, you enter an interactive shell. The following commands are available within this shell.

CommandDescription
run [--detach] <PATH> [ARGS]...Runs a .wasm inferlet. Use --detach to run in the background.
statDisplays runtime statistics from the backend.
helpShows a list of available shell commands.
query(Not yet implemented) Queries the engine state.
exitExits the interactive session and shuts down the engine.

Example​

pie> run --detach ./path/to/inferlet.wasm
✅ Inferlet launched with ID: f1d2d2f924e98624c89b3fdf5a3f0d3a
pie> stat
Backend runtime stats:
...
pie> exit
Shutting down services...