awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4945 from Infisical/ENG-4117

Browse Source 
[ENG-4117] docs: improves cli `--domain` flag docs
This commit is contained in:
Andre
2025-11-26 19:28:43 -05:00
committed by GitHub
parent f0df6eb745 af2c1b31bc
commit c39673e25a
2 changed files with 131 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
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>
@@ -500,6 +501,30 @@ 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>
```
#### Description
Specifies the Infisical API URL for non-US Cloud instances. This flag is required when connecting to any instance other than US Cloud (e.g. EU Cloud or self-hosted).
```bash
# Example for EU Cloud
infisical login --domain="https://eu.infisical.com"
# Example for localhost
infisical login --domain="http://localhost:8080"
# Example for self-hosted
infisical login --domain="https://your-self-hosted-infisical.com"
```
<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 +554,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
# Basic direct login (EU Cloud)
infisical login --domain https://eu.infisical.com --email user@example.com --password "your-password" --organization-id "your-organization-id"
# Basic direct login (Self-hosted Instance)
infisical login --domain https://your-self-hosted-infisical.com --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 +578,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 Cloud 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 +604,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 +617,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 Cloud 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.

108
docs/cli/usage.mdx
View File

@@ -127,10 +127,66 @@ The CLI is designed for a variety of secret management applications ranging from
<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 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.
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
@@ -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 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
#### 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 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 use an 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" --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?">