Project configuration

.infisical.json links a directory to an Infisical project. When you run a command such as infisical run or infisical secrets in that directory, the CLI reads the project from the file, so you don’t have to pass --projectId. The file can also choose an environment for you and pin the Infisical instance the project lives on.

The .infisical.json file doesn’t include any sensitive values and is safe to commit to version control.

Create the file

In the root of your codebase, run:

infisical init

Select the project when prompted. The CLI writes .infisical.json to the current directory:

.infisical.json

{
    "workspaceId": "<project-id>",
    "defaultEnvironment": "",
    "gitBranchToEnvironmentMapping": null
}

workspaceId is the project’s ID. The other fields are empty until you set them, as described in the sections that follow. If you run infisical init again, the CLI replaces the file with a new one that holds only the project ID, so you lose any settings you added.

If you authenticate as a machine identity, infisical run, infisical export, and infisical secrets don’t read workspaceId. Pass the project with --projectId or the INFISICAL_PROJECT_ID environment variable instead.

Set the environment

Without an environment setting, commands read secrets from your project’s dev environment unless you pass --env. To use a different environment by default, set defaultEnvironment to the environment’s slug:

.infisical.json

{
    "workspaceId": "<project-id>",
    "defaultEnvironment": "staging"
}

To pick the environment from the Git branch you’re on, map branch names to environment slugs in gitBranchToEnvironmentMapping:

.infisical.json

{
    "workspaceId": "<project-id>",
    "defaultEnvironment": "dev",
    "gitBranchToEnvironmentMapping": {
        "main": "prod",
        "staging": "staging"
    }
}

The CLI matches only the last part of a branch name, after the final /. For example, the branch release/staging matches the key staging. If your current branch has no mapping, or you aren’t on a branch (such as when you check out a specific commit), the CLI falls back to defaultEnvironment. The CLI picks the environment in this order:

The --env flag
The environment mapped to your current Git branch
defaultEnvironment
dev

Set the Infisical instance

If your project is on EU Cloud, a dedicated instance, or a self-hosted instance, set domain to the instance’s address:

.infisical.json

{
    "workspaceId": "<project-id>",
    "domain": "https://eu.infisical.com"
}

domain must be a URL that starts with https:// or http://, or the CLI ignores it and prints a warning.

We recommend using https://, since over http://, the CLI sends secrets and credentials unencrypted.

The CLI picks the instance in this order:

The --domain flag
The INFISICAL_DOMAIN environment variable, or the older INFISICAL_API_URL if INFISICAL_DOMAIN isn’t set
domain in .infisical.json
US Cloud (https://app.infisical.com)

If you log in with your own account, infisical login uses domain to choose the instance to log in to. After that:

Any commands you run will connect to the instance you logged in to, even if domain specifies a different one
If you pass --domain or set INFISICAL_DOMAIN to a different instance than the one you logged in to, the command fails

The CLI sends every request and credential to the instance in domain. Because .infisical.json is usually committed, anyone who can change the file in your repository can change where the CLI sends them. Each time the CLI uses domain from the file, it prints a warning that names the host. Only set domain to an instance you trust, and check it when you clone a repository you don’t control.

Use the file from another directory

The CLI looks for .infisical.json in the current directory, then in each parent directory up to the root of the file system. This means that if you have an .infisical.json file in the root of your codebase, that configuration applies to every directory under it. To read the project from a file somewhere else, such as one package’s directory in a monorepo, pass the directory to infisical run with --project-config-dir:

infisical run --project-config-dir ./services/api -- npm run dev

--project-config-dir only sets the project. The environment and instance settings still come from the .infisical.json the CLI finds from your current directory.

Field reference

string

The ID of the project to read secrets from. Not used when you authenticate as a machine identity.

string

The environment slug to use when --env isn’t passed and no branch mapping matches.

object

Maps branch names to environment slugs, such as { "main": "prod" }. Keys match only the last part of a branch name, after the final /.

string

The folder to read secrets from when --path and INFISICAL_SECRET_PATH aren’t set. Only the infisical secrets agent-proxy commands read it.

string

The Infisical instance to connect to, such as https://eu.infisical.com. Must start with https:// or http://.

Get started

Command reference

Project configuration

Create the file

Set the environment

Set the Infisical instance

Use the file from another directory

Field reference

​Create the file

​Set the environment

​Set the Infisical instance

​Use the file from another directory

​Field reference

Create the file

Set the environment

Set the Infisical instance

Use the file from another directory

Field reference