From 64ba002af6a774878cfc3163d7fd75bcbd6bf8ae Mon Sep 17 00:00:00 2001 From: Piyush Gupta Date: Wed, 26 Nov 2025 02:56:40 +0530 Subject: [PATCH 1/4] docs: improves cli docs --- docs/cli/commands/login.mdx | 95 +++++++++++++++++++++++--------- docs/cli/usage.mdx | 106 ++++++++++++++++++++++++++++++------ 2 files changed, 156 insertions(+), 45 deletions(-) diff --git a/docs/cli/commands/login.mdx b/docs/cli/commands/login.mdx index c58c13713..1a0db9b4e 100644 --- a/docs/cli/commands/login.mdx +++ b/docs/cli/commands/login.mdx @@ -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. @@ -42,29 +43,34 @@ User authentication is designed for individual developers and supports multiple 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` - - - - Your email address. Required for direct login along with `--password` and `--organization-id`. - - - Your password. Required for direct login along with `--email` and `--organization-id`. - - - Your organization id. Required for direct login along with `--password` and `--email`. - - - Force interactive CLI login instead of browser-based authentication. - - - Output only the JWT token (useful for scripting and CI/CD). - - - +{" "} + + + + + Your email address. Required for direct login along with `--password` and + `--organization-id`. + + + Your password. Required for direct login along with `--email` and + `--organization-id`. + + + Your organization id. Required for direct login along with `--password` + and `--email`. + + + Force interactive CLI login instead of browser-based authentication. + + + Output only the JWT token (useful for scripting and CI/CD). + + + @@ -291,6 +297,7 @@ Machine identity authentication methods are designed for automated systems, serv ``` + @@ -316,6 +323,7 @@ Machine identity authentication methods are designed for automated systems, serv ``` + @@ -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. + + + ```bash + infisical login --domain= [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= --machine-identity-id= + + # Example for self-hosted + infisical login --domain="https://your-self-hosted-infisical.com/api" --email user@example.com --password "password" + ``` + + + **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. + + @@ -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) ``` + + + **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. + + @@ -571,7 +608,7 @@ The following examples demonstrate different ways to authenticate as a user with -If you have SSO enabled, we recommend using the default browser login. + If you have SSO enabled, we recommend using the default browser login. ### 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-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. ``` + + **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. + + 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. diff --git a/docs/cli/usage.mdx b/docs/cli/usage.mdx index bedfda22c..c91ac5736 100644 --- a/docs/cli/usage.mdx +++ b/docs/cli/usage.mdx @@ -131,6 +131,62 @@ For versions prior to v0.4.0, the CLI defaults to the US Cloud. To connect to th + + ## 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 + + + + 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-secret= --silent --plain + + # All other commands will also use the same domain automatically + infisical secrets --projectId --env dev + ``` + + + + 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-secret= --silent --plain + + # All subsequent commands must also include --domain + infisical secrets --domain="https://your-domain.infisical.com" --projectId --env dev + ``` + + + If you use `--domain` during login but forget to include it on subsequent commands, you may encounter authentication errors. + + + + + + + ## Custom Request Headers @@ -186,51 +242,65 @@ For security and privacy concerns, we recommend you to configure your terminal t ## FAQ - - 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 You can point the CLI to the self-hosted Infisical instance by exporting the environment variable `INFISICAL_API_URL` in your terminal. ```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 ``` ```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 ``` -#### 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 --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 --env dev + infisical export --domain="https://your-self-hosted-infisical.com/api" --format=dotenv-export + ``` + + + **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. + From e22369ec4d773eac3a6ceab806a8750d976bc431 Mon Sep 17 00:00:00 2001 From: Piyush Gupta Date: Wed, 26 Nov 2025 18:17:35 +0530 Subject: [PATCH 2/4] fix: review comments --- docs/cli/commands/login.mdx | 72 ++++++++++++++++++------------------- docs/cli/usage.mdx | 20 +++++------ 2 files changed, 44 insertions(+), 48 deletions(-) diff --git a/docs/cli/commands/login.mdx b/docs/cli/commands/login.mdx index 1a0db9b4e..a670c03aa 100644 --- a/docs/cli/commands/login.mdx +++ b/docs/cli/commands/login.mdx @@ -43,34 +43,29 @@ User authentication is designed for individual developers and supports multiple 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` -{" "} - - - - - Your email address. Required for direct login along with `--password` and - `--organization-id`. - - - Your password. Required for direct login along with `--email` and - `--organization-id`. - - - Your organization id. Required for direct login along with `--password` - and `--email`. - - - Force interactive CLI login instead of browser-based authentication. - - - Output only the JWT token (useful for scripting and CI/CD). - - - + + + + Your email address. Required for direct login along with `--password` and `--organization-id`. + + + Your password. Required for direct login along with `--email` and `--organization-id`. + + + Your organization id. Required for direct login along with `--password` and `--email`. + + + Force interactive CLI login instead of browser-based authentication. + + + Output only the JWT token (useful for scripting and CI/CD). + + + @@ -297,7 +292,6 @@ Machine identity authentication methods are designed for automated systems, serv ``` - @@ -323,7 +317,6 @@ Machine identity authentication methods are designed for automated systems, serv ``` - @@ -511,18 +504,21 @@ The login command supports a number of flags that you can use for different auth ```bash - infisical login --domain= [other-flags] + infisical login --domain= ``` #### 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. + 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" --jwt= --machine-identity-id= + 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/api" --email user@example.com --password "password" + infisical login --domain="https://your-self-hosted-infisical.com" ``` @@ -558,11 +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 + # Basic direct login (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" + # 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) @@ -584,7 +580,7 @@ The following examples demonstrate different ways to authenticate as a user with ``` - **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. + **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. @@ -622,7 +618,7 @@ In this example we'll be using the `universal-auth` method to login to obtain an ``` - **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. + **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. 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. diff --git a/docs/cli/usage.mdx b/docs/cli/usage.mdx index c91ac5736..e158539db 100644 --- a/docs/cli/usage.mdx +++ b/docs/cli/usage.mdx @@ -127,7 +127,7 @@ The CLI is designed for a variety of secret management applications ranging from 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. @@ -136,7 +136,7 @@ For versions prior to v0.4.0, the CLI defaults to the US Cloud. To connect to th **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: +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 @@ -175,7 +175,7 @@ The CLI defaults to the US Cloud (https://app.infisical.com). To connect to the infisical login --domain="https://your-domain.infisical.com" --method=universal-auth --client-id= --client-secret= --silent --plain # All subsequent commands must also include --domain - infisical secrets --domain="https://your-domain.infisical.com" --projectId --env dev + infisical secrets --domain="https://your-domain.infisical.com" --projectId= --env=dev ``` @@ -242,12 +242,12 @@ For security and privacy concerns, we recommend you to configure your terminal t ## FAQ - - 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**. + + 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 to configure the domain for **all CLI commands**. - #### Method 1:Use the updated CLI (v0.4.0+) + #### Method 1: Use the updated CLI (v0.4.0+) - 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. + 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 @@ -287,15 +287,15 @@ For security and privacy concerns, we recommend you to configure your terminal t #### Method 3: Set manually on every command - If you prefer not to set the environment variable, you must include the `--domain` flag on **every CLI 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 # 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 --env dev - infisical export --domain="https://your-self-hosted-infisical.com/api" --format=dotenv-export + infisical secrets --domain="https://your-self-hosted-infisical.com" --projectId --env dev + infisical export --domain="https://your-self-hosted-infisical.com" --format=dotenv-export ``` From dbf9d8c57d11ab682abab285ffc9fa3367b03f36 Mon Sep 17 00:00:00 2001 From: x032205 Date: Wed, 26 Nov 2025 19:23:16 -0500 Subject: [PATCH 3/4] make MUST lowercase --- docs/cli/usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli/usage.mdx b/docs/cli/usage.mdx index e158539db..16c35b3b6 100644 --- a/docs/cli/usage.mdx +++ b/docs/cli/usage.mdx @@ -136,7 +136,7 @@ For versions prior to v0.4.0, the CLI defaults to US Cloud. To connect to EU Clo **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: +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 From af2c1b31bce15c922d63c4053ae1b373af43f308 Mon Sep 17 00:00:00 2001 From: x032205 Date: Wed, 26 Nov 2025 19:25:25 -0500 Subject: [PATCH 4/4] remove unnecessary "to" --- docs/cli/usage.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cli/usage.mdx b/docs/cli/usage.mdx index 16c35b3b6..04a7cb025 100644 --- a/docs/cli/usage.mdx +++ b/docs/cli/usage.mdx @@ -243,7 +243,7 @@ For security and privacy concerns, we recommend you to configure your terminal t - 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 to configure the domain for **all CLI commands**. + 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+)