| name | modal-cli |
| description | Modal CLI for serverless GPU/cloud compute. Use when user mentions modal, deploying to modal, running GPU workloads, or serverless Python functions. Check `which modal` first — if missing, offer: `pip install modal && modal setup`. Covers run/serve/deploy, apps, containers, secrets, volumes, and workspace management.
|
Prerequisites
Before any modal command, verify the CLI is available:
which modal
If not found, ask the user:
Modal CLI not found. Install it?
pip install modal
After install, run auth setup:
modal setup
This opens a browser for token auth. If modal still isn't on PATH after pip install, use:
python -m modal setup
If found but not authed, check with:
modal token info
If that errors, run modal setup to authenticate.
Core Commands
| Command | Purpose |
|---|
modal run <file> | One-off execution of a script/function |
modal serve <file> | Local dev with hot-reload |
modal deploy <file> | Production deployment |
modal app list | List deployed apps |
modal app logs <name> | Stream logs for a deployed app |
modal app stop <name> | Stop a running app |
modal shell | Interactive shell in Modal environment |
Workflows
First-time setup
pip install modal
modal setup
modal run hello.py
Develop and deploy
modal run my_app.py
modal serve my_app.py
modal deploy my_app.py
Debug containers
modal container list
modal container logs <id>
modal container exec <id> -- bash -lc "nvidia-smi"
Manage resources
modal secret create my-secret KEY=value
modal volume create my-vol
modal environment create dev
modal config set-environment dev
Auth & Profiles
modal token info — check current auth
modal token new — create token via browser
modal token set — set token credentials directly
modal profile list / activate — switch workspaces
modal config show — print effective config
Environment variables: MODAL_TOKEN_ID, MODAL_TOKEN_SECRET, MODAL_ENVIRONMENT, MODAL_PROFILE
Resource Management
- Secrets:
modal secret list/create/delete (supports .env import)
- Volumes:
modal volume create/list/ls/put/get/rm/delete
- Dicts:
modal dict create/list/items/get/clear/delete
- Queues:
modal queue create/list/peek/len/clear/delete
- NFS:
modal nfs list/create/ls/put/get/rm/delete
- Environments:
modal environment list/create/delete/update
Decision Points
- User says "deploy to modal" / "run on GPU" →
modal deploy or modal run
- User says "check my modal apps" →
modal app list
- User says "modal logs" →
modal app logs <name>
- User needs interactive debug →
modal shell or modal container exec
- modal not installed → offer install, don't silently fail
- modal not authed → run
modal setup
References