Last Updated: 3/5/2026

CLI Reference

Complete reference for the Pie command-line interface.

Overview


pie [OPTIONS] <COMMAND>

Pie provides commands for:

Running inferlets — serve, run
Configuration — config init, config show, config update
Model management — model list, model download, model remove
Diagnostics — doctor
Authentication — auth

serve

Start the Pie engine server.


pie serve [OPTIONS]

Options

Option	Description
`-c`, `--config <PATH>`	Path to TOML configuration file
`--host <HOST>`	Override host address
`--port <PORT>`	Override port
`--no-auth`	Disable authentication
`-v`, `--verbose`	Enable verbose logging
`--cache-dir <PATH>`	Cache directory path
`--log-dir <PATH>`	Log directory path
`-i`, `--interactive`	Enable interactive shell mode
`-m`, `--monitor`	Launch real-time TUI monitor

Examples


# Start server with defaults
pie serve
 
# Interactive mode
pie serve -i
 
# Monitor mode with custom port
pie serve -m --port 9000
 
# Disable auth for development
pie serve --no-auth -v

run

Run an inferlet with a one-shot Pie engine.


pie run [OPTIONS] [INFERLET] [-- ARGS...]

Arguments

Argument	Description
`INFERLET`	Inferlet name from registry (e.g., `std/text-completion@0.1.0`)
`ARGS...`	Arguments passed to the inferlet (after `--`)

Options

Option	Description
`-p`, `--path <PATH>`	Path to a local `.wasm` inferlet file
`-c`, `--config <PATH>`	Path to TOML configuration file
`--log <PATH>`	Path to log file

Examples


# Run from registry
pie run text-completion -- --prompt "Hello world"
 
# Run local inferlet
pie run --path ./my_inferlet.wasm -- --arg value
 
# With custom config
pie run -c ./config.toml text-completion -- --prompt "Test"

doctor

Check system health and configuration.


pie doctor

Verifies:

Configuration file exists
Models are available
GPU/device accessibility
Backend connectivity

config

Manage configuration files.

config init

Create a default configuration file.


pie config init [OPTIONS]

Option	Description
`--path <PATH>`	Custom config file path

Creates ~/.pie/config.toml with default settings.

config show

Display current configuration.


pie config show [OPTIONS]

Option	Description
`--path <PATH>`	Custom config file path

config update

Update configuration values.


pie config update [OPTIONS]

Engine Options

Option	Description
`--host <HOST>`	Network host to bind to
`--port <PORT>`	Network port to bind to
`--enable-auth` / `--disable-auth`	Toggle authentication
`--verbose` / `--no-verbose`	Toggle verbose logging
`--cache-dir <PATH>`	Cache directory path
`--log-dir <PATH>`	Log directory path
`--registry <URL>`	Inferlet registry URL

Model Options

Option	Description
`--hf-repo <REPO>`	HuggingFace model repository
`--device <DEVICES>`	Device assignment (e.g., `cuda:0` or `cuda:0,cuda:1`)
`--activation-dtype <DTYPE>`	Activation dtype (`bfloat16`, `float16`)
`--weight-dtype <DTYPE>`	Weight dtype
`--kv-page-size <SIZE>`	KV cache page size
`--max-batch-tokens <N>`	Maximum batch tokens
`--gpu-mem-utilization <FLOAT>`	GPU memory utilization (0.0-1.0)
`--use-cuda-graphs` / `--no-use-cuda-graphs`	Toggle CUDA graphs

Telemetry Options

Option	Description
`--telemetry` / `--no-telemetry`	Enable/disable OpenTelemetry
`--telemetry-endpoint <URL>`	OTLP endpoint for traces

Examples


# Change model
pie config update --hf-repo "Qwen/Qwen2.5-7B-Instruct"
 
# Multi-GPU setup
pie config update --device "cuda:0,cuda:1"
 
# Disable auth
pie config update --disable-auth
 
# Multiple updates
pie config update --port 9000 --verbose --gpu-mem-utilization 0.9

model

Manage models from HuggingFace.

model list

List locally cached models.


pie model list

Output shows:

✓ Compatible models (supported by Pie)
○ Other cached models

model download

Download a model from HuggingFace.


pie model download <REPO_ID>

Argument	Description
`REPO_ID`	HuggingFace repository ID

Examples


pie model download meta-llama/Llama-3.2-1B-Instruct
pie model download Qwen/Qwen2.5-7B-Instruct
pie model download deepseek-ai/DeepSeek-R1-Distill-Qwen-7B

model remove

Remove a locally cached model.


pie model remove <REPO_ID>

Prompts for confirmation before deletion.

auth

Authentication management commands.


pie auth <SUBCOMMAND>

Manage SSH keys and authentication settings for the Pie server.

Configuration File

The configuration file (~/.pie/config.toml) structure:


[engine]
host = "127.0.0.1"
port = 8080
enable_auth = true
verbose = false
cache_dir = "~/.pie/cache"
log_dir = "~/.pie/logs"
registry = "https://registry.pie-project.org/"
 
[[model]]
hf_repo = "meta-llama/Llama-3.2-1B-Instruct"
device = ["cuda:0"]
activation_dtype = "bfloat16"
weight_dtype = "bfloat16"
kv_page_size = 16
max_batch_tokens = 8192
gpu_mem_utilization = 0.9
use_cuda_graphs = true
 
[telemetry]
enabled = false
endpoint = "http://localhost:4317"

Environment Variables

Variable	Description
`PIE_HOME`	Override default Pie home directory (`~/.pie`)
`PIE_CONFIG`	Override default config file path
`HF_HOME`	HuggingFace cache directory

Exit Codes

Code	Meaning
`0`	Success
`1`	General error
`130`	Interrupted (Ctrl+C)