run

Runs a one-shot command with a service’s managed env vars injected: a test suite against managed Postgres, a backfill script, or a migration against the dev database, without redeploying. floo run creates a short-lived dev session to fetch the service’s env vars (DATABASE_URL, PG*, REDIS_URL, and custom vars set via floo env), runs the command in the service’s directory, and tears the session down on exit. The command’s exit code propagates exactly, so a failing test suite returns non-zero. Write-only secrets are withheld from the dev session; supply them locally. FLOO_WITHHELD_SECRET_KEYS names the withheld keys for the selected service.

floo run --service <name> -- <command...>

Everything after -- is the command, so its flags are not parsed by floo.

Flags

Flag	Description
`--service SVC`	Service name from `floo.app.toml` whose env vars to inject (required)
`--app APP`	App name or UUID (reads from config if omitted)
`--json`	Emit a machine-readable exit summary

Examples

# Run pytest with the api service's env vars (incl. DATABASE_URL)
floo run --service api -- pytest tests/unit/

# Run a backfill script with the worker's env vars
floo run --service worker -- python scripts/seed.py

# Machine-readable exit code for CI
floo run --service api --json -- pytest

How it differs from `floo dev`

floo dev starts a long-lived local server bound to a port, with cross-service discovery so web can reach api at http://localhost:<port>.
floo run is portless and single-shot: env vars for the duration of the command, with no local server and no cross-service discovery.

Errors

Code	Meaning
`NOT_AUTHENTICATED`	Run `floo auth login` first
`NO_CONFIG_FOUND`	No `floo.app.toml` in the current directory; run `floo init` or `cd` to the project root
`INVALID_PROJECT_CONFIG`	Service name not found in `floo.app.toml`, or no command after `--`
`INVALID_PATH`	The service’s `path` in `floo.app.toml` doesn’t exist on disk

CLI

Config and runtime

Errors

API

Flags

Examples

How it differs from `floo dev`

Errors

​Flags

​Examples

​How it differs from floo dev

​Errors

Flags

Examples

How it differs from `floo dev`

Errors