# Environment variables

> Set the configuration a prototype needs, for your whole team or one prototype.
> URL: https://artor.app/docs/env

Give a prototype the configuration it needs, such as an API address or a demo-service token.
Set a shared default for your organization, or a different value for one prototype.

## Commands

In your linked project folder, open a terminal and run:

```bash
artor env set API_URL=https://api.example.com --local
artor env pull
```

This saves an address for the prototype and copies it to `.env.local` on your computer.
Your prototype must be set up to use the variable. If you haven't used the terminal with
Artor yet, follow [Installing the CLI](https://artor.app/docs/install-cli).

```bash
artor env list          # see variable names and whether they can be downloaded
artor env rm API_URL    # remove the prototype's value
```

To set a value used only by the hosted prototype, leave off `--local`:

```bash
artor env set DEMO_TOKEN=your-staging-token
```

For a secret already available as `$SECRET` in your terminal, read it from a pipe so its value
doesn't appear in the command history:

```bash
printf %s "$SECRET" | artor env set DEMO_TOKEN --stdin
```

With `--stdin`, pass the name alone, without `=VALUE`.

## Scopes: org, project, version

| Scope | Applies to | How to choose it |
| --- | --- | --- |
| Organization | All prototypes in the organization | `--scope org` |
| Project | One prototype, including its versions | Default in a linked folder |
| Version | One published version | `--version v3` |

```bash
artor env set API_URL=https://demo.example.com --local --scope org  # admin access required
artor env set FEATURE_FLAG=on --version v3
artor env list --scope org
artor env rm API_URL --scope org  # admin access required
```

Outside a linked folder, use `--scope org` for `set`, `list`, and `rm`.
See the [CLI reference](https://artor.app/docs/cli#env-vars) for all flags.

### Precedence: version wins over project wins over org

Suppose the organization uses `API_URL=https://demo.example.com`, but one prototype needs
`https://research.example.com`. Set `API_URL` for that project; other prototypes keep the
organization's address. A value set for one version takes priority over both.

Changes take effect when the hosted prototype next starts, without republishing. An already
running preview keeps its current values until it goes idle and starts again. Changes to a
shared value can therefore affect older versions too. To give a particular version its own
configuration, set the value at version scope.

## Using values on your computer

| Setting | Where it can be used |
| --- | --- |
| **Server-only** (default) | The hosted prototype when opened by organization members; it cannot be downloaded with `env pull`. |
| **Local** (`--local`) | The hosted prototype, including public-link visits, and your computer after `env pull`. |

`artor env list` never shows values. Publishers can download a prototype's **local** values
with `artor env pull`, subject to its Space permissions. Any organization member can pull
organization-wide local values.

Server-only values are not provided to public-link visitors' previews, so a feature that
depends on one may not work there.

`pull` combines the project's local values with the organization's defaults. It does not pull
version-specific values and accepts no scope flag. Outside a linked folder, it pulls the
organization's local values only.

It updates Artor's section of `.env.local`, preserving your other lines. Artor excludes this
file when publishing; keep it out of Git and don't share it.

**Warning:** 
  Use staging or demo credentials, not production secrets. Prototype code can read the values
  it receives and could display or send them elsewhere. Neither setting makes a secret safe
  inside untrusted prototype code.

### `NEXT_PUBLIC_*` must be `local`

For Next.js prototypes, variables beginning with `NEXT_PUBLIC_` must be set with `--local` and
pulled **before building or publishing**. These values are visible to visitors in their browser.
Never use them for passwords or private tokens. Static prototypes also need their configuration
before publishing; changing a hosted variable does not update their existing pages.

## Who can set what

- **Organization values:** owners and admins can set and remove them.
- **Project or version values:** a [publisher seat](https://artor.app/docs/seats) and permission to edit the
  prototype's [Space](https://artor.app/docs/spaces) are required. Reviewers cannot change them.
- **List names:** organization members with access to the prototype.
- **Pull local values:** publishers with permission to download the prototype's
  source; organization-wide local values are available to organization members.

## Reserved names

Artor manages these names, so choose a different name for your own configuration:
`PORT`, `HOSTNAME`, `NODE_ENV`, `NODE_OPTIONS`, `PATH`, and `HOME`.

Use letters, numbers, and underscores. Start a name with a letter or underscore.

## Limits

Each scope supports **200 variables**, with **32 KB per value**. Empty values are not accepted.

## Related

- [Mock datasets](https://artor.app/docs/mock) — sample content for a prototype
- [Seats](https://artor.app/docs/seats) — who can publish and change configuration
- [CLI reference](https://artor.app/docs/cli#env-vars) — every command and flag