Skip to main content
The Modal CLI provides commands for deploying, managing, and monitoring your applications. Access it via modal or python -m modal.

​
Global options

modal --help               # Show help message
modal --version            # Show Modal client version
modal --profile PROFILE    # Use a specific authentication profile

​
Core commands

Run a Modal app or function from a Python file: 
modal run app.py
modal run app.py::function_name
modal run app.py --env staging
​
file_or_module
string
required
Path to Python file or module to run. Can include ::function_name to run a specific function.
​
--env
string
Environment name to run in (e.g., “staging”, “production”)
​
--detach
boolean
Run the app in detached mode (don’t stream logs)
Deploy a Modal app: 
modal deploy app.py
modal deploy app.py --name my-app
modal deploy app.py --env production
​
file_or_module
string
required
Path to Python file or module to deploy
​
--name
string
Name for the deployment
​
--env
string
Environment to deploy to
Run a Modal app in development mode with auto-reload: 
modal serve app.py
modal serve app.py --timeout 60
​
file_or_module
string
required
Path to Python file or module to serve
​
--timeout
number
Timeout in seconds for idle containers
Open an interactive shell in a Modal container: 
modal shell
modal shell --image python:3.11
modal shell --gpu T4
​
--image
string
Container image to use
​
--gpu
string
GPU type to attach (e.g., “T4”, “A10G”, “A100”)
​
--cpu
number
Number of CPU cores
​
--memory
number
Memory in MB

​
App management

List deployed and running apps: 
modal app list
modal app list --env production
modal app list --json
​
--env
string
Filter by environment
​
--json
boolean
Output as JSON
Stream logs from a running app: 
modal app logs ap-123456
modal app logs my-app-name
modal app logs my-app --timestamps
​
app_identifier
string
required
App name or ID (format: ap-*)
​
--timestamps
boolean
Include timestamps in log output
​
--env
string
Environment name
Stop a running app: 
modal app stop ap-123456
modal app stop my-app-name

​
Storage management

Manage persistent volumes: 
# List volumes
modal volume list

# Create a volume
modal volume create my-volume

# Delete a volume
modal volume delete my-volume

# List files in a volume
modal volume ls my-volume /path

# Download from volume
modal volume get my-volume /remote/path /local/path

# Upload to volume
modal volume put my-volume /local/path /remote/path
Manage distributed dictionaries: 
# List dicts
modal dict list

# Create a dict
modal dict create my-dict

# Delete a dict
modal dict delete my-dict

# Get a value
modal dict get my-dict key

# Set a value  
modal dict put my-dict key value
Manage secrets: 
# List secrets
modal secret list

# Create a secret
modal secret create my-secret KEY1=value1 KEY2=value2

# Delete a secret
modal secret delete my-secret
Manage queues: 
# List queues
modal queue list

# Create a queue
modal queue create my-queue

# Delete a queue
modal queue delete my-queue

# Get queue length
modal queue len my-queue

​
Configuration

Manage authentication tokens: 
# Create a new token
modal token new

# Create token for a profile
modal token new --profile work

# List tokens
modal token list

# Set active token
modal token set TOKEN_ID
Manage authentication profiles: 
# List profiles
modal profile list

# Set active profile
modal profile activate my-profile

# Create new profile
modal token new --profile new-profile
Manage Modal configuration: 
# Show current configuration
modal config show

# Set configuration value
modal config set key value
Manage deployment environments: 
# List environments
modal environment list

# Create environment
modal environment create staging

# Delete environment
modal environment delete staging

​
Observability

Open the Modal dashboard in your browser: 
modal dashboard
View billing information: 
# Show current usage
modal billing usage

# Show billing history
modal billing history
View Modal changelog: 
modal changelog

​
Container management

Manage running containers: 
# List containers
modal container list

# Get container logs
modal container logs fc-123456

# Execute command in container
modal container exec fc-123456 -- python script.py

# Stop a container
modal container stop fc-123456

​
Setup and initialization

Bootstrap Modal configuration (same as modal token new): 
modal setup
modal setup --profile my-profile
This command:
  1. Opens your browser for authentication
  2. Creates a new authentication token
  3. Saves credentials to ~/.modal.toml

​
Advanced commands

Launch common development tools: 
# Launch Jupyter notebook
modal launch jupyter

# Launch VS Code server
modal launch vscode
Manage network file systems (hidden command): 
modal nfs list
modal nfs create my-nfs
NetworkFileSystem commands are available but not shown in help by default.

​
Environment variables

The Modal CLI respects these environment variables:
  • MODAL_ENVIRONMENT - Default environment for deployments
  • MODAL_PROFILE - Default authentication profile
  • MODAL_TOKEN_ID - Token ID to use for authentication
  • MODAL_TOKEN_SECRET - Token secret for authentication

​
Exit codes

The Modal CLI uses standard exit codes:
  • 0 - Success
  • 1 - General error
  • 2 - Command-line usage error

​
Getting help

Every command supports the --help flag: 
modal --help
modal run --help
modal app --help
modal volume list --help

​
Examples

modal deploy app.py --env production --name my-production-app

# Get app ID
modal app list

# Stream logs
modal app logs ap-123456 --timestamps

# Check containers
modal container list

# Upload data
modal volume put my-data ./local/data /remote/data

# List contents
modal volume ls my-data /remote/data

# Download results
modal volume get my-data /remote/results ./local/results

# Deploy to staging
modal deploy app.py --env staging

# Test in staging
modal run app.py --env staging

# Deploy to production
modal deploy app.py --env production

​
Next steps

Basic usage

Learn how to write Modal functions

API reference

Explore the Python API

Build docs developers (and LLMs) love

Get started for freeTalk to us