Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs: add a way to migrate the .infisical.json to .infisical.yaml

adilsonb02434df29ef
diff --git a/docs/cli/project-config-migration.mdx b/docs/cli/project-config-migration.mdx
new file mode 100644
index 0000000000..6310220162
--- /dev/null
+++ b/docs/cli/project-config-migration.mdx
@@ -0,0 +1,151 @@
+---
+title: "Migrate to .infisical.yaml"
+description: "The Infisical CLI now reads project settings from `.infisical.yaml` instead of `.infisical.json`. Learn how to convert your project's configuration file."
+---
+
+## What changed
+
+The CLI is moving away from `.infisical.json`. It now reads [project settings](/cli/project-config) from `.infisical.yaml`. The CLI still reads `.infisical.json` for now, but a future release will stop reading it.
+
+## Who is affected
+
+You're affected if you use an `.infisical.json` file anywhere, including:
+
+- Repositories with a committed `.infisical.json`
+- Container images that copy `.infisical.json` into the image
+
+## Prerequisites
+
+{/* TODO: replace X.Y.Z with the CLI release that ships .infisical.yaml and migrate-config */}
+
+- Infisical CLI X.Y.Z or later on every machine that reads the file, including developer machines, CI pipelines, and container images ([upgrade the CLI](/cli/upgrade))
+
+Older versions of the CLI don't read `.infisical.yaml`, so after you delete `.infisical.json`, those versions can't find the project linked to the directory.
+
+## Migration steps
+
+Convert the file with the `infisical migrate-config` command, or edit it by hand.
+
+<Tabs>
+ <Tab title="Run migrate-config">
+ <Steps>
+ <Step>
+ In the directory that holds `.infisical.json`, run:
+
+ ```bash
+ infisical migrate-config
+ ```
+
+ The command copies every setting from `.infisical.json` into a new `.infisical.yaml` in the same directory, deletes `.infisical.json`, and prints the paths of both files:
+
+ ```
+ Migrated /home/user/my-app/.infisical.json to /home/user/my-app/.infisical.yaml.
+ If this project is under version control, commit the new .infisical.yaml and the removal of .infisical.json.
+ ```
+ </Step>
+ <Step>
+ Commit the new file and the deletion of the old one:
+
+ ```bash
+ git add .infisical.yaml .infisical.json
+ git commit -m "Migrate Infisical CLI config to .infisical.yaml"
+ ```
+ </Step>
+ </Steps>
+
+ The command converts one file. If your repository has more than one `.infisical.json`, such as one per package in a monorepo, run the command in each directory that holds one.
+
+ </Tab>
+ <Tab title="Edit the file by hand">
+ <Steps>
+ <Step>
+ In the directory that holds `.infisical.json`, create a file named `.infisical.yaml`. The CLI doesn't read a file named `.infisical.yml`.
+ </Step>
+ <Step>
+ Copy each field from `.infisical.json` to its key in `.infisical.yaml`:
+
+ | `.infisical.json` field | `.infisical.yaml` key |
+ | --- | --- |
+ | `workspaceId` | `secrets-management.project-id` |
+ | `defaultEnvironment` | `secrets-management.default-environment` |
+ | `gitBranchToEnvironmentMapping` | `secrets-management.mappings.git-branch-to-environment` |
+ | `defaultSecretPath` | `secrets-management.default-secret-path` |
+ | `domain` | `general.domain` |
+
+ <Note>
+ `workspaceId` is the old name for the project ID, so copy its value into `project-id` as is.
+ </Note>
+
+
+ For example, this `.infisical.json`:
+
+ ```json .infisical.json
+ {
+ "workspaceId": "<project-id>",
+ "defaultEnvironment": "dev",
+ "gitBranchToEnvironmentMapping": {
+ "main": "prod",
+ "staging": "staging"
+ },
+ "defaultSecretPath": "/backend",
+ "domain": "https://eu.infisical.com"
+ }
+ ```
+
+ becomes this `.infisical.yaml`:
+
+ ```yaml .infisical.yaml
+ general:
+ domain: https://eu.infisical.com
+ secrets-management:
+ project-id: <project-id>
+ default-environment: dev
+ default-secret-path: /backend
+ mappings:
+ git-branch-to-environment:
+ main: prod
+ staging: staging
+ ```
+
+ The CLI ignores keys it doesn't recognize, so if you misspell a key, the CLI drops that setting without reporting an error.
+ </Step>
+ <Step>
+ Delete `.infisical.json`, then commit both changes.
+ </Step>
+ </Steps>
+
+ </Tab>
+</Tabs>
+
+If a Dockerfile or CI script refers to `.infisical.json` by name, such as in a `COPY` instruction, change it to `.infisical.yaml`.
+
+## Verify the migration
+
+In the directory that holds `.infisical.yaml`, run a command that reads the file, such as:
+
+```bash
+infisical secrets
+```
+
+Check that the command lists the secrets from the project and environment you expect. If it reports that the project ID is missing, compare the keys in `.infisical.yaml` with the [field mapping](#migration-steps).
+
+## FAQ
+
+<AccordionGroup>
+ <Accordion title="What if .infisical.json and .infisical.yaml are in the same directory?">
+ The CLI can read both `.infisical.yaml` and `.infisical.json`. But
+ `.infisical.yaml` takes precedence
+ </Accordion>
+ <Accordion title="Can I run infisical init instead of migrate-config?">
+ `infisical init` writes a new `.infisical.yaml` that holds only the project
+ ID, so you lose the environment, branch mapping, folder, and instance
+ settings from `.infisical.json`. To keep those settings, run `infisical
+ migrate-config`.
+ </Accordion>
+ <Accordion title="How do I hide the deprecation notice?">
+ Set the `INFISICAL_DISABLE_WORKSPACE_CONFIG_MIGRATION_NOTICE` environment
+ variable to any value, such as `true`. The CLI prints the notice at most
+ once a day and writes it to standard error, so the notice doesn't change the
+ output of commands like `infisical export`.
+ </Accordion>
+</AccordionGroup>
diff --git a/docs/cli/project-config.mdx b/docs/cli/project-config.mdx
index 081aa7d6f5..42b0cab860 100644
--- a/docs/cli/project-config.mdx
+++ b/docs/cli/project-config.mdx
@@ -3,12 +3,16 @@ title: "Project configuration"
description: "Configure how the Infisical CLI interacts with your directory."
---
-`.infisical.json` links a directory to an [Infisical project](/documentation/platform/project). When you run a command such as [`infisical run`](/cli/reference#run) or [`infisical secrets`](/cli/reference#secrets) in that directory, the CLI reads the project from the file, so you don't have to pass [`--projectId`](/cli/reference#run--flag-projectid).
+<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`](/cli/project-config-migration).
+</Warning>
+
+`.infisical.yaml` links a directory to an [Infisical project](/documentation/platform/project). When you run a command such as [`infisical run`](/cli/reference#run) or [`infisical secrets`](/cli/reference#secrets) in that directory, the CLI reads the project from the file, so you don't have to pass [`--projectId`](/cli/reference#run--flag-projectid).
The file can also [choose an environment for you](#set-the-environment) and [pin the Infisical instance](#set-the-infisical-instance) the project lives on.
<Info>
-The `.infisical.json` file doesn't include any sensitive values and is safe to commit to version control.
+The `.infisical.yaml` file doesn't include any sensitive values and is safe to commit to version control.
</Info>
## Create the file
@@ -19,64 +23,63 @@ In the root of your codebase, run:
infisical init
```
-Select the project when prompted. The CLI writes `.infisical.json` to the current directory:
+Select the project when prompted. The CLI writes `.infisical.yaml` to the current directory:
-```json .infisical.json
-{
- "workspaceId": "<project-id>",
- "defaultEnvironment": "",
- "gitBranchToEnvironmentMapping": null
-}
+```yaml .infisical.yaml
+general: {}
+secrets-management:
+ project-id: <project-id>
+ default-environment: ""
+ mappings:
+ git-branch-to-environment: {}
```
-`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`](/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.
+`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`](/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](/documentation/platform/identities/machine-identities), `infisical run`, [`infisical export`](/cli/reference#export), and `infisical secrets` don't read `workspaceId`. Pass the project with `--projectId` or the `INFISICAL_PROJECT_ID` environment variable instead.
+ If you authenticate as a [machine identity](/documentation/platform/identities/machine-identities), `infisical run`, [`infisical export`](/cli/reference#export), and `infisical 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](/documentation/platform/secrets-mgmt/project#project-environments) unless you pass [`--env`](/cli/reference#run--flag-env). To use a different environment by default, set `defaultEnvironment` to the environment's slug:
+Without an environment setting, commands read secrets from your project's [`dev` environment](/documentation/platform/secrets-mgmt/project#project-environments) unless you pass [`--env`](/cli/reference#run--flag-env). To use a different environment by default, set `default-environment` to the environment's slug:
-```json .infisical.json
-{
- "workspaceId": "<project-id>",
- "defaultEnvironment": "staging"
-}
+```yaml .infisical.yaml
+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 in `gitBranchToEnvironmentMapping`:
-
-```json .infisical.json
-{
- "workspaceId": "<project-id>",
- "defaultEnvironment": "dev",
- "gitBranchToEnvironmentMapping": {
- "main": "prod",
- "staging": "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
+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 `defaultEnvironment`.
+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 environment mapped to your current Git branch
-3. `defaultEnvironment`
+3. `default-environment`
4. `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:
+If your project is on EU Cloud, a dedicated instance, or a self-hosted instance, set `domain` under `general` to the instance's address:
-```json .infisical.json
-{
- "workspaceId": "<project-id>",
- "domain": "https://eu.infisical.com"
-}
+```yaml .infisical.yaml
+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.
@@ -89,7 +92,7 @@ The CLI picks the instance in this order:
1. The [`--domain`](/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.json`
+3. `domain` in `.infisical.yaml`
4. US Cloud (`https://app.infisical.com`)
If you log in with your own account, [`infisical login`](/cli/reference#login) uses `domain` to choose the instance to log in to. After that:
@@ -98,12 +101,12 @@ If you log in with your own account, [`infisical login`](/cli/reference#login) u
- 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.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.
+ 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.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.
+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 run` with [`--project-config-dir`](/cli/reference#run--flag-project-config-dir):
@@ -112,27 +115,27 @@ infisical run --project-config-dir ./services/api -- npm run dev
```
<Note>
-`--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.
+`--project-config-dir` only sets the project. The environment and instance settings still come from the `.infisical.yaml` the CLI finds from your current directory.
</Note>
## Field reference
-<ResponseField name="workspaceId" type="string">
+<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="defaultEnvironment" type="string">
+<ResponseField name="secrets-management.default-environment" type="string">
The environment slug to use when `--env` isn't passed and no branch mapping matches.
</ResponseField>
-<ResponseField name="gitBranchToEnvironmentMapping" 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 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="defaultSecretPath" type="string">
+<ResponseField name="secrets-management.default-secret-path" type="string">
The folder to read secrets from when [`--path`](/cli/reference#secrets-agent-proxy-run--flag-path) and `INFISICAL_SECRET_PATH` aren't set. Only the [`infisical secrets agent-proxy`](/cli/reference#secrets-agent-proxy) commands read it.
</ResponseField>
-<ResponseField name="domain" type="string">
+<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>
diff --git a/docs/docs.json b/docs/docs.json
index 2d0977f3b4..14947ab1d3 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1333,6 +1333,7 @@
"pages": [
"cli/overview",
"cli/cloudsmith-migration",
+ "cli/project-config-migration",
{
"group": "Get started",
"pages": [