awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-10-07 12:27:28 +00: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
docs/cli/commands/login.mdx
+53 -12
View File
@@ -10,6 +10,7 @@ infisical login
### Description ### Description
The CLI uses authentication to verify your identity. You can authenticate using: The CLI uses authentication to verify your identity. You can authenticate using:
- **Browser Login** (default): Opens a browser for authentication - **Browser Login** (default): Opens a browser for authentication
- **Direct Login**: Provide email and password via flags or environment variables for non-interactive workflows - **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 - **Interactive CLI Login**: Use the `--interactive` flag to enter credentials via CLI prompts
@@ -46,21 +47,26 @@ User authentication is designed for individual developers and supports multiple
- **Direct Login**: Provide credentials via flags or environment variables for CI/CD - **Direct Login**: Provide credentials via flags or environment variables for CI/CD
- **Interactive CLI Login**: Enter credentials via CLI prompts using `--interactive` - **Interactive CLI Login**: Enter credentials via CLI prompts using `--interactive`
<ParamField query="Flags"> {" "}
<Expandable title="properties">
<ParamField query="email" type="string" optional> <ParamField query='Flags'>
Your email address. Required for direct login along with `--password` and `--organization-id`. <Expandable title='properties'>
<ParamField query='email' type='string' optional>
Your email address. Required for direct login along with `--password` and
`--organization-id`.
</ParamField> </ParamField>
<ParamField query="password" type="string" optional> <ParamField query='password' type='string' optional>
Your password. Required for direct login along with `--email` and `--organization-id`. Your password. Required for direct login along with `--email` and
`--organization-id`.
</ParamField> </ParamField>
<ParamField query="organization-id" type="string" optional> <ParamField query='organization-id' type='string' optional>
Your organization id. Required for direct login along with `--password` and `--email`. Your organization id. Required for direct login along with `--password`
and `--email`.
</ParamField> </ParamField>
<ParamField query="interactive" type="boolean" optional> <ParamField query='interactive' type='boolean' optional>
Force interactive CLI login instead of browser-based authentication. Force interactive CLI login instead of browser-based authentication.
</ParamField> </ParamField>
<ParamField query="plain" type="boolean" optional> <ParamField query='plain' type='boolean' optional>
Output only the JWT token (useful for scripting and CI/CD). Output only the JWT token (useful for scripting and CI/CD).
</ParamField> </ParamField>
</Expandable> </Expandable>
@@ -291,6 +297,7 @@ Machine identity authentication methods are designed for automated systems, serv
``` ```
</Step> </Step>
</Steps> </Steps>
</Accordion> </Accordion>
<Accordion title="JWT Auth"> <Accordion title="JWT Auth">
@@ -316,6 +323,7 @@ Machine identity authentication methods are designed for automated systems, serv
``` ```
</Step> </Step>
</Steps> </Steps>
</Accordion> </Accordion>
</AccordionGroup> </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. The `jwt` flag can be substituted with the `INFISICAL_JWT` environment variable.
</Tip> </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 [email protected] --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> </Accordion>
</AccordionGroup> </AccordionGroup>
@@ -529,8 +558,11 @@ The following examples demonstrate different ways to authenticate as a user with
# Basic direct login (defaults to US Cloud) # Basic direct login (defaults to US Cloud)
infisical login --email [email protected] --password "your-password" --organization-id "your-organization-id" infisical login --email [email protected] --password "your-password" --organization-id "your-organization-id"
# EU Cloud (Custom domain) # EU Cloud
infisical login --email [email protected] --password "your-password" --organization-id "your-organization-id" --domain https://eu.infisical.com infisical login --domain https://eu.infisical.com --email [email protected] --password "your-password" --organization-id "your-organization-id"
# Self-hosted instance
infisical login --domain https://your-self-hosted-infisical.com/api --email [email protected] --password "your-password" --organization-id "your-organization-id"
# Output only JWT token for scripting # Output only JWT token for scripting
export INFISICAL_TOKEN=$(infisical login --email [email protected] --password "your-password" --organization-id "your-organization-id" --plain --silent) export INFISICAL_TOKEN=$(infisical login --email [email protected] --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 # Or with plain output for token capture
export INFISICAL_TOKEN=$(infisical login --plain --silent) 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>
<Accordion title="Interactive CLI Login"> <Accordion title="Interactive CLI Login">
@@ -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. 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. 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.
docs/cli/usage.mdx
+84 -14
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> </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> <Tip>
## Custom Request Headers ## Custom Request Headers
@@ -186,12 +242,12 @@ For security and privacy concerns, we recommend you to configure your terminal t
## FAQ ## FAQ
<AccordionGroup> <AccordionGroup>
<Accordion title="Can I connect the CLI to my self-hosted Infisical instance?"> <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 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. 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
@@ -200,23 +256,29 @@ For security and privacy concerns, we recommend you to configure your terminal t
<Tabs> <Tabs>
<Tab title="Linux/MacOs"> <Tab title="Linux/MacOs">
```bash ```bash
# set backend host # Set the API URL
export INFISICAL_API_URL="https://your-self-hosted-infisical.com/api" 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 unset INFISICAL_API_URL
``` ```
</Tab> </Tab>
<Tab title="Windows Powershell"> <Tab title="Windows Powershell">
```bash ```bash
# set backend host # Set the API URL
setx INFISICAL_API_URL "https://your-self-hosted-infisical.com/api" 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 "" 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> </Tab>
@@ -225,13 +287,21 @@ For security and privacy concerns, we recommend you to configure your terminal t
#### 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 ```bash
# Example # Login with domain
infisical <any-command> --domain="https://your-self-hosted-infisical.com/api" 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>
<Accordion title="Can I use the CLI with service tokens?"> <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. 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.