Documentation Index
Fetch the complete documentation index at: https://mintlify.com/spiceai/spiceai/llms.txt
Use this file to discover all available pages before exploring further.
The spice run command starts the Spice.ai runtime (spiced), automatically installing it if not present.
Usage
spice run [OPTIONS] [-- SPICED_ARGS...]
Options
| Flag | Default | Description |
|---|
--http-endpoint <URL> | http://127.0.0.1:8090 | HTTP endpoint for runtime binding |
--flight-endpoint <URL> | 127.0.0.1:50051 | Arrow Flight endpoint |
--metrics-endpoint <URL> | 127.0.0.1:9090 | Prometheus metrics endpoint |
-v, --verbose | - | Increase verbosity (-v debug, -vv trace) |
Arguments
| Argument | Description |
|---|
SPICED_ARGS | Additional arguments passed directly to spiced |
Behavior
Auto-Installation
If the runtime is not installed at ~/.spice/bin/spiced, the command automatically runs spice install before starting.
Signal Handling
The CLI forwards signals to the runtime for graceful shutdown:
- Unix (Linux/macOS):
SIGTERM and SIGINT are forwarded to spiced
- Windows: Ctrl+C propagates to child process automatically
Standard I/O
All standard input, output, and error streams are inherited, allowing:
- Interactive prompts
- Direct log output
- Pipe input/output redirection
Examples
Basic Usage
Start the runtime with default settings:
Output:
Spice.ai OSS CLI v1.0.0
Spice.ai runtime starting...
2026-03-03T12:00:00.000Z INFO Runtime starting...
2026-03-03T12:00:00.100Z INFO HTTP listening on 127.0.0.1:8090
2026-03-03T12:00:00.150Z INFO Flight listening on 127.0.0.1:50051
Custom HTTP Endpoint
Bind to a specific interface and port:
spice run --http-endpoint http://0.0.0.0:8080
Verbose Logging
Enable debug logging:
Enable trace logging:
Custom Flight and Metrics Endpoints
spice run \
--http-endpoint http://0.0.0.0:8090 \
--flight-endpoint 0.0.0.0:50051 \
--metrics-endpoint 0.0.0.0:9090
Pass Additional Runtime Arguments
Arguments after -- are passed directly to spiced:
spice run -- --log-level trace --disable-telemetry
Run with Spicepod from URL
Load configuration from a remote location:
# From HTTPS URL
spice run -- https://example.com/spicepod.yaml
# From S3 (requires AWS credentials)
spice run -- s3://my-bucket/spicepod.yaml
# From local file
spice run -- /path/to/spicepod.yaml
Development Mode with Hot Reload
The runtime automatically watches for changes to spicepod.yaml and component files in the datasets/ and models/ directories:
spice run
# Edit spicepod.yaml - runtime reloads automatically
Configuration
Spicepod Location
By default, spice run looks for spicepod.yaml in the current directory. Override with:
spice run -- /path/to/custom/spicepod.yaml
Environment Variables
The runtime inherits environment variables from the shell:
export SPICE_POSTGRES_CONNECTION_STRING="postgresql://user:pass@host/db"
spice run
.env / .env.local files:
# .env
SPICE_POSTGRES_CONNECTION_STRING=postgresql://user:pass@host/db
SPICE_API_KEY=your_api_key
Runtime Arguments
Common spiced arguments you can pass:
| Argument | Description |
|---|
--http <ADDR> | HTTP bind address (set via --http-endpoint) |
--flight <ADDR> | Flight bind address (set via --flight-endpoint) |
--metrics <ADDR> | Metrics bind address (set via --metrics-endpoint) |
--log-level <LEVEL> | Log level: error, warn, info, debug, trace |
--disable-telemetry | Disable anonymous telemetry |
--tls-enabled | Enable TLS for HTTP/Flight endpoints |
Graceful Shutdown
Press Ctrl+C or send SIGTERM to gracefully stop the runtime:
Output:
2026-03-03T12:05:00.000Z INFO Received shutdown signal
2026-03-03T12:05:00.100Z INFO Draining connections...
2026-03-03T12:05:00.200Z INFO Runtime shutdown complete
Exit Codes
| Code | Description |
|---|
0 | Clean shutdown |
1 | Runtime error or installation failure |
| Other | Exit code from spiced |
Troubleshooting
Port Already in Use
spice run --http-endpoint http://127.0.0.1:8091
Permission Denied
# macOS/Linux: Verify executable permissions
ls -la ~/.spice/bin/spiced
chmod +x ~/.spice/bin/spiced
Runtime Not Found
Manually install:
Runtime Architecture
The runtime uses separate Tokio thread pools for:
- HTTP Server: API endpoints, health checks (must stay responsive)
- Query Processing: DataFusion execution (CPU/IO intensive)
This ensures health checks respond even during heavy query load.