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

# CLI project configuration

> Configure how the Infisical CLI interacts with your directory.

A project config file links a directory to an [Infisical project](https://infisical.com/docs/documentation/platform/project.md). When you run a command such as [`infisical secrets-manager run`](https://infisical.com/docs/cli/reference#secrets-manager-run) or [`infisical secrets-manager secrets`](https://infisical.com/docs/cli/reference#secrets-manager-secrets) in that directory, the CLI reads the project from the file, so you don't have to pass [`--projectId`](https://infisical.com/docs/cli/reference#secrets-manager-run--flag-projectid).

The file can also [choose an environment](#set-the-environment) and [a folder](#set-the-folder) for you, and [pin the Infisical instance](#set-the-infisical-instance) the project lives on.

The CLI reads the settings from either of two files:

* `.infisical.yaml`, which [`infisical init`](https://infisical.com/docs/cli/reference#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.

> [!NOTE]
>
> 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:

```bash theme={"dark"}
infisical init
```

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

```yaml .infisical.yaml theme={"dark"}
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.

> [!NOTE]
>
> If you authenticate as a [machine identity](https://infisical.com/docs/documentation/platform/identities/machine-identities.md), `infisical secrets-manager run`, [`infisical secrets-manager secrets export`](https://infisical.com/docs/cli/reference#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`.

> [!NOTE]
>
> 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](https://infisical.com/docs/cli/upgrade.md) there before you commit `.infisical.yaml`.

## Set the environment

> [!NOTE]
>
> 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](https://infisical.com/docs/cli/upgrade.md) there before you commit the newer keys.

Without an environment setting, commands read secrets from your project's [`dev` environment](https://infisical.com/docs/documentation/platform/secrets-mgmt/project#project-environments) unless you pass [`--env`](https://infisical.com/docs/cli/reference#secrets-manager-run--flag-env). To use a different environment by default, set `environment` under `secrets-management` to the environment's slug (`defaultEnvironment` in `.infisical.json`):

```yaml .infisical.yaml theme={"dark"}
version: 1
secrets-management:
  project-id: <project-id>
  environment: staging
```

```json .infisical.json (deprecated) theme={"dark"}
{
  "workspaceId": "<project-id>",
  "defaultEnvironment": "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`):

```yaml .infisical.yaml theme={"dark"}
version: 1
secrets-management:
  project-id: <project-id>
  environment: dev
  overrides:
    git-branch:
      - branch: main
        environment: prod
      - branch: staging
        environment: staging
```

```json .infisical.json (deprecated) theme={"dark"}
{
  "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 `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.

> [!NOTE]
>
> 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`](https://infisical.com/docs/cli/reference#secrets-manager-run--flag-path). To read from a different [folder](https://infisical.com/docs/documentation/platform/folder.md) by default, set `secret-path` under `secrets-management` (`defaultSecretPath` in `.infisical.json`):

```yaml .infisical.yaml theme={"dark"}
version: 1
secrets-management:
  project-id: <project-id>
  secret-path: /backend
```

```json .infisical.json (deprecated) theme={"dark"}
{
  "workspaceId": "<project-id>",
  "defaultSecretPath": "/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`](https://infisical.com/docs/cli/reference#agent-vault-run), [`infisical agent-vault sessions create`](https://infisical.com/docs/cli/reference#agent-vault-sessions-create), and [`infisical agent-vault skills push`](https://infisical.com/docs/cli/reference#agent-vault-skills-push) work in one [Agent Vault project](https://infisical.com/docs/documentation/platform/agent-vault/projects.md). 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](https://infisical.com/docs/documentation/platform/agent-vault/projects.md#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`](https://infisical.com/docs/cli/reference#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`):

```yaml .infisical.yaml theme={"dark"}
version: 1
general:
  domain: https://eu.infisical.com
secrets-management:
  project-id: <project-id>
```

```json .infisical.json (deprecated) theme={"dark"}
{
  "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.

> [!NOTE]
>
> 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`](https://infisical.com/docs/cli/reference#global-flags--flag-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](https://infisical.com/docs/cli/reference.md#agent-vault) 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`](https://infisical.com/docs/cli/reference#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

> [!WARNING]
>
> 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`](https://infisical.com/docs/cli/reference#secrets-manager-run--flag-project-config-dir):

```bash theme={"dark"}
infisical secrets-manager run --project-config-dir ./services/api -- npm run dev
```

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

> [!NOTE]
>
> `--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`](https://infisical.com/docs/cli/reference#secrets-manager-run--flag-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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.