From f60eaa852c7fa6ad071aab68da859af3ee40d752 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dean=20Qui=C3=B1anola?= Date: Thu, 5 Mar 2026 10:24:39 -0800 Subject: [PATCH 1/2] docs: clarify .env is for CLI only, not deployed endpoint env Update all documentation to reflect env separation: - .env populates os.environ for CLI and local dev - Resource env={} is the explicit way to set endpoint env vars - flash login is the primary auth method - Deploy-time preview shows what goes to each endpoint --- CLI-REFERENCE.md | 4 +++- CONTRIBUTING.md | 2 +- docs/cli/commands.md | 6 ++++-- docs/cli/getting-started.md | 4 ++-- docs/cli/troubleshooting.md | 31 +++++++++++++++++++++---------- docs/cli/workflows.md | 17 +++++++++-------- 6 files changed, 40 insertions(+), 24 deletions(-) diff --git a/CLI-REFERENCE.md b/CLI-REFERENCE.md index 142beba..5653416 100644 --- a/CLI-REFERENCE.md +++ b/CLI-REFERENCE.md @@ -839,12 +839,14 @@ export FLASH_PORT=9000 **.env file:** ```bash -# .env (loaded automatically by Flash) +# .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: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35181ec..a4ad5a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -332,7 +332,7 @@ To debug a worker: 4. Choose the appropriate debug configuration 5. The debugger will execute the `if __name__ == "__main__"` test block -The `.env` file is automatically loaded, so your `RUNPOD_API_KEY` is available during debugging. +The `.env` file is loaded into `os.environ` for local CLI use and debugging. To pass env vars to deployed endpoints, declare them explicitly on the resource config: `env={"KEY": os.environ["KEY"]}`. For auth, prefer `flash login`. ### Unit Tests (Recommended) diff --git a/docs/cli/commands.md b/docs/cli/commands.md index 9c309f0..62ee5c7 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -329,15 +329,17 @@ This hybrid approach enables rapid development: iterate on your orchestration lo ### Environment Variables -Variables can be set in `.env` file or exported in shell: +Variables can be set in `.env` file or exported in shell. The `.env` file populates `os.environ` for local CLI use and development -- it is not carried to deployed endpoints. ```bash -# .env file +# .env file (local CLI and development only) FLASH_HOST=0.0.0.0 FLASH_PORT=9000 RUNPOD_API_KEY=your-key-here ``` +> To pass env vars to deployed endpoints, declare them on the resource config: `env={"HF_TOKEN": os.environ["HF_TOKEN"]}`. + **Precedence (highest to lowest):** 1. Command-line options (`--host`, `--port`) 2. Environment variables (`FLASH_HOST`, `FLASH_PORT`) diff --git a/docs/cli/getting-started.md b/docs/cli/getting-started.md index 04f3a79..e32766d 100644 --- a/docs/cli/getting-started.md +++ b/docs/cli/getting-started.md @@ -27,10 +27,10 @@ uv run flash login This opens a browser for authentication and saves your credentials. -**Alternative:** Set your Runpod API key manually: +**Alternative:** Set your Runpod API key in the environment for local CLI use: ```bash export RUNPOD_API_KEY=your-key-here -# Or add to .env file: +# Or add to .env file (populates os.environ locally, not carried to deployed endpoints): echo "RUNPOD_API_KEY=your-key-here" > .env ``` diff --git a/docs/cli/troubleshooting.md b/docs/cli/troubleshooting.md index 9d689a6..1f62de8 100644 --- a/docs/cli/troubleshooting.md +++ b/docs/cli/troubleshooting.md @@ -659,7 +659,13 @@ Error: RUNPOD_API_KEY environment variable not set **Solutions:** -**1. Set environment variable:** +**1. Use `flash login` (recommended):** +```bash +flash login +# Opens browser for authentication +``` + +**2. Set environment variable:** ```bash export RUNPOD_API_KEY=your-key-here @@ -667,14 +673,14 @@ export RUNPOD_API_KEY=your-key-here echo $RUNPOD_API_KEY ``` -**2. Add to .env file:** +**3. Add to .env file (for local CLI use):** ```bash echo "RUNPOD_API_KEY=your-key-here" >> .env -# Flash automatically loads .env +# Loaded into os.environ for CLI commands ``` -**3. Get API key:** +**4. Get API key:** 1. Visit https://runpod.io/console/user/settings 2. Click "API Keys" 3. Create new key or copy existing @@ -1046,12 +1052,12 @@ export RUNPOD_API_KEY=your-key flash deploy ``` -**3. Use .env file:** +**3. Use .env file (for local CLI use):** ```bash # Create .env in project root echo "RUNPOD_API_KEY=your-key" > .env -# Flash automatically loads .env +# Loaded into os.environ for CLI commands flash deploy ``` @@ -1078,18 +1084,23 @@ ERROR: Authentication failed: API key expired **Solutions:** -**1. Generate new key:** +**1. Re-authenticate with `flash login` (recommended):** +```bash +flash login +``` + +**2. Or generate a new key manually:** 1. Visit https://runpod.io/console/user/settings 2. Revoke expired key 3. Create new key -4. Update environment variable +4. Update environment variable or `.env` file -**2. Update in all locations:** +**3. Update in all locations:** ```bash # Update environment variable export RUNPOD_API_KEY=new-key -# Update .env file +# Or update .env file (for local CLI use) echo "RUNPOD_API_KEY=new-key" > .env # Update CI/CD secrets diff --git a/docs/cli/workflows.md b/docs/cli/workflows.md index 78bc718..b008ce5 100644 --- a/docs/cli/workflows.md +++ b/docs/cli/workflows.md @@ -63,24 +63,25 @@ python --version # Should show 3.10+ uv run flash --version # Should show flash version ``` -#### 3. Configure Environment Variables +#### 3. Authenticate -```bash -# Copy example environment file -cp .env.example .env +The recommended way to authenticate is `flash login`: -# Edit .env file -# Required: RUNPOD_API_KEY (for deployment) -# Optional: FLASH_HOST, FLASH_PORT (for development) +```bash +uv run flash login ``` -Example `.env`: +Alternatively, set `RUNPOD_API_KEY` in your environment or a `.env` file for local CLI use: + ```bash +# .env file (populates os.environ for CLI and local development) RUNPOD_API_KEY=your-key-here FLASH_HOST=localhost FLASH_PORT=8888 ``` +> **Note:** `.env` values are **not** carried to deployed endpoints. To pass env vars at deploy time, declare them on the resource: `env={"KEY": os.environ["KEY"]}`. + #### 4. Start Development Server ```bash From 0b375c5c6a28af64759f7fbc3d7d552961fac123 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dean=20Qui=C3=B1anola?= Date: Fri, 6 Mar 2026 15:36:24 -0800 Subject: [PATCH 2/2] docs: address PR review feedback on env var examples - Use os.getenv() instead of os.environ[] in doc examples - Show both uv run and bare flash login invocations - Split dense paragraph into scannable bullets in CONTRIBUTING.md --- CONTRIBUTING.md | 5 ++++- docs/cli/commands.md | 2 +- docs/cli/troubleshooting.md | 5 ++++- docs/cli/workflows.md | 2 +- 4 files changed, 10 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a4ad5a1..7ed5a91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -332,7 +332,10 @@ To debug a worker: 4. Choose the appropriate debug configuration 5. The debugger will execute the `if __name__ == "__main__"` test block -The `.env` file is loaded into `os.environ` for local CLI use and debugging. To pass env vars to deployed endpoints, declare them explicitly on the resource config: `env={"KEY": os.environ["KEY"]}`. For auth, prefer `flash login`. +The `.env` file is loaded into `os.environ` for local CLI use and debugging. + +- To pass environment variables to deployed endpoints, declare them explicitly on the resource config, for example: `env={"KEY": os.getenv("KEY")}`. +- For authentication, prefer using `flash login`. ### Unit Tests (Recommended) diff --git a/docs/cli/commands.md b/docs/cli/commands.md index 62ee5c7..63e8aec 100644 --- a/docs/cli/commands.md +++ b/docs/cli/commands.md @@ -338,7 +338,7 @@ FLASH_PORT=9000 RUNPOD_API_KEY=your-key-here ``` -> To pass env vars to deployed endpoints, declare them on the resource config: `env={"HF_TOKEN": os.environ["HF_TOKEN"]}`. +> To pass env vars to deployed endpoints, declare them on the resource config: `env={"HF_TOKEN": os.getenv("HF_TOKEN")}`. **Precedence (highest to lowest):** 1. Command-line options (`--host`, `--port`) diff --git a/docs/cli/troubleshooting.md b/docs/cli/troubleshooting.md index 1f62de8..499ca73 100644 --- a/docs/cli/troubleshooting.md +++ b/docs/cli/troubleshooting.md @@ -661,8 +661,11 @@ Error: RUNPOD_API_KEY environment variable not set **1. Use `flash login` (recommended):** ```bash +# If you installed Flash via uv (recommended) +uv run flash login + +# Or, if flash is installed globally flash login -# Opens browser for authentication ``` **2. Set environment variable:** diff --git a/docs/cli/workflows.md b/docs/cli/workflows.md index b008ce5..6fe5596 100644 --- a/docs/cli/workflows.md +++ b/docs/cli/workflows.md @@ -80,7 +80,7 @@ FLASH_HOST=localhost FLASH_PORT=8888 ``` -> **Note:** `.env` values are **not** carried to deployed endpoints. To pass env vars at deploy time, declare them on the resource: `env={"KEY": os.environ["KEY"]}`. +> **Note:** `.env` values are **not** carried to deployed endpoints. To pass env vars at deploy time, declare them on the resource: `env={"KEY": os.getenv("KEY")}`. #### 4. Start Development Server