Skip to content

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

6.5 KB
Raw Blame
---
title: "Inject secrets into local development"
sidebarTitle: "Local development"
description: "Run your application on your own machine with secrets pulled from Infisical instead of a .env file."
---

import InstallCli from "/snippets/cli/install-cli.mdx";
import LogIn from "/snippets/cli/local-development/log-in.mdx";
import LinkProject from "/snippets/cli/local-development/link-project.mdx";
import StartApplication from "/snippets/cli/local-development/start-application.mdx";

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](/cli/install), link your codebase to your Infisical project, and start your application through `infisical sm run`.

<Note>
  `infisical sm 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](/integrations/overview?type=Framework).
</Note>

## Prerequisites

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

## Step 1: Install the CLI

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

<InstallCli />

Check that the installation worked:

```bash
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).
</Tip>

### Log in to Infisical

<LogIn />

### Link your codebase to your project

<LinkProject />

### Start your application with secrets injected

<StartApplication />

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

<CodeGroup>

```bash macOS/Linux
infisical sm run --env=dev -- printenv <YOUR_SECRET_KEY>
```

```powershell Windows (PowerShell)
infisical sm run --env=dev -- powershell -Command 'echo $env:<YOUR_SECRET_KEY>'
```

```batch Windows (Command Prompt)
infisical sm run --env=dev -- cmd /c echo %<YOUR_SECRET_KEY>%
```

</CodeGroup>

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

```bash
infisical sm 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](/documentation/platform/secrets-mgmt/project#personal-overrides) instead of editing the shared secret:

```bash
infisical sm secrets set <YOUR_SECRET_KEY>=<your-local-value> --type=personal
```

Your next `infisical sm 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 sm export`](/cli/reference#sm-export):

```bash
infisical sm 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 sm run` wherever possible.
</Warning>

## 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
infisical scan install --pre-commit-hook
```

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="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>
  <Accordion title="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 sm 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>
  <Accordion title="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`](/cli/project-config).
  </Accordion>
  <Accordion title="It works in your terminal but not in your editor">
    Your editor's run configuration starts your application on its own, outside the `infisical sm run` process, and the injected variables exist only inside that process and the commands it starts. Change the run configuration to call `infisical sm run --env=dev -- <your-start-command>`. Avoid launching the editor itself through `infisical sm run`, because its extensions, language servers, and other child processes would also inherit the secrets.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="CLI reference" icon="terminal" href="/cli/reference#sm-run">
    All available flags for `run`, `export`, `secrets`, and the rest of the CLI.
  </Card>
  <Card title="Docker" icon="docker" iconType="brands" href="/integrations/platforms/docker">
    Inject the same secrets into containers and Docker Compose services.
  </Card>
  <Card title="Secrets delivery" icon="truck" href="/documentation/platform/secrets-mgmt/concepts/secrets-delivery">
    Choose how to deliver secrets to CI/CD, Kubernetes, and production workloads.
  </Card>
  <Card title="Language SDKs" icon="code" href="/sdks/overview">
    Fetch secrets from inside your application code instead of the environment.
  </Card>
</CardGroup>