Flash CLI Reference

Complete reference for the Flash command-line interface. The Flash CLI provides tools for creating, developing, building, and deploying distributed inference applications.

Quick Navigation

Getting Started Guide - Your first Flash project in 5 minutes
Command Reference - Exhaustive documentation for all commands
Workflows - Common development workflows
Troubleshooting - Solutions to common problems

Command Overview

flash --help              # Show all available commands
flash --version           # Show Flash version
flash <command> --help    # Show help for specific command

Core Commands

Command	Purpose
`flash login`	Authenticate with Runpod
`flash init`	Create new Flash project
`flash run`	Run development server
`flash build`	Build application package
`flash deploy`	Build and deploy application
`flash undeploy`	Delete deployed endpoints

Management Commands

Command	Purpose
`flash env`	Manage deployment environments
`flash app`	Manage Flash applications

Learning Path

New to Flash? Follow this progression:

Start Here: Getting Started Guide
- Create your first project
- Run locally and test
- Deploy to Runpod
Deep Dive: Command Reference
- Understand all options and parameters
- Learn advanced features
- Master build configuration
Real Workflows: Workflows Guide
- Local development workflow
- Multi-environment management
- Testing strategies
When Issues Arise: Troubleshooting
- Common error solutions
- Build size optimization
- Deployment debugging

flash login

Authenticate with Runpod. Opens a browser for authentication and saves credentials locally.

Syntax

flash login

What It Does

Opens your default browser to Runpod's authentication page
After you authenticate, saves credentials securely
Environment variables persist across sessions

Examples

Authenticate with Runpod:

flash login
# Opens browser for authentication

Alternative: Manual Configuration

If flash login doesn't work in your environment, you can set the API key manually:

# Set environment variable
export RUNPOD_API_KEY=your-key-here

# Or add to .env file
echo "RUNPOD_API_KEY=your-key-here" > .env

Get your API key from Runpod Settings.

Related Commands

flash run - Run development server (requires authentication)
flash deploy - Deploy to Runpod (requires authentication)

flash init

Create a new Flash project with the correct structure and boilerplate code.

Syntax

flash init [PROJECT_NAME] [OPTIONS]

Arguments

PROJECT_NAME - Name for the project directory, or . for current directory

Options

Option	Description
`--force`, `-f`	Overwrite existing files without prompting

Examples

Create new project in subdirectory:

flash init my-api
cd my-api

Initialize in current directory:

mkdir my-api && cd my-api
flash init .

Overwrite existing files:

flash init my-api --force

What It Creates

gpu_worker.py - GPU worker template with @Endpoint decorator
pyproject.toml - Project dependencies
.env.example - Environment variable template
.gitignore - Git ignore patterns
.flashignore - Build ignore patterns
README.md - Project documentation

Related Commands

flash run - Run the initialized project locally
Getting Started Guide - Full tutorial

flash run

Run the Flash development server locally with hot reloading.

Syntax

flash run [OPTIONS]

Options

Option	Default	Description
`--host`	`localhost`	Host to bind to (env: `FLASH_HOST`)
`--port`, `-p`	`8888`	Port to bind to (env: `FLASH_PORT`)
`--reload`	enabled	Auto-reload on file changes (use `--no-reload` to disable)
`--auto-provision`	disabled	Auto-provision deployable resources on startup

Environment Variables

FLASH_HOST - Default host (overrides default, overridden by --host)
FLASH_PORT - Default port (overrides default, overridden by --port)

Examples

Basic local development:

flash run
# Server runs at http://localhost:8888
# Visit http://localhost:8888/docs for Swagger UI

Custom host and port:

flash run --host 0.0.0.0 --port 3000
# Accessible from network at http://<your-ip>:3000

Disable auto-reload:

flash run --no-reload
# Useful for debugging or production-like testing

Auto-provision resources:

flash run --auto-provision
# Automatically creates Runpod endpoints on startup

Using environment variables:

export FLASH_HOST=0.0.0.0
export FLASH_PORT=9000
flash run

What It Does

Discovers all .py files (excluding .venv/, .flash/, .runpod/, __init__.py) and finds @Endpoint decorated functions via AST parsing
Generates a FastAPI application with routes for each discovered function
Starts uvicorn development server with hot reload
Provides interactive API documentation at /docs
Optionally provisions remote resources if --auto-provision is enabled

Testing Your Application

After starting the server, test your endpoints:

Swagger UI (recommended): Visit http://localhost:8888/docs for interactive API testing

curl:

curl -X POST http://localhost:8888/your-endpoint \
  -H "Content-Type: application/json" \
  -d '{"input": "test"}'

Related Commands

flash init - Create a project to run
flash build - Build for deployment
Local Development Workflow

flash build

Build the Flash application into a deployable package without deploying.

Syntax

flash build [OPTIONS]

Options

Option	Description
`--no-deps`	Skip transitive dependencies (only install direct dependencies)
`--output`, `-o`	Custom archive name (default: `artifact.tar.gz`)
`--exclude`	Comma-separated packages to exclude (e.g., `torch,torchvision`)
`--use-local-flash`	Bundle local `runpod_flash` source instead of PyPI version

Examples

Standard build:

flash build
# Creates artifact.tar.gz

Custom archive name:

flash build -o my-app-v1.0.tar.gz

Exclude packages present in base image:

flash build --exclude torch,torchvision,torchaudio
# Reduces archive size by excluding packages already in Runpod base images

Skip transitive dependencies:

flash build --no-deps
# Only installs packages listed in pyproject.toml, not their dependencies

Development build with local Flash:

flash build --use-local-flash
# Uses your local runpod_flash source for testing changes

What It Does

Creates .build/ directory (kept for inspection)
Installs dependencies via pip for Linux x86_64
Generates flash_manifest.json with resource configurations
Creates handler files for each @Endpoint function
Packages everything into artifact.tar.gz
Reports archive size (max 500MB for deployment)

Build Size Optimization

If your build exceeds 500MB:

Identify large packages:

du -sh .build/lib/* | sort -h | tail -10

Exclude packages in base image:

flash build --exclude torch,torchvision,torchaudio,transformers

Check base image packages: See Troubleshooting: Archive Size Limit

Debugging Builds

The .build/ directory is preserved for inspection. Check:

.build/lib/ - Installed dependencies
.build/flash_manifest.json - Resource configurations
.build/handler_*.py - Generated handlers

Related Commands

flash deploy - Build and deploy in one step
Build and Deploy Workflow
Troubleshooting: Build Failures

flash deploy

Build and deploy the Flash application to Runpod in a single command.

Syntax

flash deploy [OPTIONS]

Options

Option	Description
`--env`, `-e`	Target environment name
`--app`, `-a`	Flash app name
`--preview`	Build and launch local preview instead of deploying
Build Options	(same as `flash build`)
`--no-deps`	Skip transitive dependencies
`--exclude`	Comma-separated packages to exclude
`--use-local-flash`	Bundle local runpod_flash source
`--output`, `-o`	Custom archive name

Environment Variables

RUNPOD_API_KEY - Required for deployment (get from https://runpod.io/console/user/settings)

Examples

Auto-select environment:

flash deploy
# Deploys to the only environment, or prompts if multiple exist

Deploy to specific environment:

flash deploy --env production

Deploy different app:

flash deploy --app my-app --env staging

Deploy with size optimization:

flash deploy --env prod --exclude torch,torchvision

Local preview without deploying:

flash deploy --preview
# Builds and runs in Docker locally for testing

What It Does

Runs flash build with specified options
Validates RUNPOD_API_KEY environment variable
Selects target environment (auto or via --env)
Uploads artifact to Runpod
Creates/updates serverless endpoints for each resource
Displays endpoint URLs and access information
Provides next steps for testing

Environment Selection

One environment: Used automatically
Multiple environments: Prompts for selection (or use --env)
No environments: Error (create with flash env create)

Post-Deployment

After successful deployment:

# Test endpoints
curl -X POST https://<endpoint-id>.runpod.io/run \
  -H "Authorization: Bearer $RUNPOD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"your": "data"}}'

# View deployment status
flash env get production

# Update deployment
flash deploy --env production  # Redeploy with changes

Related Commands

flash build - Build without deploying
flash env - Manage environments
flash undeploy - Delete endpoints
Build and Deploy Workflow

flash undeploy

Delete deployed Runpod serverless endpoints.

Syntax

flash undeploy [NAME] [OPTIONS]

Arguments

NAME - Endpoint name to undeploy, or list to show all endpoints

Options

Option	Description
`--all`	Undeploy all endpoints (with confirmation)
`--interactive`, `-i`	Interactive selection with checkboxes
`--cleanup-stale`	Remove endpoints already deleted externally
`--force`, `-f`	Skip confirmation prompts

Examples

List all endpoints:

flash undeploy list
# Shows all deployed endpoints with status

Undeploy specific endpoint:

flash undeploy my-api
# Prompts for confirmation before deletion

Undeploy all endpoints:

flash undeploy --all
# Prompts for confirmation, then deletes all

Force undeploy without confirmation:

flash undeploy my-api --force
# Deletes immediately, no prompts

Interactive selection:

flash undeploy --interactive
# Shows checkbox UI to select endpoints to delete

Cleanup stale tracking:

flash undeploy --cleanup-stale
# Removes endpoints from local tracking that were deleted externally

What It Does

Lists tracked endpoints (from .runpod/ directory)
Verifies endpoints exist on Runpod
Prompts for confirmation (unless --force)
Deletes endpoints via Runpod API
Removes local tracking files

Use Cases

Development cleanup:

flash undeploy --all --force
# Quick cleanup of all test deployments

Selective cleanup:

flash undeploy --interactive
# Choose which endpoints to keep/delete

Fix tracking inconsistencies:

flash undeploy --cleanup-stale
# If endpoints deleted manually via Runpod console

Related Commands

flash deploy - Deploy endpoints
flash env - View environment status
Cleanup Workflow

flash env

Manage deployment environments. Environments represent different deployment targets (e.g., staging, production).

Subcommands

flash env list - Show all environments
flash env create - Create new environment
flash env get - Show environment details
flash env delete - Delete environment

flash env list

Show all available deployment environments.

Syntax

flash env list [OPTIONS]

Options

Option	Description
`--app`, `-a`	Filter by Flash app name

Examples

List all environments:

flash env list
# Shows all environments across all apps

List environments for specific app:

flash env list --app my-app

flash env create

Create a new deployment environment.

Syntax

flash env create NAME [OPTIONS]

Arguments

NAME - Environment name (e.g., staging, production)

Options

Option	Description
`--app`, `-a`	Flash app name to create environment in

Examples

Create environment:

flash env create staging

Create environment in specific app:

flash env create production --app my-app

What It Creates

Environment entry in Flash configuration
Deployment target for flash deploy --env <name>
Isolated namespace for endpoints

flash env get

Show detailed information about a deployment environment.

Syntax

flash env get ENV_NAME [OPTIONS]

Arguments

ENV_NAME - Name of environment to inspect

Options

Option	Description
`--app`, `-a`	Flash app name

Examples

Get environment details:

flash env get production
# Shows deployed endpoints, resource configs, status

Get environment in specific app:

flash env get staging --app my-app

flash env delete

Delete a deployment environment and all its endpoints.

Syntax

flash env delete ENV_NAME [OPTIONS]

Arguments

ENV_NAME - Name of environment to delete

Options

Option	Description
`--app`, `-a`	Flash app name

Examples

Delete environment:

flash env delete staging
# Prompts for confirmation, deletes all endpoints in environment

Delete environment in specific app:

flash env delete production --app my-app

Warning

This deletes all endpoints in the environment. Ensure you have backups or can redeploy.

Related Commands

flash deploy - Deploy to environment
flash undeploy - Delete individual endpoints
Multi-Environment Workflow

flash app

Manage Flash applications. Apps provide namespace isolation for environments and endpoints.

Subcommands

flash app list - Show all apps
flash app create - Create new app
flash app get - Show app details
flash app delete - Delete app

flash app list

List all Flash applications under your account.

Syntax

flash app list

Examples

flash app list
# Shows all apps with environment counts

flash app create

Create a new Flash application.

Syntax

flash app create APP_NAME

Arguments

APP_NAME - Name for the new Flash app

Examples

Create app:

flash app create my-new-app

What It Creates

App namespace for environments and endpoints
Configuration entry for app-scoped operations

flash app get

Get detailed information about a Flash app.

Syntax

flash app get APP_NAME

Arguments

APP_NAME - Name of app to inspect

Examples

flash app get my-app
# Shows environments, endpoints, resource usage

flash app delete

Delete a Flash app and all associated resources.

Syntax

flash app delete [OPTIONS]

Options

Option	Required	Description
`--app`, `-a`	Yes	Flash app name to delete

Examples

Delete app:

flash app delete --app my-app
# Prompts for confirmation, deletes all environments and endpoints

Warning

This deletes the entire app including all environments and endpoints. This operation cannot be undone.

Related Commands

flash env - Manage environments within apps
flash deploy - Deploy to app environments

Environment Variables

Flash CLI respects these environment variables:

Variable	Purpose	Used By
`RUNPOD_API_KEY`	Runpod API authentication	`deploy`, `undeploy`, `env`, `app`
`FLASH_HOST`	Default development server host	`run`
`FLASH_PORT`	Default development server port	`run`

Setting Environment Variables

Bash/Zsh:

export RUNPOD_API_KEY=your-key-here
export FLASH_PORT=9000

.env file:

# .env (loaded into os.environ for CLI and local development)
RUNPOD_API_KEY=your-key-here
FLASH_HOST=0.0.0.0
FLASH_PORT=8888

Note: .env values populate os.environ locally. They are not carried to deployed endpoints. To pass env vars at deploy time, declare them on the resource: env={"KEY": os.environ["KEY"]}.

Configuration Files

Flash uses these configuration files:

File	Purpose	Location
`.env`	Environment variables	Project root
`.runpod/`	Deployment tracking	Project root
`flash_manifest.json`	Build artifact metadata	`.build/` (auto-generated)
`.flashignore`	Files to exclude from build	Project root

Common Workflows

See the Workflows Guide for detailed step-by-step instructions:

Local Development - Create, run, test, iterate
Build and Deploy - Package and deploy to Runpod
Multi-Environment - Manage staging and production
Testing - Validate before production
Cleanup - Remove unused resources
Troubleshooting - Debug deployment issues

Getting Help

Command-specific help: flash <command> --help
Getting Started: docs/cli/getting-started.md
Troubleshooting: docs/cli/troubleshooting.md
Flash Documentation: https://docs.runpod.io
Report Issues: https://github.com/runpod/flash/issues

Next Steps

New to Flash? Start with the Getting Started Guide
Ready to deploy? Follow the Build and Deploy Workflow
Need help? Check the Troubleshooting Guide

FilesExpand file tree

CLI-REFERENCE.md

Latest commit

History

CLI-REFERENCE.md

File metadata and controls

Flash CLI Reference

Quick Navigation

Command Overview

Core Commands

Management Commands

Learning Path

flash login

Syntax

What It Does

Examples

Alternative: Manual Configuration

Related Commands

flash init

Syntax

Arguments

Options

Examples

What It Creates

Related Commands

flash run

Syntax

Options

Environment Variables

Examples

What It Does

Testing Your Application

Related Commands

flash build

Syntax

Options

Examples

What It Does

Build Size Optimization

Debugging Builds

Related Commands

flash deploy

Syntax

Options

Environment Variables

Examples

What It Does

Environment Selection

Post-Deployment

Related Commands

flash undeploy

Syntax

Arguments

Options

Examples

What It Does

Use Cases

Related Commands

flash env

Subcommands

flash env list

Syntax

Options

Examples

flash env create

Syntax

Arguments

Options

Examples

What It Creates

flash env get

Syntax

Arguments

Options

Examples

flash env delete

Syntax

Arguments

Options

Examples