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

# Inject secrets into local development

> Run your application on your own machine with secrets pulled from Infisical instead of a .env file.

This guide shows you how to inject secrets from Infisical into your local application without using a `.env` file. You'll install the [Infisical CLI](https://infisical.com/docs/cli/install.md), link your codebase to your Infisical project, and start your application through `infisical secrets-manager run`.

> [!NOTE]
>
> `infisical secrets-manager run` injects secrets as environment variables, so it works with any language or framework. To read secrets from inside your application code instead, use a [framework integration](https://infisical.com/docs/integrations/overview.md?type=Framework).

## Prerequisites

* An Infisical project with secrets in its **Development** environment. If you don't have one yet, follow the [quickstart](https://infisical.com/docs/documentation/platform/secrets-mgmt/quick-starts/deliver-first-secret.md) first.

## Step 1: Install the CLI

Install the CLI with the package manager for your operating system.

```bash macOS theme={"dark"}
brew install infisical/get-cli/infisical
```

```bash Windows (winget) theme={"dark"}
winget install infisical
```

```bash Windows (Scoop) theme={"dark"}
scoop bucket add org https://github.com/Infisical/scoop-infisical.git
scoop install infisical
```

```bash npm theme={"dark"}
npm install -g @infisical/cli
```

```bash Debian/Ubuntu theme={"dark"}
curl -1sLf 'https://artifacts-cli.infisical.com/setup.deb.sh' | sudo -E bash
sudo apt-get update && sudo apt-get install -y infisical
```

```bash RedHat/CentOS/Amazon Linux theme={"dark"}
curl -1sLf 'https://artifacts-cli.infisical.com/setup.rpm.sh' | sudo -E bash
sudo yum install infisical
```

```bash Alpine theme={"dark"}
apk add --no-cache bash sudo wget
wget -qO- 'https://artifacts-cli.infisical.com/setup.apk.sh' | sudo sh
apk update && sudo apk add infisical
```

```bash Arch Linux theme={"dark"}
yay -S infisical-bin
```

Check that the installation worked:

```bash theme={"dark"}
infisical --version
```

## Step 2: Inject secrets into your application

> [!TIP]
>
> If you prefer to learn by watching, follow along with our [step-by-step video tutorial](https://www.youtube.com/watch?v=WQz6BCygORA).

### Log in to Infisical

Authenticate the CLI with your Infisical account.

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

The prompt asks which instance you want to use. Select **Infisical Cloud (US Region)**, **Infisical Cloud (EU Region)**, or **Self-Hosting or Dedicated Instance**, then finish signing in through your browser.

> [!NOTE]
>
> On a machine with no browser, such as a remote SSH session, WSL 2, or Codespaces, run `infisical login -i` to log in from the terminal instead.

### Link your codebase to your project

Go to the directory of the codebase you're working on and link it to your Infisical project.

```bash theme={"dark"}
cd /path/to/your/project
infisical init
```

Select your organization and project when prompted. This creates an `.infisical.yaml` file with your [local project settings](https://infisical.com/docs/cli/project-config.md), so the commands you run next don't need a project ID.

> [!NOTE]
>
> `.infisical.yaml` holds no secret values, so you can safely commit it to version control. Everyone who clones the repository is then pointed at the same project.

### Start your application with secrets injected

Run your usual start command through `infisical secrets-manager run`, placing it after the `--` separator.

```bash Node.js theme={"dark"}
infisical secrets-manager run --env=dev -- npm run dev
```

```bash Python theme={"dark"}
infisical secrets-manager run --env=dev -- flask run
```

```bash Go theme={"dark"}
infisical secrets-manager run --env=dev -- go run main.go
```

```bash Ruby theme={"dark"}
infisical secrets-manager run --env=dev -- bundle exec rails server
```

```bash Java theme={"dark"}
infisical secrets-manager run --env=dev -- ./mvnw spring-boot:run
```

```bash .NET theme={"dark"}
infisical secrets-manager run --env=dev -- dotnet run
```

The CLI fetches the secrets you have access to and passes them to your application as environment variables. Your application reads them the same way it always has, through `process.env` in Node.js or `os.environ` in Python, so you don't need to change any application code.

> [!NOTE]
>
> By default, `infisical secrets-manager run` only injects the secrets sitting at the root of the environment, so anything inside a folder is skipped. If your secrets live in [folders](https://infisical.com/docs/documentation/platform/folder.md), you can specify a folder to include using `--path`:
>
> ```bash theme={"dark"}
> infisical secrets-manager run --env=dev --path="/backend" -- npm run dev
> ```
>
> If you also need the secrets in that folder's subfolders, add `--recursive`:
>
> ```bash theme={"dark"}
> infisical secrets-manager run --env=dev --path="/backend" --recursive -- npm run dev
> ```

> [!TIP]
>
> Add `--watch` while you work to restart your application automatically whenever one of its secrets changes in Infisical.

> [accordion] Injecting secrets into a shell function or alias
>
> A start command that is a shell function or an alias can't be called directly after `--`, because it only exists inside your shell. Use the `--command` flag to run it in a shell instead.
>
> For example, if `custom.sh` defines a `yd` function that runs `yarn dev`:
>
> ```bash theme={"dark"}
> #!/bin/sh
>
> yd() {
>   yarn dev
> }
> ```
>
> Source the file and call the function in a single command:
>
> ```bash theme={"dark"}
> infisical secrets-manager run --env=dev --command="source custom.sh && yd"
> ```
>
> The `--command` flag is also how you chain commands together, as in `--command="npm run migrate && npm run dev"`.

For every available option, see the [`infisical secrets-manager run`](https://infisical.com/docs/cli/reference#secrets-manager-run) reference.

## Confirm secrets are injected

If your application starts but behaves as though a value is missing, check what the CLI is injecting before you look at your application code. This prints one secret exactly as your application would receive it:

```bash macOS/Linux theme={"dark"}
infisical secrets-manager run --env=dev -- printenv <YOUR_SECRET_KEY>
```

```powershell Windows (PowerShell) theme={"dark"}
infisical secrets-manager run --env=dev -- powershell -Command 'echo $env:<YOUR_SECRET_KEY>'
```

```batch Windows (Command Prompt) theme={"dark"}
infisical secrets-manager run --env=dev -- cmd /c echo %<YOUR_SECRET_KEY>%
```

To see every key available in an environment, list the secrets directly:

```bash theme={"dark"}
infisical secrets-manager secrets --env=dev --path=/
```

## Override secrets locally

Everyone working in a project shares the same values for a given environment, which is what keeps a team in sync. When you need a different value on your machine alone, such as pointing a database URL at a database running on your laptop, create a [personal override](https://infisical.com/docs/documentation/platform/secrets-mgmt/project.md#personal-overrides) instead of editing the shared secret:

```bash theme={"dark"}
infisical secrets-manager secrets create <YOUR_SECRET_KEY>=<your-local-value> --type=personal
```

Your next `infisical secrets-manager run` uses the override, and your teammates keep receiving the shared value. You can also create an override from the secret's row in the dashboard.

## Export secrets to a file

Some tools read secrets from a file and offer no way to accept them from the environment. For those cases, write the secrets to a file with [`infisical secrets-manager secrets export`](https://infisical.com/docs/cli/reference#secrets-manager-secrets-export):

```bash theme={"dark"}
infisical secrets-manager secrets export --env=dev --format=dotenv --output-file=./.env
```

> [!WARNING]
>
> An exported file is plain text, and it goes out of date as soon as someone changes a value in Infisical. Add it to your `.gitignore`, and regenerate it rather than treating it as the source of truth. We recommend using `infisical secrets-manager run` wherever possible.

## Scan commits for secrets

Fetching secrets from Infisical keeps them out of your repository, but a credential can still reach a commit by being pasted into a source file. Install the pre-commit hook to scan your staged changes each time you commit:

```bash theme={"dark"}
infisical scan install --pre-commit-hook
```

The hook stops the commit when it finds something that looks like a secret. Check out [Secret Scanning](https://infisical.com/docs/documentation/platform/secret-scanning/overview.md) to learn more.

## Troubleshooting

> [accordion] The infisical command isn't found
>
> Your shell reports `infisical: command not found`, or `infisical is not recognized` on Windows. The CLI isn't on your `PATH`. Run the install command for your platform again, then open a new terminal window so that it picks up the updated `PATH`.

> [accordion] Your application starts, but a secret is missing
>
> The CLI is probably reading from a different environment or folder than the one holding your secret. Run `infisical secrets-manager secrets --env=dev --path=/` to see what it resolves to, confirm the environment slug in your project settings, and add `--path` if the secret lives in a folder rather than at the root.

> [accordion] The CLI can't find your project, or asks you to log in again
>
> The CLI is pointed at the wrong instance. It uses Infisical Cloud US by default, so an EU or self-hosted account needs the address set through the `INFISICAL_DOMAIN` environment variable, the `--domain` flag, or the `general.domain` field in [`.infisical.yaml`](https://infisical.com/docs/cli/project-config).

> [accordion] It works in your terminal but not in your editor
>
> Your editor's run configuration starts your application on its own, outside the `infisical secrets-manager run` process, and the injected variables exist only inside that process and the commands it starts. Change the run configuration to call `infisical secrets-manager run --env=dev -- <your-start-command>`. Avoid launching the editor itself through `infisical secrets-manager run`, because its extensions, language servers, and other child processes would also inherit the secrets.

## Next steps

> [card] [CLI reference](https://infisical.com/docs/cli/reference.md#secrets-manager-run)
>
> All available flags for `run`, `export`, `secrets`, and the rest of the CLI.

> [card] [Docker](https://infisical.com/docs/integrations/platforms/docker.md)
>
> Inject the same secrets into containers and Docker Compose services.

> [card] [Secrets delivery](https://infisical.com/docs/documentation/platform/secrets-mgmt/concepts/secrets-delivery.md)
>
> Choose how to deliver secrets to CI/CD, Kubernetes, and production workloads.

> [card] [Language SDKs](https://infisical.com/docs/sdks/overview.md)
>
> Fetch secrets from inside your application code instead of the environment.


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