---
title: "Env"
description: "rayfin env emits a framework-specific .env.local from rayfin/.env — flags, auto-detection, and why scaffolded projects run it in predev and prebuild."
url: https://rayfin.ai/docs/reference/cli/env
markdown_url: https://rayfin.ai/docs/reference/cli/env.md
section: reference
product: Rayfin
sdk_version: 1.34.0
cli_version: 1.33.2
last_updated: 2026-08-23T01:28:43-07:00
source: reference/cli/env.mdx
---

# Env

> rayfin env emits a framework-specific .env.local from rayfin/.env — flags, auto-detection, and why scaffolded projects run it in predev and prebuild.

`rayfin env` reads the `RAYFIN_PUBLIC_*` subset of `rayfin/.env` and writes it out as a
framework-specific `.env.local` your frontend build actually reads. It's the same mechanism
`rayfin up` uses to keep `.env.local` in sync — exposed as its own command so you can
regenerate it without a full deploy.

```bash
npx rayfin env --framework vite
```

## Why it runs in `predev` / `prebuild` [#why-it-runs-in-predev--prebuild]

Scaffolded projects wire this into `package.json`:

```json title="package.json"
{
  "scripts": {
    "predev": "rayfin env --framework vite",
    "prebuild": "rayfin env --framework vite",
    "dev": "rayfin up --exclude-services staticHosting && vite",
    "build": "tsc -b && vite build"
  }
}
```

npm runs `pre*` scripts automatically before the matching script. Regenerating
`.env.local` on every `dev`/`build` invocation means the frontend always builds against the
current deployment's API URL, publishable key, and other `RAYFIN_PUBLIC_*` values — you
never hand-copy them, and a stale `.env.local` left over from a previous deployment can't
silently point the frontend at a backend that no longer exists.

## Flags [#flags]

| Flag                      | Description                                                                                                                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--framework <framework>` | Target framework: `vite`, `nextjs`, or `plain`. Auto-detected from `vite.config.*`, `next.config.*`, or `package.json` dependencies when omitted.                                              |
| `--output <dir>`          | Directory to write `.env.local` into, relative to the project root. Defaults to `services.staticHosting.path` from `rayfin.yml` when set (multi-package projects), otherwise the project root. |
| `--show`                  | Print resolved public variables to stdout and exit, without writing a file.                                                                                                                    |

If no framework can be detected and `--framework` isn't passed, the command errors with a
hint to pass it explicitly.

## Inspect without writing [#inspect-without-writing]

```bash
npx rayfin env --show
```

Prints each resolved `RAYFIN_PUBLIC_*` variable, mapped to the target framework's naming,
without touching disk.

## Framework mapping [#framework-mapping]

`rayfin env` maps each `RAYFIN_PUBLIC_*` variable in `rayfin/.env` to a framework-specific
name in `.env.local` — for example `RAYFIN_PUBLIC_API_URL` becomes `VITE_RAYFIN_API_URL`
for Vite, `NEXT_PUBLIC_RAYFIN_API_URL` for Next.js, or `API_URL` for `plain`. See
[Environment variables](/docs/reference/config/environment-variables#framework-mapping)
for the complete variable-by-variable table.

## Manual regeneration [#manual-regeneration]

Run this any time you want to refresh `.env.local` without a full deploy — for example
after manually editing `rayfin/.env`:

```bash
npx rayfin env --framework vite
```

```prompt title="Regenerate .env.local for Next.js"
My Rayfin project's rayfin/.env has values from a previous deploy, but .env.local wasn't
regenerated for my Next.js app. Run `npx rayfin env --framework nextjs` and show me the
resulting file.
```