Skip to content

docs: Restructure topic on env vars #1307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
szaganek wants to merge 1 commit into
base: master
Choose a base branch
from
+49 −30
Open

docs: Restructure topic on env vars #1307

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 49 additions & 30 deletions docs/vars.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,19 @@
---
description: Learn how use environment variables for Apify CLI
description: Learn how to define environment variables for your Actors using the Apify CLI.
title: Environment variables
---

There are two options how you can set up environment variables for Actors.
You can use the CLI to set environment variables for your Actors.

### Set up environment variables in `.actor/actor.json`
For the list of the system variables that Apify provides, see [Environment variables](https://docs.apify.com/actors/development/programming-interface/environment-variables).

All keys from `environmentVariables` will be set as environment variables into Apify platform after you push Actor to Apify. Current values on Apify will be overridden.
## Custom environment variables

To pass additional configuration to your Actor, define custom environment variables.

### Define in `.actor/actor.json`

To set custom variables, add them to the `environmentVariables` object in `.actor/actor.json` and push the Actor to Apify:

```json
{
Expand All @@ -22,10 +28,19 @@ All keys from `environmentVariables` will be set as environment variables into A
}
```

### Set up environment variables in Apify Console
Variables defined in `.actor/actor.json` override the ones defined in Apify Console.

### Define in Apify Console

In [Apify Console](https://console.apify.com/actors) select your Actor, you can set up variables into Source tab.
After setting up variables in the app, remove the `environmentVariables` from `.actor/actor.json`. Otherwise, variables from `.actor/actor.json` will override variables in the app.
To set custom variables in Apify Console:

1. Log in to [Apify Console](https://console.apify.com).
1. In the left-side panel, go to **Development** > **My Actors**.
1. From the table, select the Actor you want to configure.
1. Go to the **Source** tab > **Code**.
1. Expand the **Environment variables** section.

Once done, delete `environmentVariables` from `.actor/actor.json`. Variables defined in that file override the ones defined in Apify Console.

```json
{
Expand All @@ -36,41 +51,45 @@ After setting up variables in the app, remove the `environmentVariables` from `.
}
```

#### How to set secret environment variables in `.actor/actor.json`
### Define secrets

CLI provides commands to manage secrets environment variables. Secrets are stored to the `~/.apify` directory.
You can add a new secret using the command:
You can use the CLI to manage secrets environment variables:

```bash
apify secrets add mySecretPassword pwd1234
```
1. To add a secret, use the `apify secrets add` command. All secrets are stored in the `~/.apify` directory.

After adding a new secret you can use the secret in `.actor/actor.json`.
```bash
apify secrets add mySecretPassword pwd1234
```

```text
{
"actorSpecification": 1,
"name": "dataset-to-mysql",
...
"environmentVariables": {
"MYSQL_PASSWORD": "@mySecretPassword"
},
...
}
```
1. To reference the secret in `.actor/actor.json`, use the `@` prefix:

## Environment variables that configure the CLI
```text
{
"actorSpecification": 1,
"name": "dataset-to-mysql",
...
"environmentVariables": {
"MYSQL_PASSWORD": "@mySecretPassword"
},
...
}
```

Use the following environment variable to point the CLI at a non-production Apify Console, such as a staging deployment or a local instance during development.
## CLI environment variables

@patrikbraborec patrikbraborec Jul 29, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure whatever we need this section as I do not know the use case for our users. Maybe it's only for Apify internal developers, and it should be internal documentation, not public. Cc. @DaveHanns, maybe you know more details.

@DaveHanns DaveHanns Aug 3, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The repository is public and non-Apifiers can contribute (create PRs), so it is reasonable to have this public.

I would probably put it in the CONTRIBUTING.md tho (https://github.com/apify/apify-cli/blob/master/CONTRIBUTING.md).


Use the following environment variables to configure the CLI.

### `APIFY_CONSOLE_URL`

Overrides the base URL of [Apify Console](https://console.apify.com) used when the CLI prints links. For example, run, build, dataset and key-value store URLs, or the `apify login` browser flow. When unset, the production Console at `https://console.apify.com` is used.
Changes the base URL of Apify Console that the CLI prints and opens. For example, the run, build, dataset and key-value store URLs, or the browser page for the `apify login` flow.

The default value is `https://console.apify.com`.

Set it to point at a local Console instance during development:
To point the CLI at a local Console instance during development, use:

```bash
export APIFY_CONSOLE_URL=http://localhost:3000
```

With a localhost Console, `apify login` also validates your token against the local API at `http://localhost:3333`.
Note that if `APIFY_CONSOLE_URL` points at `localhost`, `apify login` validates your token against `http://localhost:3333`. All other commands still call the production API at `https://api.apify.com`.