modal

Modal

Three modes. Pick based on intent:

========================================

Deploy mode — deploy or update a Modal app (pre-flight, log streaming, health verification)

Deploy a Modal app with pre-flight checks, log streaming, health verification, and deployment history review.

Instructions

Follow these steps exactly in order. Do NOT skip the user confirmation gate in Step 2.

---

Step 0: Prerequisites

Run these checks in order. Stop at the first failure and guide the user.

1. CLI installed?

Run these as separate parallel Bash calls (never chain with || or &&):

modal --version

If that fails, try:

python -m modal --version

If both fail, tell the user to install with pip install modal. If only python -m modal works, use that prefix for all subsequent commands.

2. Authenticated?

modal token info

If the command fails, tell the user to run modal token new (opens browser) or modal token set.

3. Identify app file:

Use the Grep tool with pattern modal\.App|modal\.Stub|@app\. and glob *.py with output_mode: files_with_matches to find Modal app files. If no app files found, ask the user which file to deploy.

---

Step 1: Pre-Deploy Check

Gather context about what's about to be deployed.

Current deployment state:

modal app list --json

Note any existing deployment with the same name — it will be updated in place.

Git context:

git log -1 --oneline
git status --porcelain

Check for environment specification:

• If the user mentioned a specific environment → use --env <name>
• If a .modal.toml has a default environment → use that
• Otherwise → use the default environment

Check for deployment tag:

• If the user wants to tag this deployment → use --tag <tag>
• Otherwise → no tag

Local syntax check (optional but recommended):

python -c "import ast; ast.parse(open('<app-file>').read())"

If the syntax check fails, warn the user before proceeding.

Present a pre-deploy summary:

Deploy Summary
═══════════════════════════════════════════════════════
  App file:     [filename.py]
  App name:     [app name from file or --name flag]
  Environment:  [env name or "default"]
  Tag:          [tag or "none"]
  Branch:       [git branch]
  Commit:       [short hash] [message]
  Uncommitted:  [Y/N — warn if Y]
  Existing:     [Y/N — will update existing deployment]
═══════════════════════════════════════════════════════

Step 2: User Confirmation Gate

Ask the user: "Ready to deploy? (y/n)"

Do NOT proceed until the user explicitly confirms. If they say no, stop and ask what they'd like to change.

Step 3: Deploy

Standard deployment:

modal deploy <app-file.py> --stream-logs

With custom name:

modal deploy <app-file.py> --name <deployment-name> --stream-logs

With environment:

modal deploy <app-file.py> --env <environment> --stream-logs

With tag:

modal deploy <app-file.py> --tag <version-tag> --stream-logs

With timestamps:

modal deploy <app-file.py> --stream-logs --timestamps

The --stream-logs flag streams app logs after deployment completes. Monitor for:

• Build/image creation errors
• Import errors
• Function registration failures
• Secret mount failures

Step 4: Health Check

After deployment completes:

Check the app is listed:

modal app list --json

Verify the app appears with the correct state.

If the app has web endpoints, test them: The deployment output will show endpoint URLs. Test each one:

curl -s -o /dev/null -w "%{http_code}" <endpoint-url>

• 200-299 → healthy
• 4xx/5xx → unhealthy, flag immediately
• Note: Modal web endpoints have a -dev suffix when using modal serve; production deploys do not

Check for running containers:

modal container list --json

If the app has min_containers set, verify containers are running.

Step 5: Post-Deploy Log Review

modal app logs <app-name> --timestamps

Check for:

• Function initialization errors
• GPU allocation failures
• OOM kills
• Heartbeat timeouts
• Secret access errors
• Volume mount failures
• Import errors in container

Step 6: Deployment History

modal app history <app-name> --json

Show recent deployment versions, useful for confirming the deploy and for rollback reference.

Step 7: Deploy Report

Present a final summary:

Deploy Report
═══════════════════════════════════════════════════════
  Status:       [deployed / failed]
  App:          [app name]
  Environment:  [environment]
  Tag:          [tag if set]
  Version:      [version number from history]
  Commit:       [hash] [message]
  Endpoints:    [list URLs if web endpoints exist]
  Health:       [HTTP status for each endpoint]
  Containers:   [count running]
  Errors:       [count of errors in logs]
═══════════════════════════════════════════════════════

If the deploy failed:

• Show the relevant error logs
• Suggest checking modal app logs <app-name> --timestamps
• Offer to rollback: modal app rollback <app-name> <version> (Team/Enterprise plans only)
• Offer to stop: modal app stop <app-name> (permanent — requires redeployment)

$ARGUMENTS

========================================

Logs mode — view, stream, or tail logs for an app or container

View and stream Modal app and container logs. Supports app-level logs, per-container logs, and deployment log streaming.

Instructions

Follow these steps exactly in order.

---

Step 0: Prerequisites

Run these checks in order. Stop at the first failure and guide the user.

1. CLI installed?

Run these as separate parallel Bash calls (never chain with || or &&):

modal --version

If that fails, try:

python -m modal --version

If both fail, tell the user to install with pip install modal.

2. Authenticated?

modal token info

If the command fails, tell the user to run modal token new.

---

Step 1: Identify Target

Determine what to fetch logs for.

List deployed apps:

modal app list --json

List running containers:

modal container list --json

If the user specified an app name, container ID, or environment, use that. Otherwise, ask which app they want logs for.

Step 2: Fetch Logs

App-level logs (streams while app is active):

modal app logs <app-name>

App logs with timestamps:

modal app logs <app-name> --timestamps

App logs in a specific environment:

modal app logs <app-name> --env <environment>

Container-level logs (specific container):

modal container logs <container-id>

Container logs with timestamps:

modal container logs <container-id> --timestamps

Stream logs during a run:

modal run <app-file.py> --timestamps

Stream logs during deployment:

modal deploy <app-file.py> --stream-logs --timestamps

Step 3: Debug Deeper

If app-level logs aren't enough, investigate individual containers.

List running containers for the app:

modal container list --json

Get specific container logs:

modal container logs <container-id> --timestamps

Execute diagnostic commands inside a container:

modal container exec <container-id> -- nvidia-smi          # GPU status
modal container exec <container-id> -- ps aux              # Process list
modal container exec <container-id> -- cat /proc/meminfo   # Memory info
modal container exec <container-id> -- df -h               # Disk usage

Shell into a container for interactive debugging:

modal shell <container-id>

The shell container has preinstalled tools: vim, nano, ps, strace, curl, py-spy.

Common Investigations

GPU OOM detection:

modal container exec <container-id> -- nvidia-smi

Check for high GPU memory utilization. OOM kills appear in app logs as container termination events.

Heartbeat timeout diagnosis: The GIL may be blocking the heartbeat thread. Profile with py-spy:

modal shell <container-id>
# Inside the shell:
py-spy dump --pid 1

Function initialization failures: Check app logs for import errors, missing dependencies, or secret access failures:

modal app logs <app-name> --timestamps

Cold start analysis: Look for container startup events in logs — compare startup times across containers. Check if min_containers is configured to prevent cold starts.

Volume access issues:

modal volume ls <volume-name>

Verify the volume exists and has expected contents.

Secret access issues:

modal secret list --json

Verify the secret exists in the correct environment. Don't display values.

Step 4: Present Results

Format log output clearly:

• Group by severity (errors first, then warnings, then info)
• Highlight container termination events (OOM, heartbeat timeout)
• Show GPU utilization if containers use GPUs
• Note any patterns (recurring errors, degrading performance)
• If logs are empty or the app has no recent activity, say so
• Suggest next steps based on what the logs show

Debug Environment Variables

For more verbose logging, suggest the user set:

MODAL_LOGLEVEL=DEBUG modal run <app-file.py>

For full tracebacks:

MODAL_TRACEBACK=1 modal run <app-file.py>

$ARGUMENTS

========================================

Status mode — workspace overview: apps, containers, secrets, volumes

Quick dashboard for your Modal workspace. Shows deployed apps, running containers, secrets, volumes, environments, and GPU usage at a glance.

Instructions

Follow these steps exactly in order.

---

Step 0: Prerequisites

Run these checks in order. Stop at the first failure and guide the user.

1. CLI installed?

Run these as separate parallel Bash calls (never chain with || or &&):

modal --version

If that fails, try:

python -m modal --version

If both fail, tell the user to install with pip install modal. If only python -m modal works, note this and use python -m modal for all subsequent commands.

2. Authenticated?

modal token info

If the command fails, tell the user to run modal token new (opens browser) or modal token set --token-id <id> --token-secret <secret> for headless auth.

3. Check environment:

modal environment list --json

Note which environments exist and which is active. Default is used if --env is not specified.

---

Step 1: Deployed Apps

modal app list --json

List all deployed and running apps: name, state, creation time.

Step 2: Running Containers

modal container list --json

List all currently running containers: container ID, app, function, GPU type (if any).

Step 3: Secrets

modal secret list --json

List secret names only — never display values. Note which environment each secret belongs to.

Step 4: Volumes

modal volume list --json

List all volumes: name, creation time, environment.

Step 5: Environments

modal environment list --json

List all environments and their web suffixes.

Step 6: Check for Modal Config

Use the Read tool to check for project-level Modal configuration:

• Read .modal.toml (skip if it doesn't exist)
• Read modal.toml (skip if it doesn't exist)

Also check for Modal app files:

• Use the Glob tool with pattern *.py to find Python files
• Use the Grep tool with pattern modal\.App|modal\.Stub|@app\. and glob *.py with output_mode: files_with_matches to find Modal app files

Step 7: Present Dashboard

Format all output as a clean summary:

Modal Dashboard
═══════════════════════════════════════════════════════
  Workspace:    [workspace name from token info]
  Environment:  [active environment]
  Environments: [list all]
═══════════════════════════════════════════════════════

Deployed Apps
┌──────────────────────────┬────────────┬─────────────────────┐
│ App                      │ State      │ Deployed            │
├──────────────────────────┼────────────┼─────────────────────┤
│ ...                      │ ...        │ ...                 │
└──────────────────────────┴────────────┴─────────────────────┘

Running Containers
┌──────────────────┬──────────────────┬────────────┬──────────┐
│ Container ID     │ App / Function   │ GPU        │ Status   │
├──────────────────┼──────────────────┼────────────┼──────────┤
│ ...              │ ...              │ ...        │ ...      │
└──────────────────┴──────────────────┴────────────┴──────────┘

Secrets: [count] configured
Volumes: [count] provisioned
  [list names and sizes if available]

Config: [.modal.toml found / not found]
App files: [list of .py files with modal imports]

========================================

Migration

Consolidated from legacy claudefather skills. Pick the mode based on intent.