> ## Documentation Index
> Fetch the complete documentation index at: https://getfloo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables

> Set, inspect, import, and scope env vars with the shipped Floo CLI.

Use this guide when you need to add secrets, inspect injected values, or target env vars at one service in a multi-service app.

## 1. Set a Value

```bash theme={null}
floo env set DATABASE_URL=postgres://user:pass@host:5432/db --app my-app
floo env set API_KEY=secret --app my-app --restart
```

Use `--restart` when the running app needs the new value immediately.

## 2. Inspect Values

Use masked output when you only need confirmation:

```bash theme={null}
floo env list --app my-app
```

Use plaintext output when you need the actual value:

```bash theme={null}
floo env get DATABASE_URL --app my-app
```

That `env get` path is part of the shipped CLI surface, so do not document env vars as readable only from inside the container.

## 3. Scope to Specific Services

In multi-service apps, target specific services. Most commands use `--services` (plural, repeatable). `env get` uses `--service` (singular) since it returns one value.

```bash theme={null}
# Backend secrets — api/worker only
floo env set DATABASE_URL=postgres://... --app my-app --services api
floo env set API_KEY=secret --app my-app --services api --services worker

# Frontend config — web only (public values only)
floo env set VITE_API_URL=https://my-app.getfloo.com/api --app my-app --services web

# Inspect per service
floo env list --app my-app --services api
floo env get DATABASE_URL --app my-app --service api
floo env import ./api/.env --app my-app --services api
```

<Warning>
  Never set backend secrets (`DATABASE_URL`, API keys, tokens) on frontend services. Build-time variables (`VITE_*`, `NEXT_PUBLIC_*`, `REACT_APP_*`) are baked into the JS bundle and visible to end users. Always use `--services` to target backend-only services when setting secrets.
</Warning>

**Scoping rules:**

* **Single-service app:** env vars go to the only service (no `--services` needed)
* **Multi-service app, 1 service deployed:** auto-targets that service
* **Multi-service app, 2+ services:** `--services` is required, CLI errors without it

Managed service env vars (`DATABASE_URL` + `PG*`, `REDIS_URL`, `STORAGE_BUCKET`, `STORAGE_URL`) are provisioned at app scope. Legacy apps receive them on every service by default. In single-service apps, top-level `[env] managed = []` opts out. For multi-service apps, declare exactly which service receives them:

```toml theme={null}
[services.api.env]
managed = ["postgres", "redis"]

[services.web.env]
managed = []
```

Run `floo preflight --json` and inspect `env_injection_plan` before pushing.

The filter only applies to keys owned by floo managed-service records. A user-managed external `DATABASE_URL` remains a normal env var unless the app also has floo managed Postgres owning that key.

## 4. Import From Files

```bash theme={null}
floo env import .env --app my-app
floo env import --all --app my-app
```

Use `--all` when you want Floo to import from the configured `env_file` paths across services.

## 5. Debug Env-Related Failures

```bash theme={null}
floo env list --app my-app
floo env get API_KEY --app my-app
floo logs --app my-app --error --since 30m
floo redeploy --restart --app my-app
```

## For Agents

```bash theme={null}
floo env set DATABASE_URL=postgres://... --app my-app --json
floo env list --app my-app --json 2>/dev/null | jq '.data.env_vars'
floo env get DATABASE_URL --app my-app --json 2>/dev/null | jq '.data.value'
```

<Card title="CLI Reference" href="/docs/cli/env">
  See the exact `env set`, `env get`, `env list`, `env remove`, and `env import` flags.
</Card>