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) |