github/infisical
1
0
Fork 0
mirror of https://github.com/Infisical/infisical.git synced 2026-01-09 15:38:03 -05:00
Code Issues Packages Projects Releases Wiki Activity

docs: improves cli docs

Browse Source
This commit is contained in:
Piyush Gupta
2025-11-26 02:56:40 +05:30
parent 973813aae6
commit 64ba002af6
2 changed files with 156 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/cli/commands/login.mdx
View File

@@ -10,6 +10,7 @@ infisical login
### Description
The CLI uses authentication to verify your identity. You can authenticate using:
- **Browser Login** (default): Opens a browser for authentication
- **Direct Login**: Provide email and password via flags or environment variables for non-interactive workflows
- **Interactive CLI Login**: Use the `--interactive` flag to enter credentials via CLI prompts
@@ -24,9 +25,9 @@ If you have added multiple users, you can switch between the users by using the
**JWT Token Output:**
- For **user authentication** with the `--plain --silent` flags: outputs only the JWT access token (useful for scripting)
- For **machine identity authentication**: an access token is always printed to the console
Use the `--plain` flag to print only the token in plain text and the `--silent` flag to disable update alerts.
Both flags are ideal for capturing the token in environment variables or CI/CD pipelines.
</Info>
@@ -42,29 +43,34 @@ User authentication is designed for individual developers and supports multiple
<Accordion title="User">
The User authentication method allows you to log in with your email and password. This method supports three different login flows:
- **Browser Login** (default): Opens a browser for authentication
- **Direct Login**: Provide credentials via flags or environment variables for CI/CD
- **Interactive CLI Login**: Enter credentials via CLI prompts using `--interactive`
- **Browser Login** (default): Opens a browser for authentication
- **Direct Login**: Provide credentials via flags or environment variables for CI/CD
- **Interactive CLI Login**: Enter credentials via CLI prompts using `--interactive`
<ParamField query="Flags">
<Expandable title="properties">
<ParamField query="email" type="string" optional>
Your email address. Required for direct login along with `--password` and `--organization-id`.
</ParamField>
<ParamField query="password" type="string" optional>
Your password. Required for direct login along with `--email` and `--organization-id`.
</ParamField>
<ParamField query="organization-id" type="string" optional>
Your organization id. Required for direct login along with `--password` and `--email`.
</ParamField>
<ParamField query="interactive" type="boolean" optional>
Force interactive CLI login instead of browser-based authentication.
</ParamField>
<ParamField query="plain" type="boolean" optional>
Output only the JWT token (useful for scripting and CI/CD).
</ParamField>
</Expandable>
</ParamField>
{" "}
<ParamField query='Flags'>
<Expandable title='properties'>
<ParamField query='email' type='string' optional>
Your email address. Required for direct login along with `--password` and
`--organization-id`.
</ParamField>
<ParamField query='password' type='string' optional>
Your password. Required for direct login along with `--email` and
`--organization-id`.
</ParamField>
<ParamField query='organization-id' type='string' optional>
Your organization id. Required for direct login along with `--password`
and `--email`.
</ParamField>
<ParamField query='interactive' type='boolean' optional>
Force interactive CLI login instead of browser-based authentication.
</ParamField>
<ParamField query='plain' type='boolean' optional>
Output only the JWT token (useful for scripting and CI/CD).
</ParamField>
</Expandable>
</ParamField>
<AccordionGroup>
<Accordion title="Browser Login (Default)">
@@ -291,6 +297,7 @@ Machine identity authentication methods are designed for automated systems, serv
```
</Step>
</Steps>
</Accordion>
<Accordion title="JWT Auth">
@@ -316,6 +323,7 @@ Machine identity authentication methods are designed for automated systems, serv
```
</Step>
</Steps>
</Accordion>
</AccordionGroup>
@@ -500,6 +508,27 @@ The login command supports a number of flags that you can use for different auth
The `jwt` flag can be substituted with the `INFISICAL_JWT` environment variable.
</Tip>
</Accordion>
<Accordion title="--domain">
```bash
infisical login --domain=<domain-url> [other-flags]
```
#### Description
Specifies the Infisical API URL for non-US instances (EU Cloud or self-hosted instances). This flag is required when connecting to any instance other than the US Cloud.
```bash
# Example for EU Cloud
infisical login --domain="https://eu.infisical.com" --jwt=<jwt-token> --machine-identity-id=<machine-identity-id>
# Example for self-hosted
infisical login --domain="https://your-self-hosted-infisical.com/api" --email user@example.com --password "password"
```
<Warning>
**Critical:** If you use `--domain` during login, you must also include it on **all subsequent CLI commands** (e.g., `infisical secrets`, `infisical export`, etc.). Alternatively, set the `INFISICAL_API_URL` environment variable to avoid having to use `--domain` on every command. Refer to the [Domain Configuration](/cli/usage#domain-configuration) section for more details.
</Warning>
</Accordion>
</AccordionGroup>
@@ -529,8 +558,11 @@ The following examples demonstrate different ways to authenticate as a user with
# Basic direct login (defaults to US Cloud)
infisical login --email user@example.com --password "your-password" --organization-id "your-organization-id"
# EU Cloud (Custom domain)
infisical login --email user@example.com --password "your-password" --organization-id "your-organization-id" --domain https://eu.infisical.com
# EU Cloud
infisical login --domain https://eu.infisical.com --email user@example.com --password "your-password" --organization-id "your-organization-id"
# Self-hosted instance
infisical login --domain https://your-self-hosted-infisical.com/api --email user@example.com --password "your-password" --organization-id "your-organization-id"
# Output only JWT token for scripting
export INFISICAL_TOKEN=$(infisical login --email user@example.com --password "your-password" --organization-id "your-organization-id" --plain --silent)
@@ -550,6 +582,11 @@ The following examples demonstrate different ways to authenticate as a user with
# Or with plain output for token capture
export INFISICAL_TOKEN=$(infisical login --plain --silent)
```
<Warning>
**For non-US instances:** If you're using EU Cloud, or a self-hosted instance, you must set `INFISICAL_API_URL` before login, or use `--domain` on all commands. Refer to the [Domain Configuration](/cli/usage#domain-configuration) section for more details.
</Warning>
</Accordion>
<Accordion title="Interactive CLI Login">
@@ -571,7 +608,7 @@ The following examples demonstrate different ways to authenticate as a user with
</AccordionGroup>
<Tip>
If you have SSO enabled, we recommend using the default browser login.
If you have SSO enabled, we recommend using the default browser login.
</Tip>
### Machine Identity Authentication Quick Start
@@ -584,6 +621,10 @@ In this example we'll be using the `universal-auth` method to login to obtain an
export INFISICAL_TOKEN=$(infisical login --method=universal-auth --client-id=<client-id> --client-secret=<client-secret> --silent --plain) # silent and plain is important to ensure only the token itself is printed, so we can easily set it as an environment variable.
```
<Warning>
**For non-US instances:** If you're using EU Cloud, or a self-hosted instance, you must set `INFISICAL_API_URL` before login, or use `--domain` on all commands. Refer to the [Domain Configuration](/cli/usage#domain-configuration) section for more details.
</Warning>
Now that we've set the `INFISICAL_TOKEN` environment variable, we can use the CLI to interact with Infisical. The CLI will automatically check for the presence of the `INFISICAL_TOKEN` environment variable and use it for authentication.

106
docs/cli/usage.mdx
View File

@@ -131,6 +131,62 @@ For versions prior to v0.4.0, the CLI defaults to the US Cloud. To connect to th
</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 the US Cloud (https://app.infisical.com). To connect to the **EU Cloud (https://eu.infisical.com)** or a **self-hosted instance**, you can 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
@@ -186,51 +242,65 @@ For security and privacy concerns, we recommend you to configure your terminal t
## FAQ
<AccordionGroup>
<Accordion title="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.
<Accordion title="Can I connect the CLI to my self-hosted Infisical instance or non-US Cloud?">
Yes. The CLI is set to connect to Infisical US Cloud by default, but if you're using the EU Cloud, a self-hosted instance, you need to configure the domain for **all CLI commands**.
#### Method 1: Use the updated CLI
#### Method 1:Use the updated CLI (v0.4.0+)
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.
Beginning with CLI version V0.4.0, you can choose between logging in through the 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
#### 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 backend host
export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api"
# Set the API URL
export INFISICAL_API_URL="https://your-self-hosted-infisical.com"
# remove backend host
# 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 backend host
setx INFISICAL_API_URL "https://your-self-hosted-infisical.com/api"
# Set the API URL
setx INFISICAL_API_URL "https://your-self-hosted-infisical.com"
# remove backend host
# For EU Cloud
setx INFISICAL_API_URL "https://eu.infisical.com"
# Remove the setting
setx INFISICAL_API_URL ""
# NOTE: Once set or removed, please restart powershell for the change to take effect
# NOTE: Once set, please restart powershell for the change to take effect
```
</Tab>
</Tabs>
#### Method 3: Set manually on every command
#### 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.
If you prefer not to set the environment variable, you must include the `--domain` flag on **every CLI command** you run:
```bash
# Example
infisical <any-command> --domain="https://your-self-hosted-infisical.com/api"
```
```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/api" --projectId <id> --env dev
infisical export --domain="https://your-self-hosted-infisical.com/api" --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?">