> ## 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.

# Project configuration

> Configure how the Infisical CLI interacts with your directory.

<Warning>
  `.infisical.yaml` replaces `.infisical.json`, which is deprecated. The CLI still reads `.infisical.json`, so directories that have one keep working without any changes. To move to the new format, [convert it to `.infisical.yaml`](/docs/cli/project-config-migration).
</Warning>

`.infisical.yaml` links a directory to an [Infisical project](/docs/documentation/platform/project). When you run a command such as [`infisical sm run`](/docs/cli/reference#sm-run) or [`infisical sm secrets`](/docs/cli/reference#sm-secrets) in that directory, the CLI reads the project from the file, so you don't have to pass [`--projectId`](/docs/cli/reference#sm-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.

<Info>
  The `.infisical.yaml` file doesn't include any sensitive values and is safe to commit to version control.
</Info>

## 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"}
general: {}
secrets-management:
  project-id: <project-id>
  default-environment: ""
  mappings:
    git-branch-to-environment: {}
```

`project-id` is the project's ID. The other settings are empty until you set them, as described in the sections that follow. If you run [`infisical init`](/docs/cli/reference#init) again, the CLI replaces the file with a new one that holds only the project ID, so you lose any settings you added.

<Note>
  If you authenticate as a [machine identity](/docs/documentation/platform/identities/machine-identities), `infisical sm run`, [`infisical sm export`](/docs/cli/reference#sm-export), and `infisical sm secrets` don't read `project-id`. Pass the project with `--projectId` or the `INFISICAL_PROJECT_ID` environment variable instead.
</Note>

## Set the environment

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

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

To pick the environment from the Git branch you're on, map branch names to environment slugs under `mappings.git-branch-to-environment`:

```yaml .infisical.yaml theme={"dark"}
secrets-management:
  project-id: <project-id>
  default-environment: dev
  mappings:
    git-branch-to-environment:
      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 `default-environment`.

The CLI picks the environment in this order:

1. The `--env` flag
2. The `INFISICAL_ENVIRONMENT` environment variable
3. The environment mapped to your current Git branch
4. `default-environment`
5. `dev`

## Set the folder

Without a folder setting, commands read secrets from the root of the environment (`/`) unless you pass [`--path`](/docs/cli/reference#sm-run--flag-path). To read from a different [folder](/docs/documentation/platform/folder) by default, set `default-secret-path` under `secrets-management`:

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

The CLI picks the folder in this order:

1. The `--path` flag
2. The `INFISICAL_SECRET_PATH` environment variable
3. `default-secret-path`
4. `/`

The [`infisical sm secrets folders`](/docs/cli/reference#sm-secrets-folders) commands don't read either setting, so pass `--path` to work in a folder other than `/`.

## 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:

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

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

The CLI picks the instance in this order:

1. The [`--domain`](/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. `domain` in `.infisical.yaml`
4. US Cloud (`https://app.infisical.com`)

If you log in with your own account, [`infisical login`](/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 `.infisical.yaml` 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.
</Warning>

## Use the file from another directory

The CLI looks for `.infisical.yaml` 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.yaml` 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 sm run` with [`--project-config-dir`](/docs/cli/reference#sm-run--flag-project-config-dir):

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

<Note>
  `--project-config-dir` sets the project, environment, and folder. The instance setting still comes from the `.infisical.yaml` the CLI finds from your current directory.
</Note>

## Field reference

<ResponseField name="secrets-management.project-id" type="string">
  The ID of the project to read secrets from. Not used when you authenticate as a machine identity.
</ResponseField>

<ResponseField name="secrets-management.default-environment" type="string">
  The environment slug to use when `--env` and `INFISICAL_ENVIRONMENT` aren't set and no branch mapping matches.
</ResponseField>

<ResponseField name="secrets-management.mappings.git-branch-to-environment" type="object">
  Maps branch names to environment slugs, such as `main: prod`. Keys match only the last part of a branch name, after the final `/`.
</ResponseField>

<ResponseField name="secrets-management.default-secret-path" type="string">
  The folder to read secrets from when [`--path`](/docs/cli/reference#sm-run--flag-path) and `INFISICAL_SECRET_PATH` aren't set. The `infisical sm` commands read it, except `infisical sm secrets folders`.
</ResponseField>

<ResponseField name="general.domain" type="string">
  The Infisical instance to connect to, such as `https://eu.infisical.com`. Must start with `https://` or `http://`.
</ResponseField>


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