> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment Variables and Secrets

> Store tokens, API keys and connection strings as environment variables on Square Cloud from the dashboard, the CLI or the API, and read them in your code.

Keep bot tokens, API keys and database passwords out of your source code. Set them as environment variables on the application, and your code reads them at runtime like any other variable.

## Set variables

Environment variables belong to one application. They survive restarts and commits, but a new upload creates a new application without them, so set them again there.

<Tabs>
  <Tab title="Dashboard">
    1. Open your application in the [dashboard](https://squarecloud.app/en/dashboard) and go to **Settings** → **Environment Variables**.
    2. Add each key and value, or import an existing `.env` file.
    3. Click **Save**. The dashboard asks whether to restart the application: restart it so the app picks up the new values.

    When you upload a new application in the dashboard, you can also add variables on the upload screen, before the first start.
  </Tab>

  <Tab title="CLI">
    Run the commands from your project folder. The CLI targets the application whose `ID` is in your `squarecloud.app`. To target another one, pass `--app <app ID>` (for `list`, pass the ID as its argument).

    ```bash theme={"system"}
    # Add or update variables (the others stay as they are)
    squarecloud app env set DISCORD_TOKEN=your-token LOG_LEVEL=info

    # Send every line of a local .env file
    squarecloud app env set --from-file .env

    # List the current variables
    squarecloud app env list

    # Remove one variable
    squarecloud app env remove LOG_LEVEL

    # Restart to apply the changes
    squarecloud app restart
    ```

    `squarecloud app env replace` swaps the whole set for the one you pass, after a confirmation. Every command and flag is covered in [environment variables from the CLI](/en/cli-reference/environment-variables); to install the CLI and log in, see the [CLI quickstart](/en/cli-reference/quickstart).
  </Tab>

  <Tab title="VS Code">
    In the [Square Cloud extension](/en/vscode-extension/features), right-click your application in the side bar and choose **Environment variables** to list, add, edit or delete them. Restart the application afterwards to apply the changes.
  </Tab>

  <Tab title="API">
    Send the variables to [`POST /v2/apps/{app_id}/envs`](/en/api-reference/endpoint/apps/envs/add_n_edit) with an API key that has the `envs:write` scope:

    ```bash theme={"system"}
    curl -X POST "https://api.squarecloud.app/v2/apps/YOUR_APP_ID/envs" \
      -H "Authorization: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"envs": {"DISCORD_TOKEN": "your-token"}}'
    ```

    The same path also [lists](/en/api-reference/endpoint/apps/envs/get) (`GET`), [replaces](/en/api-reference/endpoint/apps/envs/overwrite) (`PUT`) and [removes](/en/api-reference/endpoint/apps/envs/remove) (`DELETE`) variables. The API doesn't restart the application: call the [restart endpoint](/en/api-reference/endpoint/apps/restart) afterwards.
  </Tab>
</Tabs>

<Warning>Variables are loaded when the application starts. After any change, restart the application, or it keeps running with the old values.</Warning>

## Read them in your code

<CodeGroup>
  ```javascript Node.js theme={"system"}
  const token = process.env.DISCORD_TOKEN;

  if (!token) {
    throw new Error("DISCORD_TOKEN is not set");
  }
  ```

  ```python Python theme={"system"}
  import os

  token = os.environ.get("DISCORD_TOKEN")

  if not token:
      raise RuntimeError("DISCORD_TOKEN is not set")
  ```
</CodeGroup>

Failing fast when a variable is missing gives you a clear message in the logs instead of a confusing error later, such as an invalid token.

## Variables Square Cloud sets for you

Your application starts with these variables already defined:

| Variable | Value | Use it to |
| - | - | - |
| `PORT` | `80` | Choose the port your web server listens on. |
| `HOST` | `0.0.0.0` | Choose the address your web server binds to. |
| `SQUARECLOUD_APP_ID` | Your application ID | Identify the application at runtime. |
| `NODE_ENV` | `production` | Tell Node.js libraries they run in production (Node.js and TypeScript runtimes). |

<Warning>Don't override `PORT` or `HOST` on a website: the platform only reaches a server on port 80 and host `0.0.0.0`.</Warning>

Because `NODE_ENV` is `production`, `npm install` skips `devDependencies`. If your `START` command builds the project (for example with `typescript` or `vite`), list those build tools under `dependencies` in `package.json`.

## How variables reach your app

Square Cloud stores the variables in a `.squarecloud/.env` file inside the application and loads them with a shell every time the application starts, before dependencies are installed and your `START` command or `MAIN` file runs. Two consequences:

* **Names** should use letters, digits and underscores, and not start with a digit.
* **Values** with spaces or shell characters such as `$`, `&`, `;` or `|` must be quoted, or the shell cuts or expands them. The dashboard and `squarecloud app env set` quote them for you. In the VS Code extension or the API, wrap such a value in single quotes yourself: type `'p@ss word$1'`, or send `"PASSWORD": "'p@ss word$1'"` in the API body.

The limits are 256 variables per application, 1,024 characters per name and 4,096 characters per value. Static websites (HTML/CSS) don't support environment variables and return `STATIC_APP_ENV_NOT_SUPPORTED`.

## Keep secrets out of your upload

If your code loads a `.env` file itself (for example with `dotenv`), that file has to be in the upload. Listing `.env` in [`squarecloud.ignore`](/en/getting-started/squarecloud-ignore) then starts the app without its secrets, and a bot fails with an invalid token.

The safer setup: move each value from your `.env` into the application's environment variables, as shown above. Once they are set, you can leave `.env` out of the upload and out of your Git repository. `dotenv` doesn't overwrite variables that already exist, so the same code keeps working on your machine and on Square Cloud.

<Warning>Never commit tokens or passwords to a public repository. If one leaks, revoke it at the provider (for example, reset the bot token in the Discord Developer Portal) and set the new value here.</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration file" icon="gear-complex-code" href="/en/getting-started/config-file">
    Set `MAIN`, `MEMORY`, `START` and the other fields of `squarecloud.app`.
  </Card>

  <Card title="Host a Discord bot" icon="discord" href="/en/tutorials/bots/discord">
    Deploy a bot that reads its token from an environment variable.
  </Card>

  <Card title="Discord bot errors" icon="bug" href="/en/platform/troubleshooting/discord-bot-errors">
    Fix an invalid token, missing intents and bots that go offline.
  </Card>

  <Card title="Database connection errors" icon="database" href="/en/platform/troubleshooting/database-connection-errors">
    Connect with a `DATABASE_URL` and the right SSL settings.
  </Card>
</CardGroup>