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

# run

> CLI reference: floo run — execute a one-shot command with a service's managed env vars injected

Run a one-shot command with a service's managed env vars injected — e.g., a test suite against cloud Postgres, a data backfill script, or a migration against the dev schema without redeploying.

`floo run` creates a short-lived dev session to fetch the service's env vars (`DATABASE_URL`, `REDIS_URL`, custom vars set via `floo env`), authorizes direct Postgres connections if the app uses managed Postgres, runs the command in the service's directory, then tears the session down on exit.

The command's exit code is propagated exactly, so a failing test suite returns non-zero.

```bash theme={null}
floo run --service <name> -- <command...>
```

Everything after `--` is the command to execute. Use `--` so flags on your command aren't interpreted 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

```bash theme={null}
# 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. No local server, no cross-service discovery — just env vars + Postgres auth for the duration of the command.

Use `floo dev` to run your app locally against cloud credentials. Use `floo run` to execute a script or test suite against them.

## 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`                                                 |
| `INVALID_PATH`           | The service's `path` in `floo.app.toml` doesn't exist on disk                             |