Quickstart - Infisical

The CLI is designed for a variety of secret management applications ranging from local development to CI/CD and production scenarios.

In the following steps, we explore how to use the Infisical CLI to fetch back environment variables from Infisical and inject them into your local development process.

Start by running the infisical login command to authenticate with Infisical.

infisical login

If you are in a containerized environment such as WSL 2 or Codespaces, run infisical login -i to avoid browser based login

Initialize Infisical for your project

Next, navigate to your project and initialize Infisical.

# navigate to your project
cd /path/to/project

# initialize infisical
infisical init

The infisical init command creates a .infisical.json file, containing local project settings, at the location where the command is executed.

The .infisical.json file does not contain any sensitive data, so you may commit it to your git repository.

Inject environment variables

Finally, pass environment variables from Infisical into your application.

infisical run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev

# example with node (nodemon)
infisical run --env=staging --path=/apps/spotify -- nodemon index.js

# example with flask
infisical run --env=prod --path=/apps/backend -- flask run

# example with spring boot - maven
infisical run --env=dev --path=/apps/ -- ./mvnw spring-boot:run --quiet

infisical run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev

# example with node (nodemon)
infisical run --env=staging --path=/apps/spotify -- nodemon index.js

# example with flask
infisical run --env=prod --path=/apps/backend -- flask run

# example with spring boot - maven
infisical run --env=dev --path=/apps/ -- ./mvnw spring-boot:run --quiet

Custom aliases can utilize secrets from Infisical. Suppose there is a custom alias yd in custom.sh that runs yarn dev and needs the secrets provided by Infisical.

#!/bin/sh

yd() {
  yarn dev
}

To make the secrets available from Infisical to yd, you can run the following command:

infisical run --env=prod --path=/apps/reddit --command="source custom.sh && yd"

View all available options for run command here

In the following steps, we explore how to use the Infisical CLI to fetch back environment variables from Infisical and inject them into your local development process.

Start by running the infisical login command to authenticate with Infisical.

infisical login

If you are in a containerized environment such as WSL 2 or Codespaces, run infisical login -i to avoid browser based login

Initialize Infisical for your project

Next, navigate to your project and initialize Infisical.

# navigate to your project
cd /path/to/project

# initialize infisical
infisical init

The infisical init command creates a .infisical.json file, containing local project settings, at the location where the command is executed.

The .infisical.json file does not contain any sensitive data, so you may commit it to your git repository.

Inject environment variables

Finally, pass environment variables from Infisical into your application.

infisical run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev

# example with node (nodemon)
infisical run --env=staging --path=/apps/spotify -- nodemon index.js

# example with flask
infisical run --env=prod --path=/apps/backend -- flask run

# example with spring boot - maven
infisical run --env=dev --path=/apps/ -- ./mvnw spring-boot:run --quiet

infisical run --env=dev --path=/apps/firefly -- [your application start command] # e.g. npm run dev

# example with node (nodemon)
infisical run --env=staging --path=/apps/spotify -- nodemon index.js

# example with flask
infisical run --env=prod --path=/apps/backend -- flask run

# example with spring boot - maven
infisical run --env=dev --path=/apps/ -- ./mvnw spring-boot:run --quiet

Custom aliases can utilize secrets from Infisical. Suppose there is a custom alias yd in custom.sh that runs yarn dev and needs the secrets provided by Infisical.

#!/bin/sh

yd() {
  yarn dev
}

To make the secrets available from Infisical to yd, you can run the following command:

infisical run --env=prod --path=/apps/reddit --command="source custom.sh && yd"

View all available options for run command here

In the following steps, we explore how to use the Infisical CLI in a non-local development scenario to fetch back environment variables and export them to a file.

Create a machine identity and obtain credentials for it

Follow the steps listed here to create a machine identity and obtain a client ID and client secret for it.

Obtain a machine identity access token

Run the following command to authenticate with Infisical using the client ID and client secret credentials from step 1 and set the INFISICAL_TOKEN environment variable to the retrieved access token.

export INFISICAL_TOKEN=$(infisical login --method=universal-auth --client-id=<identity-client-id> --client-secret=<identity-client-secret> --silent --plain) # --plain flag will output only the token, so it can be fed to an environment variable. --silent will disable any update messages.

The CLI is configured to look out for the INFISICAL_TOKEN environment variable, so going forward any command used will be authenticated.

Alternatively, assuming you have an access token on hand, you can also pass it directly to the CLI using the --token flag in conjunction with other CLI commands.

Keep in mind that the machine identity access token has a limited lifetime. It is recommended to use it only for the duration of the task at hand. You can refresh the token if needed.

Export environment variables back into a file

Finally, export the environment variables from Infisical to a file of choice.

# export variables to a .env file (with export keyword)
infisical export --format=dotenv-export > .env

# export variables to a YAML file
infisical export --format=yaml > secrets.yaml

Starting with CLI version v0.4.0, you can now choose to log in via Infisical Cloud (US/EU) or your own self-hosted instance by simply running infisical login and following the on-screen instructions — no need to manually set the INFISICAL_API_URL environment variable.

For versions prior to v0.4.0, the CLI defaults to the US Cloud. To connect to the EU Cloud or a self-hosted instance, set the INFISICAL_API_URL environment variable to https://eu.infisical.com or your custom URL.

Custom Request Headers

The Infisical CLI supports custom HTTP headers for requests to servers protected by authentication services such as Cloudflare Access. Configure these headers using the INFISICAL_CUSTOM_HEADERS environment variable:

# Syntax: headername1=headervalue1 headername2=headervalue2
export INFISICAL_CUSTOM_HEADERS="Access-Client-Id=your-client-id Access-Client-Secret=your-client-secret"

# Execute Infisical commands after setting the environment variable
infisical secrets

This functionality enables secure interaction with Infisical instances that require specific authentication headers.

History

Your terminal keeps a history with the commands you run. When you create Infisical secrets directly from your terminal, they’ll stay there for a while.

For security and privacy concerns, we recommend you to configure your terminal to ignore those specific Infisical commands.

Ignore commands

$HOME/.profile is pretty common but, you could place it under $HOME/.profile.d/infisical.sh or any profile file run at login

cat <<EOF >> $HOME/.profile && source $HOME/.profile

# Ignoring specific Infisical CLI commands
DEFAULT_HISTIGNORE=$HISTIGNORE
export HISTIGNORE="*infisical secrets set*:$DEFAULT_HISTIGNORE"
EOF

$HOME/.profile is pretty common but, you could place it under $HOME/.profile.d/infisical.sh or any profile file run at login

cat <<EOF >> $HOME/.profile && source $HOME/.profile

# Ignoring specific Infisical CLI commands
DEFAULT_HISTIGNORE=$HISTIGNORE
export HISTIGNORE="*infisical secrets set*:$DEFAULT_HISTIGNORE"
EOF

If you’re on WSL, then you can use the Unix/Linux method.

Here’s some documentation about how to clear the terminal history, in PowerShell and CMD

FAQ

Can I connect the CLI to my self-hosted Infisical instance?

Yes. The CLI is set to connect to Infisical Cloud by default, but if you’re running your own instance of Infisical, you can direct the CLI to it using one of the methods provided below.

Method 1: Use the updated CLI

Beginning with CLI version V0.4.0, it is now possible to choose between logging in through the Infisical cloud or your own self-hosted instance. Simply execute the infisical login command and follow the on-screen instructions.

Method 2: Export environment variable

You can point the CLI to the self-hosted Infisical instance by exporting the environment variable INFISICAL_API_URL in your terminal.

# set backend host
export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api"

# remove backend host
unset INFISICAL_API_URL

# set backend host
export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api"

# remove backend host
unset INFISICAL_API_URL

# set backend host
setx INFISICAL_API_URL "https://your-self-hosted-infisical.com/api"

# remove backend host
setx INFISICAL_API_URL ""

# NOTE: Once set or removed, please restart powershell for the change to take effect

Method 3: Set manually on every command

Another option to point the CLI to your self-hosted Infisical instance is to set it via a flag on every command you run.

# Example
infisical <any-command> --domain="https://your-self-hosted-infisical.com/api"

Can I use the CLI with service tokens?

To use Infisical for non local development scenarios, please create a service token. The service token will allow you to authenticate and interact with Infisical. Once you have created a service token with the required permissions, you’ll need to feed the token to the CLI.

  infisical export --token=<service-token>
  infisical secrets --token=<service-token>
  infisical run --token=<service-token> -- npm run dev

Pass via shell environment variable

The CLI is configured to look for an environment variable named INFISICAL_TOKEN. If set, it’ll attempt to use it for authentication.

  export INFISICAL_TOKEN=<service-token>

Command line

​Custom Request Headers

​History

​FAQ

Custom Request Headers

History

FAQ