CLI project configuration

Configure how the Infisical CLI interacts with your directory.

A project config file links a directory to an Infisical project. When you run a command such as infisical secrets-manager run or infisical secrets-manager 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 and a folder for you, and pin the Infisical instance the project lives on.

The CLI reads the settings from either of two files:

• .infisical.yaml, which infisical init creates
• .infisical.json, which older versions of infisical init created

Both files hold the same settings, so you don’t need to convert an existing .infisical.json. Each example on this page shows both formats.

Neither file includes any sensitive values, so both are 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.yaml to the current directory:

.infisical.yaml

version: 1
general: {}
secrets-management:
    project-id: <project-id>

project-id is the project’s ID, and version is the version of the file format. To add more settings, edit the file as described in the sections that follow.

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

If the directory already has .infisical.yaml or .infisical.json, infisical init asks before it writes a new .infisical.yaml. The new file holds only the project ID, and the CLI reads it instead of the old file, so you lose the settings in the old file. To keep those settings, edit the old file instead of running infisical init.

CLI versions earlier than 0.43.145 read only .infisical.json. If a developer machine, CI pipeline, or container image runs an older version, upgrade the CLI there before you commit .infisical.yaml.

​

Set the environment

The environment, secret-path, and overrides.git-branch keys in .infisical.yaml require CLI version 0.44.8 or later. Earlier versions read only the older default-environment, default-secret-path, and mappings.git-branch-to-environment keys. If a developer machine, CI pipeline, or container image runs an older version, upgrade the CLI there before you commit the newer keys.

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 environment under secrets-management to the environment’s slug (defaultEnvironment in .infisical.json):

.infisical.yaml

version: 1
secrets-management:
  project-id: <project-id>
  environment: staging

To pick the environment from the Git branch you’re on, list each branch and its environment slug under overrides.git-branch (gitBranchToEnvironmentMapping in .infisical.json):

.infisical.yaml

version: 1
secrets-management:
  project-id: <project-id>
  environment: dev
  overrides:
    git-branch:
      - branch: main
        environment: prod
      - branch: staging
        environment: staging

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

If an older version of infisical init wrote your .infisical.yaml, the file may set default-environment and mappings.git-branch-to-environment instead. The CLI still reads both keys. If environment is set, the CLI ignores default-environment. If overrides.git-branch has any entries, the CLI ignores mappings.git-branch-to-environment.

The CLI picks the environment in this order:

1. The --env flag
2. The INFISICAL_ENVIRONMENT environment variable
3. The environment that matches your current Git branch
4. The default environment (environment or defaultEnvironment)
5. dev

​

Set the folder

Without a folder setting, commands read secrets from the root of the environment (/) unless you pass --path. To read from a different folder by default, set secret-path under secrets-management (defaultSecretPath in .infisical.json):

.infisical.yaml

version: 1
secrets-management:
  project-id: <project-id>
  secret-path: /backend

The CLI picks the folder in this order:

1. The --path flag
2. The INFISICAL_SECRET_PATH environment variable
3. secret-path or defaultSecretPath
4. /

The CLI still reads the older default-secret-path key in .infisical.yaml, but ignores it if secret-path is set.

​

Set the Agent Vault project

infisical agent-vault run --access-bundle, infisical agent-vault sessions create, and infisical agent-vault skills push work in one Agent Vault project. These commands don’t read the project from the project config file, because secrets-management.project-id is a Secrets Management project.

To set the Agent Vault project, set INFISICAL_AGENT_VAULT_PROJECT_ID to the project’s ID, or pass --project-id. To get the ID, see Find the project ID.

The CLI picks the Agent Vault project in this order:

1. The --project-id flag
2. The INFISICAL_AGENT_VAULT_PROJECT_ID environment variable
3. The INFISICAL_PROJECT_ID environment variable

If none of these is set, the command stops with an error. If you’re logged in with a profile, run infisical profile current to see which project the CLI picked.

​

Set the Infisical instance

If your project is on EU Cloud, a dedicated instance, or a self-hosted instance, set domain under general to the instance’s address (domain in .infisical.json):

.infisical.yaml

version: 1
general:
  domain: https://eu.infisical.com
secrets-management:
  project-id: <project-id>

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:

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

Agent Vault commands skip step 3, so they never use domain from the file. If the file names a different instance from the one they would use, they stop with an error instead of connecting. To connect them to another instance, pass --domain, set INFISICAL_DOMAIN, or log in to that instance.

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 the project config file 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.

​

Where the CLI looks for the file

The CLI looks for a project config file in the current directory, then in each parent directory up to the root of the file system. If you have a project config file in the root of your codebase, that file applies to every directory under it.

In each directory, the CLI checks for .infisical.yaml first, then .infisical.json, and uses the first file it finds:

• If a directory has both files, the CLI reads .infisical.yaml and ignores .infisical.json
• If the current directory has .infisical.json and a parent directory has .infisical.yaml, the CLI reads .infisical.json
• The CLI doesn’t read a file named .infisical.yml

​

Use the file from another directory

To read the project from a file somewhere else, such as one package’s directory in a monorepo, pass the directory to infisical secrets-manager run with --project-config-dir:

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

The CLI checks only that directory, not its parent directories.

--project-config-dir sets the project, environment, and folder. The instance setting still comes from the project config file the CLI finds from your current directory.

​

Field reference

The CLI ignores keys it doesn’t recognize, so if you misspell a key, the CLI drops that setting without reporting an error.

version · number

The version of the .infisical.yaml format. infisical init sets it to 1. .infisical.json has no version field.

secrets-management.project-id · string

The ID of the project to read secrets from. Not used when you authenticate as a machine identity. In .infisical.json, the field is workspaceId.

secrets-management.environment · string

The environment slug to use when --env and INFISICAL_ENVIRONMENT aren’t set and no branch override matches. In .infisical.json, the field is defaultEnvironment.

secrets-management.overrides.git-branch · object[]

A list of branches, each with the environment slug to use on that branch, such as branch: main and environment: prod. The CLI compares each branch with only the last part of the current branch name, after the final /. In .infisical.json, the field is gitBranchToEnvironmentMapping, an object that maps branch names to environment slugs, such as "main": "prod".

secrets-management.secret-path · string

The folder to read secrets from when --path and INFISICAL_SECRET_PATH aren’t set. In .infisical.json, the field is defaultSecretPath.

general.domain · string

The Infisical instance to connect to, such as https://eu.infisical.com. Must start with https:// or http://. In .infisical.json, the field is domain.