mirror of
https://github.com/Infisical/infisical.git
synced 2026-01-11 08:28:11 -05:00
324 lines
12 KiB
Plaintext
324 lines
12 KiB
Plaintext
---
|
||
title: "Quickstart"
|
||
description: "Manage secrets with Infisical CLI"
|
||
---
|
||
|
||
The CLI is designed for a variety of secret management applications ranging from local development to CI/CD and production scenarios.
|
||
|
||
<Tabs>
|
||
<Tab title="Local development">
|
||
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.
|
||
|
||
<Note>
|
||
If you prefer learning by watching, you can follow along our step-by-step video tutorial [here](https://www.youtube.com/watch?v=EzDQC7nY3YY).
|
||
</Note>
|
||
|
||
<Steps>
|
||
<Step title="Log in with the CLI">
|
||
Start by running the `infisical login` command to authenticate with Infisical.
|
||
|
||
```bash
|
||
infisical login
|
||
```
|
||
<Note>
|
||
If you are in a containerized environment such as WSL 2 or Codespaces, run `infisical login -i` to avoid browser based login
|
||
</Note>
|
||
</Step>
|
||
<Step title="Initialize Infisical for your project">
|
||
Next, navigate to your project and initialize Infisical.
|
||
|
||
```bash
|
||
# 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](./project-config), at the location where the command is executed.
|
||
|
||
<Note>
|
||
The `.infisical.json` file does not contain any sensitive data, so you may commit it to your git repository.
|
||
</Note>
|
||
</Step>
|
||
<Step title="Inject environment variables">
|
||
Finally, pass environment variables from Infisical into your application.
|
||
|
||
<Tabs>
|
||
<Tab title="Feed secrets to your application">
|
||
```bash
|
||
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
|
||
```
|
||
|
||
</Tab>
|
||
<Tab title="Feed secrets via custom aliases (advanced)">
|
||
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.
|
||
```bash
|
||
#!/bin/sh
|
||
|
||
yd() {
|
||
yarn dev
|
||
}
|
||
```
|
||
|
||
To make the secrets available from Infisical to `yd`, you can run the following command:
|
||
|
||
```bash
|
||
infisical run --env=prod --path=/apps/reddit --command="source custom.sh && yd"
|
||
```
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
View all available options for `run` command [here](./commands/run)
|
||
</Step>
|
||
</Steps>
|
||
|
||
</Tab>
|
||
|
||
<Tab title="Staging, production & all other use cases">
|
||
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.
|
||
<Steps>
|
||
<Step title="Create a machine identity and obtain credentials for it">
|
||
Follow the steps listed [here](/documentation/platform/identities/universal-auth) to create a machine identity and obtain a **client ID** and **client secret** for it.
|
||
</Step>
|
||
<Step title="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.
|
||
|
||
```bash
|
||
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.
|
||
|
||
<Info>
|
||
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](./commands/token) if needed.
|
||
</Info>
|
||
</Step>
|
||
<Step title="Export environment variables back into a file">
|
||
Finally, export the environment variables from Infisical to a file of choice.
|
||
|
||
```bash
|
||
# 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
|
||
```
|
||
</Step>
|
||
</Steps>
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<Note>
|
||
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 US Cloud. To connect to EU Cloud or a self-hosted instance, set the `INFISICAL_API_URL` environment variable to `https://eu.infisical.com` or your custom URL.
|
||
|
||
</Note>
|
||
|
||
<Warning>
|
||
## Domain Configuration
|
||
|
||
**Important:** If you're not using interactive login, you must configure the domain for **all CLI commands**.
|
||
|
||
The CLI defaults to US Cloud (https://app.infisical.com). To connect to **EU Cloud (https://eu.infisical.com)** or a **self-hosted instance**, you must configure the domain in one of the following ways:
|
||
|
||
- Use the `INFISICAL_API_URL` environment variable
|
||
- Use the `--domain` flag on every command
|
||
|
||
<Tabs>
|
||
<Tab title='Use Environment Variable (Recommended)'>
|
||
The easiest way to ensure all CLI commands use the correct domain is to set
|
||
the `INFISICAL_API_URL` environment variable. This applies the domain
|
||
setting globally to all commands:
|
||
|
||
```bash
|
||
# Linux/MacOS
|
||
export INFISICAL_API_URL="https://your-domain.infisical.com"
|
||
|
||
# Windows PowerShell
|
||
setx INFISICAL_API_URL "https://your-domain.infisical.com"
|
||
```
|
||
|
||
Once set, all subsequent CLI commands will automatically use this domain:
|
||
|
||
```bash
|
||
# Login with the domain
|
||
infisical login --method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --silent --plain
|
||
|
||
# All other commands will also use the same domain automatically
|
||
infisical secrets --projectId <id> --env dev
|
||
```
|
||
|
||
</Tab>
|
||
<Tab title='Use --domain Flag'>
|
||
The `--domain` flag can be used to set the domain for a single command. This
|
||
applies the domain setting to the command only:
|
||
|
||
```bash
|
||
# Login with domain
|
||
infisical login --domain="https://your-domain.infisical.com" --method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --silent --plain
|
||
|
||
# All subsequent commands must also include --domain
|
||
infisical secrets --domain="https://your-domain.infisical.com" --projectId=<id> --env=dev
|
||
```
|
||
|
||
<Note>
|
||
If you use `--domain` during login but forget to include it on subsequent commands, you may encounter authentication errors.
|
||
</Note>
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
</Warning>
|
||
|
||
<Tip>
|
||
## 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:
|
||
|
||
```bash
|
||
# 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.
|
||
|
||
</Tip>
|
||
|
||
## 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.
|
||
|
||
<Accordion title="Ignore commands">
|
||
<Tabs>
|
||
<Tab title="Unix/Linux">
|
||
<Tip>
|
||
`$HOME/.profile` is pretty common but, you could place it under `$HOME/.profile.d/infisical.sh` or any profile file run at login
|
||
</Tip>
|
||
|
||
```bash
|
||
cat <<EOF >> $HOME/.profile && source $HOME/.profile
|
||
|
||
# Ignoring specific Infisical CLI commands
|
||
DEFAULT_HISTIGNORE=$HISTIGNORE
|
||
export HISTIGNORE="*infisical secrets set*:$DEFAULT_HISTIGNORE"
|
||
EOF
|
||
```
|
||
|
||
</Tab>
|
||
<Tab title="Windows">
|
||
If you're on WSL, then you can use the Unix/Linux method.
|
||
|
||
<Tip>
|
||
Here's some [documentation](https://superuser.com/a/1658331) about how to clear the terminal history, in PowerShell and CMD
|
||
</Tip>
|
||
|
||
</Tab>
|
||
|
||
</Tabs>
|
||
</Accordion>
|
||
|
||
## FAQ
|
||
|
||
<AccordionGroup>
|
||
<Accordion title="Can I connect the CLI to my self-hosted or non-US Cloud Infisical instance?">
|
||
Yes. The CLI is set to connect to Infisical US Cloud by default, but if you're using EU Cloud or a self-hosted instance you can configure the domain for **all CLI commands**.
|
||
|
||
#### Method 1: Use the updated CLI (v0.4.0+)
|
||
|
||
Beginning with CLI version V0.4.0, you can choose between logging in through Infisical US Cloud, EU 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.
|
||
|
||
<Tabs>
|
||
<Tab title="Linux/MacOs">
|
||
```bash
|
||
# Set the API URL
|
||
export INFISICAL_API_URL="https://your-self-hosted-infisical.com"
|
||
|
||
# For EU Cloud
|
||
export INFISICAL_API_URL="https://eu.infisical.com"
|
||
|
||
# Remove the setting
|
||
unset INFISICAL_API_URL
|
||
```
|
||
|
||
</Tab>
|
||
<Tab title="Windows Powershell">
|
||
```bash
|
||
# Set the API URL
|
||
setx INFISICAL_API_URL "https://your-self-hosted-infisical.com"
|
||
|
||
# For EU Cloud
|
||
setx INFISICAL_API_URL "https://eu.infisical.com"
|
||
|
||
# Remove the setting
|
||
setx INFISICAL_API_URL ""
|
||
|
||
# NOTE: Once set, please restart powershell for the change to take effect
|
||
```
|
||
|
||
</Tab>
|
||
|
||
</Tabs>
|
||
|
||
#### Method 3: Set manually on every command
|
||
|
||
If you prefer not to use an environment variable, you must include the `--domain` flag on **every CLI command** you run:
|
||
|
||
```bash
|
||
# Login with domain
|
||
infisical login --domain="https://your-domain.infisical.com" --method=oidc-auth --jwt $JWT
|
||
|
||
# All subsequent commands must also include --domain
|
||
infisical secrets --domain="https://your-self-hosted-infisical.com" --projectId <id> --env dev
|
||
infisical export --domain="https://your-self-hosted-infisical.com" --format=dotenv-export
|
||
```
|
||
|
||
<Tip>
|
||
**Best Practice:** Use `INFISICAL_API_URL` environment variable (Method 2) to avoid having to remember the `--domain` flag on every command. This is especially important in CI/CD pipelines and automation scripts.
|
||
</Tip>
|
||
|
||
</Accordion>
|
||
<Accordion title="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.
|
||
|
||
```bash
|
||
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.
|
||
|
||
```bash
|
||
export INFISICAL_TOKEN=<service-token>
|
||
```
|
||
|
||
</Accordion>
|
||
</AccordionGroup>
|