> ## 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.

## 1. Set a value

```bash theme={null}
printf '%s' "$API_KEY" | floo env set API_KEY --stdin --secret --app my-app --restart
```

`--stdin` or `--value-file` keeps secret values out of argv, shell history, and process listings. A new key is stored as a write-only secret unless its name has a [build-time prefix](#4-build-time-variables) or you pass `--config`; `--secret` turns an existing config key into a secret. `--restart` redeploys so the running app gets the new value immediately.

Values are per environment: `--env dev` is the default, and `--env prod` targets production.

## 2. Inspect values

`floo env list` masks every value:

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

`floo env get` returns config values, such as one set with `--config`. A secret-shaped config value, such as an injected `DATABASE_URL`, needs the global `--reveal-secrets` flag:

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

Use `--reveal-secrets` only when you control where the output goes. Secrets are never returned.

## 3. Scope to specific services

In multi-service apps, target services with the repeatable `--service` flag, which also accepts a comma-separated list.

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

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

# Inspect per service
floo env list --app my-app --service api
floo env get PUBLIC_API_ORIGIN --app my-app --service api
floo env import ./api/.env --app my-app --service 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. Set secrets with `--service` pointing at backend-only services.
</Warning>

**Scoping rules:**

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

Managed service env vars are provisioned at app scope. Default resources own conventional keys such as `DATABASE_URL`; named resources own suffixed keys such as `REDIS_URL_CACHE`. Until a service declares `managed`, every service receives managed credentials. In `floo.app.toml`, `[services.NAME.env] managed = []` opts that service out, including in single-service apps. The CLI rejects top-level `[env]` as an unknown key; the deploy parser ignores it with an `unknown_manifest_key` warning. Move `[env] managed = []` under `[services.NAME.env]`. Declare exactly which service receives each handle:

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

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

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

The filter applies only 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. Build-time variables

Next.js, Vite, and Create React App bake some variables into the bundle at build time. floo passes every env var whose name starts with `NEXT_PUBLIC_`, `VITE_`, or `REACT_APP_` to the image build as a Docker build arg, and injects it at runtime as well. The prefix is the contract; no flag is needed.

The Dockerfile must thread the value into the stage that runs the build, or it is empty when the bundle compiles:

```dockerfile theme={null}
FROM node:22-slim AS build
ARG VITE_API_URL
ENV VITE_API_URL=$VITE_API_URL
RUN npm run build
```

A promote rebuilds the image with prod's values when prod has any of these variables, and otherwise reuses the dev image with the dev values baked in. Set the variable in both environments when the values differ. See [Container contract](/docs/reference/container-contract#thread-build-args-into-the-build).

## 5. Import from files

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

`--all` imports from each service's configured `env_file` path.

## 6. Debug env-related failures

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

## For agents

```bash theme={null}
floo env set API_KEY --stdin --secret --app my-app --json
floo env list --app my-app --json 2>/dev/null | jq '.data.env_vars'
```

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.