+```
+
+### Example
+
+```bash
+flash app delete --app my-project
+```
+
+### Flags
+
+
+Name of the Flash app to delete. Required explicitly for safety.
+
+
+
+
+Unlike other subcommands, `delete` requires the `--app` flag explicitly. This is a safety measure for destructive operations.
+
+
+
+### Process
+
+1. Shows app details and resources to be deleted.
+2. Prompts for confirmation (required).
+3. Deletes all environments and their resources.
+4. Deletes all builds.
+5. Deletes the app.
+
+
+
+This operation is irreversible. All environments, builds, endpoints, volumes, and configuration will be permanently deleted.
+
+
+
+---
+
+## App hierarchy
+
+A Flash app contains environments and builds:
+
+```text
+Flash App (my-project)
+│
+├── Environments
+│ ├── dev
+│ │ ├── Endpoints (ep1, ep2)
+│ │ └── Volumes (vol1)
+│ ├── staging
+│ │ ├── Endpoints (ep1, ep2)
+│ │ └── Volumes (vol1)
+│ └── production
+│ ├── Endpoints (ep1, ep2)
+│ └── Volumes (vol1)
+│
+└── Builds
+ ├── build_v1 (2024-01-15)
+ ├── build_v2 (2024-01-18)
+ └── build_v3 (2024-01-20)
+```
+
+## Auto-detection
+
+Flash CLI automatically detects the app name from your current directory:
+
+```bash
+cd /path/to/my-project
+flash deploy # Deploys to 'my-project' app
+flash env list # Lists 'my-project' environments
+```
+
+Override with the `--app` flag:
+
+```bash
+flash deploy --app other-project
+flash env list --app other-project
+```
+
+## Related commands
+
+- [`flash env`](/flash/cli/env) - Manage environments within an app
+- [`flash deploy`](/flash/cli/deploy) - Deploy to an app's environment
+- [`flash init`](/flash/cli/init) - Create a new project
diff --git a/flash/cli/build.mdx b/flash/cli/build.mdx
new file mode 100644
index 00000000..fa125112
--- /dev/null
+++ b/flash/cli/build.mdx
@@ -0,0 +1,184 @@
+---
+title: "build"
+sidebarTitle: "build"
+---
+
+Build a deployment-ready artifact for your Flash application without deploying. Use this for more control over the build process or to inspect the artifact before deploying.
+
+```bash
+flash build [OPTIONS]
+```
+
+## Example
+
+Build with all dependencies:
+
+```bash
+flash build
+```
+
+Build and launch local preview environment:
+
+```bash
+flash build --preview
+```
+
+Build with excluded packages (for smaller deployment size):
+
+```bash
+flash build --exclude torch,torchvision,torchaudio
+```
+
+Keep the build directory for inspection:
+
+```bash
+flash build --keep-build
+```
+
+## Flags
+
+
+Skip transitive dependencies during pip install. Only installs direct dependencies specified in `@remote` decorators. Useful when the base image already includes dependencies.
+
+
+
+Keep the `.flash/.build` directory after creating the archive. Useful for debugging build issues or inspecting generated files.
+
+
+
+Custom name for the output archive file.
+
+
+
+Comma-separated list of packages to exclude from the build (e.g., `torch,torchvision`). Use this to skip packages already in the base image.
+
+
+
+Launch a local Docker-based test environment after building. Automatically enables `--keep-build`.
+
+
+## What happens during build
+
+1. **Function discovery**: Finds all `@remote` decorated functions.
+2. **Grouping**: Groups functions by their `resource_config`.
+3. **Manifest generation**: Creates `.flash/flash_manifest.json` with endpoint definitions.
+4. **Dependency installation**: Installs Python packages for Linux x86_64.
+5. **Packaging**: Bundles everything into `.flash/artifact.tar.gz`.
+
+## Build artifacts
+
+After running `flash build`:
+
+| File/Directory | Description |
+|----------------|-------------|
+| `.flash/artifact.tar.gz` | Deployment package ready for Runpod |
+| `.flash/flash_manifest.json` | Service discovery configuration |
+| `.flash/.build/` | Temporary build directory (removed unless `--keep-build`) |
+
+## Cross-platform builds
+
+Flash automatically handles cross-platform builds:
+
+- **Automatic platform targeting**: Dependencies are installed for Linux x86_64, regardless of your build platform.
+- **Python version matching**: Uses your current Python version for package compatibility.
+- **Binary wheel enforcement**: Only pre-built wheels are used, preventing compilation issues.
+
+You can build on macOS, Windows, or Linux, and the deployment will work on Runpod.
+
+## Managing deployment size
+
+Runpod Serverless has a **500MB deployment limit**. Use `--exclude` to skip packages already in your base image:
+
+```bash
+# For GPU deployments (PyTorch pre-installed)
+flash build --exclude torch,torchvision,torchaudio
+```
+
+### Base image reference
+
+| Resource type | Base image | Safe to exclude |
+|--------------|------------|-----------------|
+| GPU | PyTorch base | `torch`, `torchvision`, `torchaudio` |
+| CPU | Python slim | Do not exclude ML packages |
+
+
+
+Check the [worker-flash repository](https://github.com/runpod-workers/worker-flash) for current base images and pre-installed packages.
+
+
+
+## Preview environment
+
+Test your deployment locally before pushing to Runpod:
+
+```bash
+flash build --preview
+```
+
+This:
+
+1. Builds your project (creates archive and manifest).
+2. Creates a Docker network for inter-container communication.
+3. Starts one container per resource config (mothership + workers).
+4. Exposes the mothership on `localhost:8000`.
+5. On shutdown (`Ctrl+C`), stops and removes all containers.
+
+### When to use preview
+
+- Test deployment configuration before production.
+- Validate manifest structure.
+- Debug resource provisioning.
+- Verify cross-endpoint function calls.
+
+## Troubleshooting
+
+### Build fails with "functions not found"
+
+Ensure your project has `@remote` decorated functions:
+
+```python
+from runpod_flash import remote, LiveServerless
+
+config = LiveServerless(name="my-worker")
+
+@remote(resource_config=config)
+def my_function(data):
+ return {"result": data}
+```
+
+### Archive is too large
+
+Use `--exclude` or `--no-deps`:
+
+```bash
+flash build --exclude torch,torchvision,torchaudio
+```
+
+### Dependency installation fails
+
+If a package doesn't have Linux x86_64 wheels:
+
+1. Ensure standard pip is installed: `python -m ensurepip --upgrade`
+2. Check PyPI for Linux wheel availability.
+3. For Python 3.13+, some packages may require newer manylinux versions.
+
+### Need to examine generated files
+
+Use `--keep-build`:
+
+```bash
+flash build --keep-build
+ls .flash/.build/
+```
+
+## Related commands
+
+- [`flash deploy`](/flash/cli/deploy) - Build and deploy in one step
+- [`flash run`](/flash/cli/run) - Start development server
+- [`flash env`](/flash/cli/env) - Manage environments
+
+
+
+Most users should use `flash deploy` instead, which runs build and deploy in one step. Use `flash build` when you need more control or want to inspect the artifact.
+
+
diff --git a/flash/cli/deploy.mdx b/flash/cli/deploy.mdx
new file mode 100644
index 00000000..00ee5544
--- /dev/null
+++ b/flash/cli/deploy.mdx
@@ -0,0 +1,247 @@
+---
+title: "deploy"
+sidebarTitle: "deploy"
+---
+
+Build and deploy your Flash application to Runpod Serverless endpoints in one step. This is the primary command for getting your application running in the cloud.
+
+```bash
+flash deploy [OPTIONS]
+```
+
+## Example
+
+Build and deploy (auto-selects environment if only one exists):
+
+```bash
+flash deploy
+```
+
+Deploy to a specific environment:
+
+```bash
+flash deploy --env production
+```
+
+Deploy with excluded packages to reduce size:
+
+```bash
+flash deploy --exclude torch,torchvision,torchaudio
+```
+
+Build and test locally before deploying:
+
+```bash
+flash deploy --preview
+```
+
+## Flags
+
+
+Target environment name (e.g., `dev`, `staging`, `production`). Auto-selected if only one exists. Creates the environment if it doesn't exist.
+
+
+
+Flash app name. Auto-detected from the current directory if not specified.
+
+
+
+Skip transitive dependencies during pip install. Useful when the base image already includes dependencies.
+
+
+
+Comma-separated packages to exclude (e.g., `torch,torchvision`). Use this to stay under the 500MB deployment limit.
+
+
+
+Custom archive name for the build artifact.
+
+
+
+Build and launch a local Docker-based preview environment instead of deploying to Runpod.
+
+
+
+Bundle local `runpod_flash` source instead of the PyPI version. For development and testing only.
+
+
+## What happens during deployment
+
+1. **Build phase**: Creates the deployment artifact (same as `flash build`).
+2. **Environment resolution**: Detects or creates the target environment.
+3. **Upload**: Sends the artifact to Runpod storage.
+4. **Provisioning**: Creates or updates Serverless endpoints.
+5. **Configuration**: Sets up environment variables and service discovery.
+6. **Verification**: Confirms endpoints are healthy.
+
+## Architecture
+
+After deployment, your entire application runs on Runpod Serverless:
+
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#9289FE','primaryTextColor':'#fff','primaryBorderColor':'#9289FE','lineColor':'#5F4CFE','secondaryColor':'#AE6DFF','tertiaryColor':'#FCB1FF','edgeLabelBackground':'#5F4CFE', 'fontSize':'14px','fontFamily':'font-inter'}}}%%
+
+flowchart TB
+ Users(["USERS"])
+
+ subgraph Runpod ["RUNPOD SERVERLESS"]
+ Mothership["MOTHERSHIP ENDPOINT
(your FastAPI app from main.py)
• Your HTTP routes
• Orchestrates @remote calls
• Public URL for users"]
+ GPU["gpu-worker
(your @remote function)"]
+ CPU["cpu-worker
(your @remote function)"]
+
+ Mothership -->|"internal"| GPU
+ Mothership -->|"internal"| CPU
+ end
+
+ Users -->|"HTTPS (authenticated)"| Mothership
+
+ style Runpod fill:#1a1a2e,stroke:#5F4CFE,stroke-width:2px,color:#fff
+ style Users fill:#4D38F5,stroke:#4D38F5,color:#fff
+ style Mothership fill:#5F4CFE,stroke:#5F4CFE,color:#fff
+ style GPU fill:#22C55E,stroke:#22C55E,color:#000
+ style CPU fill:#22C55E,stroke:#22C55E,color:#000
+```
+
+
+## Environment management
+
+### Automatic creation
+
+If the specified environment doesn't exist, `flash deploy` creates it:
+
+```bash
+# Creates 'staging' if it doesn't exist
+flash deploy --env staging
+```
+
+### Auto-selection
+
+When you have only one environment, it's selected automatically:
+
+```bash
+# Auto-selects the only available environment
+flash deploy
+```
+
+When multiple environments exist, you must specify one:
+
+```bash
+# Required when multiple environments exist
+flash deploy --env staging
+```
+
+### Default environment
+
+If no environment exists and none is specified, Flash creates a `production` environment by default.
+
+## Post-deployment
+
+After successful deployment, Flash displays:
+
+```text
+✓ Deployment Complete
+
+Your mothership is deployed at:
+https://api-xxxxx.runpod.net
+
+Available Routes:
+POST /api/hello
+POST /gpu/process
+
+All endpoints require authentication:
+curl -X POST https://api-xxxxx.runpod.net/api/hello \
+ -H "Authorization: Bearer $RUNPOD_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"param": "value"}'
+```
+
+### Authentication
+
+All deployed endpoints require authentication with your Runpod API key:
+
+```bash
+export RUNPOD_API_KEY="your_key_here"
+
+curl -X POST https://YOUR_ENDPOINT_URL/path \
+ -H "Authorization: Bearer $RUNPOD_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"param": "value"}'
+```
+
+## Preview mode
+
+Test locally before deploying:
+
+```bash
+flash deploy --preview
+```
+
+This builds your project and runs it in Docker containers locally:
+
+- Mothership exposed on `localhost:8000`.
+- All containers communicate via Docker network.
+- Press `Ctrl+C` to stop.
+
+## Managing deployment size
+
+Runpod Serverless has a **500MB limit**. Use `--exclude` to skip packages in the base image:
+
+```bash
+# GPU deployments (PyTorch pre-installed)
+flash deploy --exclude torch,torchvision,torchaudio
+```
+
+| Resource type | Safe to exclude |
+|--------------|-----------------|
+| GPU | `torch`, `torchvision`, `torchaudio` |
+| CPU | Do not exclude ML packages |
+
+## flash run vs flash deploy
+
+| Aspect | `flash run` | `flash deploy` |
+|--------|-------------|----------------|
+| FastAPI app runs on | Your machine | Runpod Serverless |
+| `@remote` functions run on | Runpod Serverless | Runpod Serverless |
+| Endpoint naming | `live-` prefix | No prefix |
+| Automatic updates | Yes | No |
+| Use case | Development | Production |
+
+## Troubleshooting
+
+### Multiple environments error
+
+```text
+Error: Multiple environments found: dev, staging, production
+```
+
+Specify the target environment:
+
+```bash
+flash deploy --env staging
+```
+
+### Deployment size limit
+
+Use `--exclude` to reduce size:
+
+```bash
+flash deploy --exclude torch,torchvision,torchaudio
+```
+
+### Authentication fails
+
+Ensure your API key is set:
+
+```bash
+echo $RUNPOD_API_KEY
+export RUNPOD_API_KEY="your_key_here"
+```
+
+## Related commands
+
+- [`flash build`](/flash/cli/build) - Build without deploying
+- [`flash run`](/flash/cli/run) - Local development server
+- [`flash env`](/flash/cli/env) - Manage environments
+- [`flash app`](/flash/cli/app) - Manage applications
+- [`flash undeploy`](/flash/cli/undeploy) - Remove endpoints
diff --git a/flash/cli/env.mdx b/flash/cli/env.mdx
new file mode 100644
index 00000000..00215404
--- /dev/null
+++ b/flash/cli/env.mdx
@@ -0,0 +1,255 @@
+---
+title: "env"
+sidebarTitle: "env"
+---
+
+Manage deployment environments for Flash applications. Environments are isolated deployment contexts (like `dev`, `staging`, `production`) within a Flash app.
+
+```bash Command
+flash env [OPTIONS]
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | Show all environments for an app |
+| `create` | Create a new environment |
+| `get` | Show details of an environment |
+| `delete` | Delete an environment and its resources |
+
+---
+
+## env list
+
+Show all available environments for an app.
+
+```bash Command
+flash env list [OPTIONS]
+```
+
+### Example
+
+```bash
+# List environments for current app
+flash env list
+
+# List environments for specific app
+flash env list --app my-project
+```
+
+### Flags
+
+
+Flash app name. Auto-detected from current directory if not specified.
+
+
+### Output
+
+```text
+┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┓
+┃ Name ┃ ID ┃ Active Build ┃ Created At ┃
+┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━┩
+│ dev │ env_abc123 │ build_xyz789 │ 2024-01-15 10:30 │
+│ staging │ env_def456 │ build_uvw456 │ 2024-01-16 14:20 │
+│ production │ env_ghi789 │ build_rst123 │ 2024-01-20 09:15 │
+└────────────┴─────────────────────┴───────────────────┴──────────────────┘
+```
+
+---
+
+## env create
+
+Create a new deployment environment.
+
+```bash Command
+flash env create [OPTIONS]
+```
+
+### Example
+
+```bash
+# Create staging environment
+flash env create staging
+
+# Create environment in specific app
+flash env create production --app my-project
+```
+
+### Arguments
+
+
+Name for the new environment (e.g., `dev`, `staging`, `production`).
+
+
+### Flags
+
+
+Flash app name. Auto-detected from current directory if not specified.
+
+
+### Notes
+
+- If the app doesn't exist, it's created automatically.
+- Environment names must be unique within an app.
+- Newly created environments have no active build until first deployment.
+
+
+
+You don't always need to create environments explicitly. Running `flash deploy --env ` creates the environment automatically if it doesn't exist.
+
+
+
+---
+
+## env get
+
+Show detailed information about a deployment environment.
+
+```bash Command
+flash env get [OPTIONS]
+```
+
+### Example
+
+```bash
+# Get details for production environment
+flash env get production
+
+# Get details for specific app's environment
+flash env get staging --app my-project
+```
+
+### Arguments
+
+
+Name of the environment to inspect.
+
+
+### Flags
+
+
+Flash app name. Auto-detected from current directory if not specified.
+
+
+### Output
+
+```text
+╭────────────────────────────────────╮
+│ Environment: production │
+├────────────────────────────────────┤
+│ ID: env_ghi789 │
+│ State: DEPLOYED │
+│ Active Build: build_rst123 │
+│ Created: 2024-01-20 09:15:00 │
+╰────────────────────────────────────╯
+
+ Associated Endpoints
+┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
+┃ Name ┃ ID ┃
+┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
+│ my-gpu │ ep_abc123 │
+│ my-cpu │ ep_def456 │
+└────────────────┴────────────────────┘
+
+ Associated Network Volumes
+┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
+┃ Name ┃ ID ┃
+┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
+│ model-cache │ nv_xyz789 │
+└────────────────┴────────────────────┘
+```
+
+---
+
+## env delete
+
+Delete a deployment environment and all its associated resources.
+
+```bash Command
+flash env delete [OPTIONS]
+```
+
+### Example
+
+```bash
+# Delete development environment
+flash env delete dev
+
+# Delete environment in specific app
+flash env delete staging --app my-project
+```
+
+### Arguments
+
+
+Name of the environment to delete.
+
+
+### Flags
+
+
+Flash app name. Auto-detected from current directory if not specified.
+
+
+### Process
+
+1. Shows environment details and resources to be deleted.
+2. Prompts for confirmation (required).
+3. Undeploys all associated endpoints.
+4. Removes all associated network volumes.
+5. Deletes the environment from the app.
+
+
+
+This operation is irreversible. All endpoints, volumes, and configuration associated with the environment will be permanently deleted.
+
+
+
+---
+
+## Environment states
+
+| State | Description |
+|-------|-------------|
+| PENDING | Environment created but not deployed |
+| DEPLOYING | Deployment in progress |
+| DEPLOYED | Successfully deployed and running |
+| FAILED | Deployment or health check failed |
+| DELETING | Deletion in progress |
+
+## Common workflows
+
+### Three-tier deployment
+
+```bash
+# Create environments
+flash env create dev
+flash env create staging
+flash env create production
+
+# Deploy to each
+flash deploy --env dev
+flash deploy --env staging
+flash deploy --env production
+```
+
+### Feature branch testing
+
+```bash
+# Create feature environment
+flash env create feature-auth
+
+# Deploy feature branch
+git checkout feature-auth
+flash deploy --env feature-auth
+
+# Clean up after merge
+flash env delete feature-auth
+```
+
+## Related commands
+
+- [`flash deploy`](/flash/cli/deploy) - Deploy to an environment
+- [`flash app`](/flash/cli/app) - Manage applications
+- [`flash undeploy`](/flash/cli/undeploy) - Remove specific endpoints
diff --git a/flash/cli/init.mdx b/flash/cli/init.mdx
new file mode 100644
index 00000000..6fcf1511
--- /dev/null
+++ b/flash/cli/init.mdx
@@ -0,0 +1,89 @@
+---
+title: "init"
+sidebarTitle: "init"
+---
+
+Create a new Flash project with a ready-to-use template structure including a FastAPI server, example GPU and CPU workers, and configuration files.
+
+```bash
+flash init [PROJECT_NAME] [OPTIONS]
+```
+
+## Example
+
+Create a new project directory:
+
+```bash
+flash init my-project
+cd my-project
+pip install -r requirements.txt
+flash run
+```
+
+Initialize in the current directory:
+
+```bash
+flash init .
+```
+
+## Arguments
+
+
+Name of the project directory to create. If omitted or set to `.`, initializes in the current directory.
+
+
+## Flags
+
+
+Overwrite existing files if they already exist in the target directory.
+
+
+## What it creates
+
+The command creates the following project structure:
+
+```text
+my-project/
+├── main.py # FastAPI application entry point
+├── workers/
+│ ├── gpu/ # GPU worker example
+│ │ ├── __init__.py
+│ │ └── endpoint.py
+│ └── cpu/ # CPU worker example
+│ ├── __init__.py
+│ └── endpoint.py
+├── .env # Environment variables template
+├── .gitignore # Git ignore patterns
+├── .flashignore # Flash deployment ignore patterns
+├── requirements.txt # Python dependencies
+└── README.md # Project documentation
+```
+
+### Template contents
+
+- **main.py**: FastAPI application that imports routers from the `workers/` directory.
+- **workers/gpu/endpoint.py**: Example GPU worker with a `@remote` decorated function using `LiveServerless`.
+- **workers/cpu/endpoint.py**: Example CPU worker with a `@remote` decorated function using CPU configuration.
+- **.env**: Template for environment variables including `RUNPOD_API_KEY`.
+
+## Next steps
+
+After initialization:
+
+1. Copy `.env.example` to `.env` (if needed) and add your `RUNPOD_API_KEY`.
+2. Install dependencies: `pip install -r requirements.txt`
+3. Start the development server: `flash run`
+4. Open http://localhost:8888/docs to explore the API.
+5. Customize the workers for your use case.
+6. Deploy with `flash deploy` when ready.
+
+
+
+This command only creates local files. It doesn't interact with Runpod or create any cloud resources. Cloud resources are created when you run `flash run` or `flash deploy`.
+
+
+
+## Related commands
+
+- [`flash run`](/flash/cli/run) - Start the development server
+- [`flash deploy`](/flash/cli/deploy) - Build and deploy to Runpod
diff --git a/flash/cli/overview.mdx b/flash/cli/overview.mdx
new file mode 100644
index 00000000..aa44caba
--- /dev/null
+++ b/flash/cli/overview.mdx
@@ -0,0 +1,121 @@
+---
+title: "CLI overview"
+sidebarTitle: "Overview"
+description: "Learn how to use the Flash CLI for local development and deployment."
+---
+
+The Flash CLI provides commands for initializing projects, running local development servers, building deployment artifacts, and managing your applications on Runpod Serverless.
+
+## Install Flash
+
+Create a Python virtual environment and install Flash using pip:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install runpod-flash
+```
+
+## Configure your API key
+
+Flash requires a Runpod API key to provision and manage Serverless endpoints. Create a `.env` file in your project directory:
+
+```bash
+echo "RUNPOD_API_KEY=your_api_key_here" > .env
+```
+
+You can also set the API key as an environment variable:
+
+
+
+```bash
+export RUNPOD_API_KEY=your_api_key_here
+```
+
+
+```bash
+set RUNPOD_API_KEY=your_api_key_here
+```
+
+
+
+## Available commands
+
+| Command | Description |
+|---------|-------------|
+| [`flash init`](/flash/cli/init) | Create a new Flash project with a template structure |
+| [`flash run`](/flash/cli/run) | Start the local development server with automatic updates |
+| [`flash build`](/flash/cli/build) | Build a deployment artifact without deploying |
+| [`flash deploy`](/flash/cli/deploy) | Build and deploy your application to Runpod |
+| [`flash env`](/flash/cli/env) | Manage deployment environments |
+| [`flash app`](/flash/cli/app) | Manage Flash applications |
+| [`flash undeploy`](/flash/cli/undeploy) | Remove deployed endpoints |
+
+## Getting help
+
+View help for any command by adding `--help`:
+
+```bash
+flash --help
+flash deploy --help
+flash env --help
+```
+
+## Common workflows
+
+### Local development
+
+```bash
+# Create a new project
+flash init my-project
+cd my-project
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Add your API key to .env
+# Start the development server
+flash run
+```
+
+### Deploy to production
+
+```bash
+# Build and deploy
+flash deploy
+
+# Deploy to a specific environment
+flash deploy --env production
+```
+
+### Manage deployments
+
+```bash
+# List environments
+flash env list
+
+# Check environment status
+flash env get production
+
+# Remove an environment
+flash env delete staging
+```
+
+### Clean up endpoints
+
+```bash
+# List deployed endpoints
+flash undeploy list
+
+# Remove specific endpoint
+flash undeploy my-api
+
+# Remove all endpoints
+flash undeploy --all
+```
+
+## Next steps
+
+- [Create a project](/flash/cli/init) with `flash init`.
+- [Start developing](/flash/cli/run) with `flash run`.
+- [Deploy your app](/flash/cli/deploy) with `flash deploy`.
diff --git a/flash/cli/run.mdx b/flash/cli/run.mdx
new file mode 100644
index 00000000..4dab9e6c
--- /dev/null
+++ b/flash/cli/run.mdx
@@ -0,0 +1,156 @@
+---
+title: "run"
+sidebarTitle: "run"
+---
+
+Start the Flash development server for local testing with automatic updates. Your FastAPI app runs locally while `@remote` functions execute on Runpod Serverless.
+
+```bash
+flash run [OPTIONS]
+```
+
+## Example
+
+Start the development server with defaults:
+
+```bash
+flash run
+```
+
+Start with auto-provisioning to eliminate cold-start delays:
+
+```bash
+flash run --auto-provision
+```
+
+Start on a custom port:
+
+```bash
+flash run --port 3000
+```
+
+## Flags
+
+
+Host address to bind the server to.
+
+
+
+Port number to bind the server to.
+
+
+
+Enable or disable auto-reload on code changes. Enabled by default.
+
+
+
+Auto-provision all Serverless endpoints on startup instead of lazily on first call. Eliminates cold-start delays during development.
+
+
+## Architecture
+
+With `flash run`, your system runs in a hybrid architecture:
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#9289FE','primaryTextColor':'#fff','primaryBorderColor':'#9289FE','lineColor':'#5F4CFE','secondaryColor':'#AE6DFF','tertiaryColor':'#FCB1FF','edgeLabelBackground':'#5F4CFE', 'fontSize':'14px','fontFamily':'font-inter'}}}%%
+
+flowchart TB
+ subgraph Local ["YOUR MACHINE (localhost:8888)"]
+ FastAPI["FastAPI App (main.py)
• Your HTTP routes
• Orchestrates @remote calls
• Updates automatically"]
+ end
+
+ subgraph Runpod ["RUNPOD SERVERLESS"]
+ GPU["live-gpu-worker
(your @remote function)"]
+ CPU["live-cpu-worker
(your @remote function)"]
+ end
+
+ FastAPI -->|"HTTPS"| GPU
+ FastAPI -->|"HTTPS"| CPU
+
+ style Local fill:#1a1a2e,stroke:#5F4CFE,stroke-width:2px,color:#fff
+ style Runpod fill:#1a1a2e,stroke:#5F4CFE,stroke-width:2px,color:#fff
+ style FastAPI fill:#5F4CFE,stroke:#5F4CFE,color:#fff
+ style GPU fill:#22C55E,stroke:#22C55E,color:#000
+ style CPU fill:#22C55E,stroke:#22C55E,color:#000
+```
+
+**Key points:**
+
+- Your FastAPI app runs locally and updates automatically for rapid iteration.
+- `@remote` functions run on Runpod as Serverless endpoints.
+- Endpoints are prefixed with `live-` to distinguish from production.
+- Changes to local code are picked up instantly.
+
+This is different from `flash deploy`, where everything runs on Runpod.
+
+## Auto-provisioning
+
+By default, endpoints are provisioned lazily on first `@remote` function call. Use `--auto-provision` to provision all endpoints at server startup:
+
+```bash
+flash run --auto-provision
+```
+
+### How it works
+
+1. **Discovery**: Scans your app for `@remote` decorated functions.
+2. **Deployment**: Deploys resources concurrently (up to 3 at a time).
+3. **Confirmation**: Asks for confirmation if deploying more than 5 endpoints.
+4. **Caching**: Stores deployed resources in `.runpod/resources.pkl` for reuse.
+5. **Updates**: Recognizes existing endpoints and updates if configuration changed.
+
+### Benefits
+
+- **Zero cold start**: All endpoints ready before you test them.
+- **Faster development**: No waiting for deployment on first HTTP call.
+- **Resource reuse**: Cached endpoints are reused across server restarts.
+
+### When to use
+
+- Local development with multiple endpoints.
+- Testing workflows that call multiple remote functions.
+- Debugging where you want deployment separated from handler logic.
+
+## Provisioning modes
+
+| Mode | When endpoints are deployed |
+|------|----------------------------|
+| Default (lazy) | On first `@remote` function call |
+| `--auto-provision` | At server startup |
+
+## Testing your API
+
+Once the server is running, test your endpoints:
+
+```bash
+# Health check
+curl http://localhost:8888/
+
+# Call a GPU endpoint
+curl -X POST http://localhost:8888/gpu/hello \
+ -H "Content-Type: application/json" \
+ -d '{"message": "Hello from GPU!"}'
+```
+
+Open http://localhost:8888/docs for the interactive API explorer.
+
+## Requirements
+
+- `RUNPOD_API_KEY` must be set in your `.env` file or environment.
+- A valid Flash project structure (created by `flash init` or manually).
+
+## flash run vs flash deploy
+
+| Aspect | `flash run` | `flash deploy` |
+|--------|-------------|----------------|
+| FastAPI app runs on | Your machine (localhost) | Runpod Serverless |
+| `@remote` functions run on | Runpod Serverless | Runpod Serverless |
+| Endpoint naming | `live-` prefix | No prefix |
+| Automatic updates | Yes | No |
+| Use case | Development | Production |
+
+## Related commands
+
+- [`flash init`](/flash/cli/init) - Create a new project
+- [`flash deploy`](/flash/cli/deploy) - Deploy to production
+- [`flash undeploy`](/flash/cli/undeploy) - Remove endpoints
diff --git a/flash/cli/undeploy.mdx b/flash/cli/undeploy.mdx
new file mode 100644
index 00000000..870e4ad1
--- /dev/null
+++ b/flash/cli/undeploy.mdx
@@ -0,0 +1,213 @@
+---
+title: "undeploy"
+sidebarTitle: "undeploy"
+---
+
+Manage and delete Runpod Serverless endpoints deployed via Flash. Use this command to clean up endpoints created during local development with `flash run`.
+
+```bash
+flash undeploy [NAME|list] [OPTIONS]
+```
+
+## Example
+
+List all tracked endpoints:
+
+```bash
+flash undeploy list
+```
+
+Remove a specific endpoint:
+
+```bash
+flash undeploy my-api
+```
+
+Remove all endpoints:
+
+```bash
+flash undeploy --all
+```
+
+## Usage modes
+
+### List endpoints
+
+Display all tracked endpoints with their current status:
+
+```bash
+flash undeploy list
+```
+
+Output includes:
+
+- **Name**: Endpoint name
+- **Endpoint ID**: Runpod endpoint identifier
+- **Status**: Current health status (Active/Inactive/Unknown)
+- **Type**: Resource type (Live Serverless, Cpu Live Serverless, etc.)
+
+**Status indicators:**
+
+| Status | Meaning |
+|--------|---------|
+| Active | Endpoint is running and responding |
+| Inactive | Tracking exists but endpoint deleted externally |
+| Unknown | Error during health check |
+
+### Undeploy by name
+
+Delete a specific endpoint:
+
+```bash
+flash undeploy my-api
+```
+
+This:
+
+1. Searches for endpoints matching the name.
+2. Shows endpoint details.
+3. Prompts for confirmation.
+4. Deletes the endpoint from Runpod.
+5. Removes from local tracking.
+
+### Undeploy all
+
+Delete all tracked endpoints (requires double confirmation):
+
+```bash
+flash undeploy --all
+```
+
+Safety features:
+
+1. Shows total count of endpoints.
+2. First confirmation: Yes/No prompt.
+3. Second confirmation: Type "DELETE ALL" exactly.
+4. Deletes all endpoints from Runpod.
+5. Removes all from tracking.
+
+### Interactive selection
+
+Select endpoints to undeploy using checkboxes:
+
+```bash
+flash undeploy --interactive
+```
+
+Use arrow keys to navigate, space bar to select/deselect, and Enter to confirm.
+
+### Clean up stale tracking
+
+Remove inactive endpoints from tracking without API deletion:
+
+```bash
+flash undeploy --cleanup-stale
+```
+
+Use this when endpoints were deleted via the Runpod console or API (not through Flash). The local tracking file (`.runpod/resources.pkl`) becomes stale, and this command cleans it up.
+
+## Flags
+
+
+Undeploy all tracked endpoints. Requires double confirmation for safety.
+
+
+
+Interactive checkbox selection mode. Select multiple endpoints to undeploy.
+
+
+
+Remove inactive endpoints from local tracking without attempting API deletion. Use when endpoints were deleted externally.
+
+
+## Arguments
+
+
+Name of the endpoint to undeploy. Use `list` to show all endpoints.
+
+
+## undeploy vs env delete
+
+| Command | Scope | When to use |
+|---------|-------|-------------|
+| `flash undeploy` | Individual endpoints from local tracking | Development cleanup, granular control |
+| `flash env delete` | Entire environment + all resources | Production cleanup, full teardown |
+
+For production deployments, use `flash env delete` to remove entire environments and all associated resources.
+
+## How tracking works
+
+Flash tracks deployed endpoints in `.runpod/resources.pkl`. Endpoints are added when you:
+
+- Run `flash run --auto-provision`
+- Run `flash run` and call `@remote` functions
+- Run `flash deploy`
+
+The tracking file is in `.gitignore` and should never be committed. It contains local deployment state.
+
+## Common workflows
+
+### Basic cleanup
+
+```bash
+# Check what's deployed
+flash undeploy list
+
+# Remove a specific endpoint
+flash undeploy my-api
+
+# Clean up stale tracking
+flash undeploy --cleanup-stale
+```
+
+### Bulk operations
+
+```bash
+# Undeploy all endpoints
+flash undeploy --all
+
+# Interactive selection
+flash undeploy --interactive
+```
+
+### Managing external deletions
+
+If you delete endpoints via the Runpod console:
+
+```bash
+# Check status - will show as "Inactive"
+flash undeploy list
+
+# Remove stale tracking entries
+flash undeploy --cleanup-stale
+```
+
+## Troubleshooting
+
+### Endpoint shows as "Inactive"
+
+The endpoint was deleted via Runpod console or API. Clean up:
+
+```bash
+flash undeploy --cleanup-stale
+```
+
+### Can't find endpoint by name
+
+Check the exact name:
+
+```bash
+flash undeploy list
+```
+
+### Undeploy fails with API error
+
+1. Check `RUNPOD_API_KEY` in `.env`.
+2. Verify network connectivity.
+3. Check if the endpoint still exists on Runpod.
+
+## Related commands
+
+- [`flash run`](/flash/cli/run) - Development server (creates endpoints)
+- [`flash deploy`](/flash/cli/deploy) - Deploy to Runpod
+- [`flash env delete`](/flash/cli/env) - Delete entire environment
diff --git a/flash/deploy-apps.mdx b/flash/deploy-apps.mdx
index ff62e7ac..8497fe28 100644
--- a/flash/deploy-apps.mdx
+++ b/flash/deploy-apps.mdx
@@ -1,175 +1,227 @@
---
-title: "Build and deploy Flash apps"
-sidebarTitle: "Deploy Flash apps"
-description: "Package and deploy Flash applications for production with `flash build`."
+title: "Deploy Flash apps to Runpod"
+sidebarTitle: "Deploy to Runpod"
+description: "Bild and deploy your FastAPI app to Runpod."
tag: "BETA"
---
-Flash uses a build process to package your application for deployment. This page covers how the build process works, including handler generation, cross-platform builds, and troubleshooting common issues.
+Flash provides a complete deployment workflow for taking your local development project to production. Use `flash deploy` to build and deploy your application in a single command, or use `flash build` for more control over the build process.
-## Build process and handler generation
-When you run `flash build`, the following happens:
+## Deployment workflow
-1. **Discovery**: Flash scans your code for `@remote` decorated functions.
-2. **Grouping**: Functions are grouped by their `resource_config`.
-3. **Handler generation**: For each resource config, Flash generates a lightweight handler file.
-4. **Manifest creation**: A `flash_manifest.json` file maps functions to their endpoints.
-5. **Dependency installation**: Python packages are installed with Linux `x86_64` compatibility.
-6. **Packaging**: Everything is bundled into `archive.tar.gz` for deployment.
+A typical deployment workflow looks like this:
-### Handler architecture
+1. **Create a new project**: Use [`flash init`](/flash/cli/init) to create a new project.
+2. **Develop locally**: Use [`flash run`](/flash/cli/run) to test your application. Any functions decorated with `@remote` will be run on Runpod Serverless workers.
+3. **Preview** (optional): Use [`flash deploy --preview`](/flash/cli/deploy) to test locally with Docker.
+4. **Deploy**: Use [`flash deploy`](/flash/cli/deploy) to push to Runpod Serverless.
+5. **Manage**: Use [`flash env`](/flash/cli/env) and [`flash app`](/flash/cli/app) to manage your deployments.
-Flash uses a factory pattern for handlers to eliminate code duplication:
+## Deploy your application
-```python
-# Generated handler (handler_gpu_config.py)
-from runpod_flash.runtime.generic_handler import create_handler
-from workers.gpu import process_data
+When you're satisfied with your `@remote` functions and ready to move to production, use `flash deploy` to build and deploy your Flash application:
+
+```bash
+flash deploy
+```
+
+This command performs the following steps:
+
+1. **Build**: Packages your code, dependencies, and manifest.
+2. **Upload**: Sends the artifact to Runpod's storage.
+3. **Provision**: Creates or updates Serverless endpoints.
+4. **Configure**: Sets up environment variables and service discovery.
+5. **Verify**: Confirms endpoints are healthy.
+
+### Deployment architecture
-FUNCTION_REGISTRY = {
- "process_data": process_data,
-}
+After deployment, your entire application runs on Runpod Serverless:
-handler = create_handler(FUNCTION_REGISTRY)
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#9289FE','primaryTextColor':'#fff','primaryBorderColor':'#9289FE','lineColor':'#5F4CFE','secondaryColor':'#AE6DFF','tertiaryColor':'#FCB1FF','edgeLabelBackground':'#5F4CFE', 'fontSize':'14px','fontFamily':'font-inter'}}}%%
+
+flowchart TB
+ Users(["USERS"])
+
+ subgraph Runpod ["RUNPOD SERVERLESS"]
+ Mothership["MOTHERSHIP ENDPOINT
(your FastAPI app from main.py)
• Your HTTP routes
• Orchestrates @remote calls
• Public URL for users"]
+ GPU["gpu-worker
(your @remote function)"]
+ CPU["cpu-worker
(your @remote function)"]
+
+ Mothership -->|"internal"| GPU
+ Mothership -->|"internal"| CPU
+ end
+
+ Users -->|"HTTPS (authenticated)"| Mothership
+
+ style Runpod fill:#1a1a2e,stroke:#5F4CFE,stroke-width:2px,color:#fff
+ style Users fill:#4D38F5,stroke:#4D38F5,color:#fff
+ style Mothership fill:#5F4CFE,stroke:#5F4CFE,color:#fff
+ style GPU fill:#22C55E,stroke:#22C55E,color:#000
+ style CPU fill:#22C55E,stroke:#22C55E,color:#000
```
-This approach provides:
+### Deploy to an environment
-- **Single source of truth**: All handler logic in one place.
-- **Easier maintenance**: Bug fixes don't require rebuilding projects.
+Flash organizes deployments using [apps and environments](/flash/apps-and-environments). Deploy to a specific environment using the `--env` flag:
-## Cross-platform builds
+```bash
+# Deploy to staging
+flash deploy --env staging
-Flash automatically handles cross-platform builds, ensuring your deployments work correctly regardless of your development platform:
+# Deploy to production
+flash deploy --env production
+```
-- **Automatic platform targeting**: Dependencies are installed for Linux `x86_64` (required for [Runpod Serverless](/serverless/overview)), even when building on macOS or Windows.
-- **Python version matching**: The build uses your current Python version to ensure package compatibility.
-- **Binary wheel enforcement**: Only pre-built binary wheels are used, preventing platform-specific compilation issues.
+If the specified environment doesn't exist, Flash creates it automatically.
-This means you can build on macOS ARM64, Windows, or any other platform, and the resulting package will run correctly on [Runpod Serverless](/serverless/overview).
+### Post-deployment
-## Cross-endpoint function calls
+After a successful deployment, Flash displays:
-Flash enables functions on different endpoints to call each other:
+- The public URL for your application.
+- Available routes from your `@remote` decorated functions.
+- Instructions for authenticating requests.
-```python
-# CPU endpoint function
-@remote(resource_config=cpu_config)
-def preprocess(data):
- # Preprocessing logic
- return clean_data
-
-# GPU endpoint function
-@remote(resource_config=gpu_config)
-async def inference(data):
- # Can call CPU endpoint function
- clean = await preprocess(data)
- # Run inference on clean data
- return result
+```text
+✓ Deployment Complete
+
+Your mothership is deployed at:
+https://api-xxxxx.runpod.net
+
+Available Routes:
+POST /api/hello
+POST /gpu/process
+
+All endpoints require authentication:
+curl -X POST https://api-xxxxx.runpod.net/api/hello \
+ -H "Authorization: Bearer $RUNPOD_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{"message": "Hello"}'
```
-The runtime automatically discovers endpoints and routes calls appropriately using the [`flash_manifest.json`](#build-artifacts) file generated during the build process. This lets you build pipelines that use CPU workers for preprocessing and GPU workers for inference, optimizing costs by using the appropriate hardware for each task.
+## Preview before deploying
+
+Test your deployment locally using Docker before pushing to production:
-## Build artifacts
+```bash
+flash deploy --preview
+```
-After running `flash build`, you'll find these artifacts in the `.flash/` directory:
+This command:
-| Artifact | Description |
-|----------|-------------|
-| `.flash/.build/` | Temporary build directory (removed unless `--keep-build`) |
-| `.flash/archive.tar.gz` | Deployment package |
-| `.flash/flash_manifest.json` | Service discovery configuration |
+1. Builds your project (creates the archive and manifest).
+2. Creates a Docker network for inter-container communication.
+3. Starts one container per resource config (mothership + workers).
+4. Exposes the mothership on `localhost:8000`.
+
+Use preview mode to:
-### Managing bundle size
+- Validate your deployment configuration.
+- Test cross-endpoint function calls.
+- Debug resource provisioning issues.
+- Verify the manifest structure.
-Runpod Serverless has a **500MB deployment limit**. Exceeding this limit will cause your build to fail.
+Press `Ctrl+C` to stop the preview environment.
-Use `--exclude` to skip packages that are already included in your base worker image:
+## Managing deployment size
+
+Runpod Serverless has a **500MB deployment limit**. If your deployment exceeds this limit, use the `--exclude` flag to skip packages already included in your base worker image:
```bash
-# For GPU deployments (PyTorch pre-installed)
-flash build --exclude torch,torchvision,torchaudio
+# Exclude PyTorch packages (pre-installed in GPU images)
+flash deploy --exclude torch,torchvision,torchaudio
```
-Which packages to exclude depends on your [resource config](/flash/resource-configuration):
+### Base image packages
+
+Which packages to exclude depends on your resource configuration:
-- **GPU resources** use PyTorch as the base image, which has `torch`, `torchvision`, and `torchaudio` pre-installed.
-- **CPU resources** use Python slim images, which have no ML frameworks pre-installed.
-- **Load-balancer** resources use the same base image as their GPU/CPU counterparts.
+| Resource type | Base image | Pre-installed packages |
+|--------------|------------|------------------------|
+| GPU (`LiveServerless` with `gpus`) | PyTorch base | `torch`, `torchvision`, `torchaudio` |
+| CPU (`LiveServerless` with `instanceIds`) | Python slim | None |
+| Load-balanced | Same as GPU/CPU | Same as GPU/CPU |
- You can find details about the Flash worker image in the [runpod-workers/flash](https://github.com/runpod-workers/flash) repository. Find the `Dockerfile` for your endpoint type: `Dockerfile` (for GPU workers), `Dockerfile-cpu` (for CPU workers), or `Dockerfile-lb` (for load balancing workers).
+
+Check the [worker-flash repository](https://github.com/runpod-workers/worker-flash) for current base images and pre-installed packages.
+
-## Troubleshooting
+## Build process
-### No @remote functions found
+When you run `flash deploy` (or `flash build`), Flash:
-If the build process can't find your remote functions:
+1. **Discovers** all `@remote` decorated functions.
+2. **Groups** functions by their `resource_config`.
+3. **Generates** handler files for each resource config.
+4. **Creates** a `flash_manifest.json` file for service discovery.
+5. **Installs** dependencies with Linux x86_64 compatibility.
+6. **Packages** everything into `.flash/artifact.tar.gz`.
-- Ensure your functions are decorated with `@remote(resource_config)`.
-- Check that Python files are not excluded by `.gitignore` or `.flashignore`.
-- Verify function decorators have valid syntax.
+### Cross-platform builds
-### Handler generation failed
+Flash automatically handles cross-platform builds. You can build on macOS, Windows, or Linux, and the resulting package will run correctly on Runpod's Linux x86_64 infrastructure.
-If handler generation fails:
+### Build artifacts
-- Check for syntax errors in your Python files (they should be logged in the terminal).
-- Verify all imports in your worker modules are available.
-- Ensure resource config variables (e.g., `gpu_config`) are defined before a function references them.
-- Use `--keep-build` to inspect generated handler files in `.flash/.build/`.
+After building, these artifacts are created in the `.flash/` directory:
-### Build succeeded but deployment failed
+| Artifact | Description |
+|----------|-------------|
+| `.flash/artifact.tar.gz` | Deployment package |
+| `.flash/flash_manifest.json` | Service discovery configuration |
+| `.flash/.build/` | Temporary build directory (removed by default) |
-If the build succeeds but deployment fails:
+## Troubleshooting
-- Verify all function imports work in the deployment environment.
-- Check that environment variables required by your functions are available.
-- Review the generated `flash_manifest.json` for correct function mappings.
+### No @remote functions found
-### Dependency installation failed
+If the build process can't find your remote functions:
-If dependency installation fails during the build:
+- Ensure functions are decorated with `@remote(resource_config=...)`.
+- Check that Python files aren't excluded by `.gitignore` or `.flashignore`.
+- Verify decorator syntax is correct.
-- If a package doesn't have pre-built Linux `x86_64`` wheels, the build will fail with an error.
-- For newer Python versions (3.13+), some packages may require `manylinux_2_27`` or higher.
-- Ensure you have standard pip installed (`python -m ensurepip --upgrade`) for best compatibility.
-- Check PyPI to verify the package supports your Python version on Linux.
+### Deployment size limit exceeded
-### Authentication errors
+If your deployment exceeds 500MB:
+
+```bash
+# Exclude packages already in base image
+flash deploy --exclude torch,torchvision,torchaudio
+```
-If you're seeing authentication errors:
+### Authentication errors
Verify your API key is set correctly:
```bash
-echo $RUNPOD_API_KEY # Should show your key
+echo $RUNPOD_API_KEY
+```
+
+If not set, add it to your `.env` file or export it:
+
+```bash
+export RUNPOD_API_KEY=your_api_key_here
```
### Import errors in remote functions
-Remember to import packages inside remote functions:
+Import packages inside the remote function, not at the top of the file:
```python
-@remote(dependencies=["requests"])
+@remote(resource_config=config, dependencies=["requests"])
def fetch_data(url):
- import requests # Import here, not at top of file
+ import requests # Import here
return requests.get(url).json()
```
-## Performance optimization
-
-To optimize performance:
-
-- Set `workersMin=1` to keep workers warm and avoid cold starts.
-- Use `idleTimeout` to balance cost and responsiveness.
-- Choose appropriate GPU types for your workload.
-- Use `--auto-provision` with `flash run` to eliminate cold-start delays during development.
-
## Next steps
-- [View the resource configuration reference](/flash/resource-configuration) for all available options.
+- [Learn about apps and environments](/flash/apps-and-environments) for managing deployments.
+- [View the CLI reference](/flash/cli/overview) for all available commands.
+- [Configure resources](/flash/resource-configuration) for your endpoints.
- [Monitor and debug](/flash/monitoring) your deployments.
-- [Learn about pricing](/flash/pricing) to optimize costs.
diff --git a/flash/initialize-project.mdx b/flash/initialize-project.mdx
new file mode 100644
index 00000000..b00d4ea9
--- /dev/null
+++ b/flash/initialize-project.mdx
@@ -0,0 +1,209 @@
+---
+title: "Initialize a Flash app project"
+sidebarTitle: "Initialize a project"
+description: "Use flash init to create a new Flash project with a ready-to-use structure."
+tag: "BETA"
+---
+
+The `flash init` command creates a new Flash project with a complete project structure, including a FastAPI server, example GPU and CPU workers, and configuration files. This gives you a working starting point for building Flash applications.
+
+Use `flash init` whenever you want to start a new Flash project, fully configured for you to run `flash run` and `flash deploy`.
+
+## Create a new project
+
+Create a new project in a new directory:
+
+```bash
+flash init my-project
+cd my-project
+```
+
+Or initialize in your current directory:
+
+```bash
+flash init .
+```
+
+## Project structure
+
+`flash init` creates the following structure:
+
+```text
+my-project/
+├── main.py # FastAPI application entry point
+├── mothership.py # Mothership endpoint configuration
+├── workers/
+│ ├── gpu/ # GPU worker
+│ │ ├── __init__.py
+│ │ └── endpoint.py
+│ └── cpu/ # CPU worker
+│ ├── __init__.py
+│ └── endpoint.py
+├── .env.example # Environment variables template
+├── .flashignore # Files to exclude from deployment
+├── .gitignore # Git ignore patterns
+├── pyproject.toml # Python project configuration
+├── requirements.txt # Python dependencies
+└── README.md # Project documentation
+```
+
+### Key files
+
+**main.py**: The FastAPI application that imports and registers your worker routers.
+
+**mothership.py**: Configuration for the "mothership" endpoint—the main entry point that orchestrates calls to your workers when deployed.
+
+**workers/gpu/endpoint.py**: An example GPU worker with a `@remote` decorated function. This is where you define functions that run on GPU workers.
+
+**workers/cpu/endpoint.py**: An example CPU worker for tasks that don't require GPU acceleration.
+
+**.flashignore**: Lists files and directories to exclude from the deployment artifact (similar to `.gitignore`).
+
+## Set up the project
+
+After initialization, complete the setup:
+
+```bash
+# Install dependencies
+pip install -r requirements.txt
+
+# Copy environment template
+cp .env.example .env
+
+# Add your API key to .env
+# RUNPOD_API_KEY=your_api_key_here
+```
+
+## How it fits into the workflow
+
+`flash init` is the first step in the Flash development workflow:
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#9289FE','primaryTextColor':'#fff','primaryBorderColor':'#9289FE','lineColor':'#5F4CFE','secondaryColor':'#AE6DFF','tertiaryColor':'#FCB1FF','edgeLabelBackground':'#5F4CFE', 'fontSize':'14px','fontFamily':'font-inter'}}}%%
+
+flowchart LR
+ Init["flash init"]
+ Dev["flash run"]
+ Deploy["flash deploy"]
+
+ Init -->|"Create project"| Dev
+ Dev -->|"Test locally"| Deploy
+
+ style Init fill:#5F4CFE,stroke:#5F4CFE,color:#fff
+ style Dev fill:#22C55E,stroke:#22C55E,color:#000
+ style Deploy fill:#4D38F5,stroke:#4D38F5,color:#fff
+```
+
+1. **`flash init`**: Creates project structure and boilerplate.
+2. **`flash run`**: Starts local development server for testing.
+3. **`flash deploy`**: Builds and deploys to Runpod Serverless.
+
+## Customize your project
+
+### Add a new GPU endpoint
+
+To add a new GPU endpoint, you need to create a new file in the `workers/gpu/` directory. This file will contain the code for the endpoint and be automatically included in the FastAPI app.
+
+1. Create a new file in `workers/gpu/` with the name of the endpoint. For example, `inference.py`:
+
+```python
+# workers/gpu/inference.py
+from runpod_flash import remote, LiveServerless, GpuGroup
+
+config = LiveServerless(
+ name="inference-worker",
+ gpus=[GpuGroup.ADA_24],
+ workersMax=3,
+)
+
+@remote(resource_config=config, dependencies=["transformers", "torch"])
+def run_inference(prompt: str) -> dict:
+ # Rember to import endpoint dependencies inside the function.
+ from transformers import pipeline
+
+ generator = pipeline("text-generation", model="gpt2")
+ result = generator(prompt, max_length=50)
+ return {"output": result[0]["generated_text"]}
+```
+
+2. Add a route in `workers/gpu/__init__.py`:
+
+```python
+from fastapi import APIRouter
+from .inference import run_inference
+
+router = APIRouter(prefix="/gpu", tags=["GPU Workers"])
+
+@router.post("/inference")
+async def inference_endpoint(prompt: str):
+ result = await run_inference(prompt)
+ return result
+```
+
+3. The router is automatically included via `main.py`.
+
+### Add a CPU endpoint
+
+Follow the same pattern in `workers/cpu/`. CPU endpoints use `instanceIds` instead of `gpus`:
+
+```python
+from runpod_flash import remote, LiveServerless, CpuInstanceType
+
+config = LiveServerless(
+ name="data-processor",
+ instanceIds=[CpuInstanceType.CPU5C_4_8],
+ workersMax=2,
+)
+
+@remote(resource_config=config, dependencies=["pandas"])
+def process_data(data: list) -> dict:
+ import pandas as pd
+ df = pd.DataFrame(data)
+ return df.describe().to_dict()
+```
+
+## Handle existing files
+
+If you run `flash init` in a directory with existing files, Flash detects conflicts and prompts for confirmation:
+
+```text
+┌─ File Conflicts Detected ─────────────────────┐
+│ Warning: The following files will be │
+│ overwritten: │
+│ │
+│ • main.py │
+│ • requirements.txt │
+└───────────────────────────────────────────────┘
+Continue and overwrite these files? [y/N]:
+```
+
+Use `--force` to skip the prompt and overwrite files:
+
+```bash
+flash init . --force
+```
+
+## Start developing
+
+Once your project is set up:
+
+```bash
+# Start the development server
+flash run
+
+# Open the API explorer
+# http://localhost:8888/docs
+```
+
+Make changes to your workers, and the server reloads automatically. When you're ready, deploy with:
+
+```bash
+flash deploy
+```
+
+## Next steps
+
+- [Test locally](/flash/local-testing) with `flash run`.
+- [Build your app](/flash/build-app) by customizing workers.
+- [Deploy to production](/flash/deploy-apps) with `flash deploy`.
+- [View the flash init reference](/flash/cli/init) for all options.
diff --git a/flash/local-testing.mdx b/flash/local-testing.mdx
new file mode 100644
index 00000000..d19beeb9
--- /dev/null
+++ b/flash/local-testing.mdx
@@ -0,0 +1,174 @@
+---
+title: "Test Flash apps locally"
+sidebarTitle: "Test locally"
+description: "Use flash run to test your Flash application locally before deploying."
+tag: "BETA"
+---
+
+The `flash run` command starts a local development server that lets you test your Flash application before deploying to production. Your FastAPI app runs locally with automatic reloading, while `@remote` functions execute on Runpod Serverless workers.
+
+Use `flash run` when you want to:
+
+- Iterate quickly on your API logic with automatic reloading.
+- Test `@remote` functions against real GPU/CPU workers.
+- Debug request/response handling before deployment.
+- Develop new endpoints without deploying after every change.
+
+## Start the development server
+
+From inside your [project directory](/flash/initialize-project), run:
+
+```bash
+flash run
+```
+
+The server starts at `http://localhost:8888` by default. Your FastAPI routes are available immediately, and `@remote` functions provision Serverless endpoints on first call.
+
+### Custom host and port
+
+```bash
+# Change port
+flash run --port 3000
+
+# Make accessible on network
+flash run --host 0.0.0.0
+```
+
+## Test your endpoints
+
+### Using curl
+
+```bash
+curl -X POST http://localhost:8888/gpu/hello \
+ -H "Content-Type: application/json" \
+ -d '{"name": "Flash"}'
+```
+
+### Using the API explorer
+
+Open [http://localhost:8888/docs](http://localhost:8888/docs) in your browser to access the interactive Swagger UI. You can test all endpoints directly from the browser.
+
+### Using Python
+
+```python
+import requests
+
+response = requests.post(
+ "http://localhost:8888/gpu/hello",
+ json={"name": "Flash"}
+)
+print(response.json())
+```
+
+## Reduce cold-start delays
+
+The first call to a `@remote` function provisions a Serverless endpoint, which takes 30-60 seconds. Use `--auto-provision` to provision all endpoints at startup:
+
+```bash
+flash run --auto-provision
+```
+
+This scans your project for `@remote` functions and deploys them before the server starts accepting requests. Endpoints are cached in `.runpod/resources.pkl` and reused across server restarts.
+
+## How it works
+
+With `flash run`, your system runs in a hybrid architecture:
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#9289FE','primaryTextColor':'#fff','primaryBorderColor':'#9289FE','lineColor':'#5F4CFE','secondaryColor':'#AE6DFF','tertiaryColor':'#FCB1FF','edgeLabelBackground':'#5F4CFE', 'fontSize':'14px','fontFamily':'font-inter'}}}%%
+
+flowchart TB
+ subgraph Local ["YOUR MACHINE (localhost:8888)"]
+ FastAPI["FastAPI App
• Updates automatically
• Your HTTP routes"]
+ end
+
+ subgraph Runpod ["RUNPOD SERVERLESS"]
+ GPU["live-gpu-worker"]
+ CPU["live-cpu-worker"]
+ end
+
+ FastAPI -->|"HTTPS"| GPU
+ FastAPI -->|"HTTPS"| CPU
+
+ style Local fill:#1a1a2e,stroke:#5F4CFE,stroke-width:2px,color:#fff
+ style Runpod fill:#1a1a2e,stroke:#5F4CFE,stroke-width:2px,color:#fff
+ style FastAPI fill:#5F4CFE,stroke:#5F4CFE,color:#fff
+ style GPU fill:#22C55E,stroke:#22C55E,color:#000
+ style CPU fill:#22C55E,stroke:#22C55E,color:#000
+```
+
+**What runs where:**
+
+| Component | Location | Automatic updates |
+|-----------|----------|------------|
+| FastAPI app (`main.py`) | Your machine | Yes |
+| HTTP routes | Your machine | Yes |
+| `@remote` functions | Runpod Serverless | No |
+
+Endpoints created by `flash run` are prefixed with `live-` to distinguish them from production endpoints.
+
+## Development workflow
+
+A typical development cycle looks like this:
+
+1. Start the server: `flash run`
+2. Make changes to your code.
+3. The server reloads automatically.
+4. Test your changes via curl or the API explorer.
+5. Repeat until ready to deploy.
+
+When you're done, use `flash undeploy` to clean up the `live-` endpoints created during development.
+
+## Differences from production
+
+| Aspect | `flash run` | `flash deploy` |
+|--------|-------------|----------------|
+| FastAPI app runs on | Your machine | Runpod Serverless |
+| Endpoint naming | `live-` prefix | No prefix |
+| Automatic updates | Yes | No |
+| Authentication | Not required | Required |
+
+## Clean up after testing
+
+Endpoints created by `flash run` persist until you delete them. To clean up:
+
+```bash
+# List all endpoints
+flash undeploy list
+
+# Remove a specific endpoint
+flash undeploy live-YOUR_ENDPOINT_NAME
+
+# Remove all endpoints
+flash undeploy --all
+```
+
+## Troubleshooting
+
+**Port already in use**
+
+```bash
+flash run --port 3000
+```
+
+**Slow first request**
+
+Use `--auto-provision` to eliminate cold-start delays:
+
+```bash
+flash run --auto-provision
+```
+
+**Authentication errors**
+
+Ensure `RUNPOD_API_KEY` is set in your `.env` file or environment:
+
+```bash
+export RUNPOD_API_KEY=your_api_key_here
+```
+
+## Next steps
+
+- [Deploy to production](/flash/deploy-apps) when your app is ready.
+- [Clean up endpoints](/flash/cli/undeploy) after testing.
+- [View the flash run reference](/flash/cli/run) for all options.
diff --git a/flash/monitoring.mdx b/flash/monitoring.mdx
index fb206f58..33da1d53 100644
--- a/flash/monitoring.mdx
+++ b/flash/monitoring.mdx
@@ -1,6 +1,6 @@
---
-title: "Monitoring and debugging"
-sidebarTitle: "Monitoring and debugging"
+title: "Monitor and debug remote functions"
+sidebarTitle: "Monitor and debug"
description: "Monitor, debug, and troubleshoot Flash deployments."
tag: "BETA"
---
@@ -178,14 +178,54 @@ export RUNPOD_API_KEY=your_api_key_here
## Endpoint management
-As you work with Flash, endpoints accumulate in your Runpod account. To manage them:
+As you work with Flash, endpoints accumulate in your Runpod account. Use `flash undeploy` to manage and clean up endpoints.
-1. Go to the [Serverless section](https://www.runpod.io/console/serverless) in the Runpod console.
-2. Review your endpoints and delete unused ones.
-3. Note that a `flash undeploy` command is in development for easier cleanup.
+### List deployed endpoints
-
+View all tracked endpoints with their status:
-Endpoints persist until manually deleted through the Runpod console. Regularly clean up unused endpoints to avoid hitting your account's maximum worker capacity limits.
+```bash
+flash undeploy list
+```
+
+This shows each endpoint's name, ID, status (Active/Inactive), and resource type.
+
+### Undeploy specific endpoints
+
+Remove a specific endpoint by name:
+
+```bash
+flash undeploy my-api
+```
+
+### Undeploy all endpoints
+
+Remove all tracked endpoints (requires confirmation):
+
+```bash
+flash undeploy --all
+```
+
+### Interactive selection
+
+Select endpoints to undeploy using an interactive interface:
+
+```bash
+flash undeploy --interactive
+```
+
+### Clean up stale tracking
+
+If you delete endpoints through the Runpod console, the local tracking file becomes stale. Clean it up with:
+
+```bash
+flash undeploy --cleanup-stale
+```
+
+For production deployments, use `flash env delete` to remove an entire environment and all its associated resources.
+
+
+
+For detailed documentation on the undeploy command, see the [flash undeploy CLI reference](/flash/cli/undeploy).
-
\ No newline at end of file
+