Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(cli): document named login profiles

Scott Wilson52310551c5e7
diff --git a/docs/cli/commands/init.mdx b/docs/cli/commands/init.mdx
index 3ce5015008..3c76d11a23 100644
--- a/docs/cli/commands/init.mdx
+++ b/docs/cli/commands/init.mdx
@@ -12,5 +12,15 @@ infisical init
Link a local project to your Infisical project. Once connected, you can then access the secrets locally from the connected Infisical project.
<Info>
-This command creates a `.infisical.json` file containing your Project ID.
+ This command creates a `.infisical.json` file containing your Project ID.
</Info>
+
+The command lists the projects of the organization that your profile uses. To link a project in another organization, change the default with `infisical profile set-org`. You can also create a profile for that organization with `infisical profile new`. See [profile](./profile).
+
+<Warning>
+ Do not pass `--org` to link a project from another organization. Later
+ commands use the organization of the profile and cannot find that project.
+ The command stops and names the two options above.
+</Warning>
+
+If you have more than one profile, the command offers to bind this directory to the profile that it used. Commands that run here then select that profile with no flag and no environment variable. Run `infisical profile unbind` to remove the binding.
diff --git a/docs/cli/commands/login.mdx b/docs/cli/commands/login.mdx
index 3238441062..efc4534dcd 100644
--- a/docs/cli/commands/login.mdx
+++ b/docs/cli/commands/login.mdx
@@ -19,7 +19,7 @@ When authenticated, a token is generated and saved in your system Keyring to all
To change where the login credentials are stored, visit the [vaults command](./vault).
-If you have added multiple users, you can switch between the users by using the [user command](./user).
+Each login is stored as a profile: an account on the specified Infisical instance, with the organization that it uses by default. A login without flags becomes the default profile for this machine. To store a login under a name you choose, and leave the default alone, pass `--save-as`. See [profile](./profile) for how to select from existing profiles.
<Info>
**JWT Token Output:**
@@ -67,6 +67,14 @@ User authentication is designed for individual developers and supports multiple
<ParamField query="plain" type="boolean" optional>
Output only the JWT token (useful for scripting and CI/CD).
</ParamField>
+ <ParamField query="save-as" type="string" optional>
+ Store this login as the named profile, creating a new profile or replacing
+ an existing one's session. The new profile is not automatically selected.
+ </ParamField>
+ <ParamField query="profile" type="string" optional>
+ Sign back in to a profile that already exists, restoring its account,
+ instance, and organization.
+ </ParamField>
</Expandable>
</ParamField>
@@ -491,6 +499,36 @@ The login command supports a number of flags that you can use for different auth
#### Description
Forces interactive CLI login where you'll be prompted to enter your email, password, and select your organization in the terminal, instead of opening a browser.
+ </Accordion>
+ <Accordion title="--save-as">
+ ```bash
+ infisical login --save-as <name>
+ ```
+
+ #### Description
+ Stores this login as the named profile. The CLI creates the profile, or replaces the session of an existing profile that already has that name.
+
+ A login with `--save-as` does not change the default profile, so other terminals keep the profile that they are already using.
+
+ ```bash
+ # Sign in to a second account and keep the first.
+ infisical login --save-as contractor
+ infisical --profile contractor secrets
+ ```
+
+ </Accordion>
+ <Accordion title="--profile">
+ ```bash
+ infisical login --profile <name>
+ ```
+
+ #### Description
+ Signs back in to a profile that already exists. The profile keeps its account, its instance, and its organization, so you do not have to pass `--organization-id`.
+
+ ```bash
+ infisical login --profile globex
+ ```
+
</Accordion>
<Accordion title="--plain">
```bash
@@ -633,24 +671,24 @@ The following examples demonstrate different ways to authenticate as a user with
<Accordion title="infisical login status" defaultOpen="true">
Reports whether the CLI is currently authenticated to Infisical and, when available, the organization the active session is scoped to. The command checks the user session stored in your vault, machine identity tokens exported as environment variables, and a token passed via the `--token` flag.
- ```bash
- infisical login status
- ```
+```bash
+infisical login status
+```
- In addition to local checks (token presence, local expiration), `status` calls the Infisical backend to verify that each credential is still valid — so revoked or rejected tokens are surfaced even when they look fine locally.
+In addition to local checks (token presence, local expiration), `status` calls the Infisical backend to verify that each credential is still valid — so revoked or rejected tokens are surfaced even when they look fine locally.
- #### Sources checked
+#### Sources checked
- - **User session**: the active login stored in your system keyring (or the configured [vault](./vault)).
- - **Machine identity environment variable**: `INFISICAL_TOKEN`.
- - **`--token` flag**: a specific machine identity access token passed explicitly.
+- **User session**: the active login stored in your system keyring (or the configured [vault](./vault)). The report names the profile that the session belongs to, and how the CLI selected it.
+- **Machine identity environment variable**: `INFISICAL_TOKEN`.
+- **`--token` flag**: a specific machine identity access token passed explicitly.
- #### Exit codes
+#### Exit codes
- - `0`: at least one session was reported and none are expired or rejected.
- - `1`: no active session was found, or a reported session is expired or rejected by the backend.
+- `0`: at least one session was reported and none are expired or rejected.
+- `1`: no active session was found, or a reported session is expired or rejected by the backend.
- #### Flags
+#### Flags
<Accordion title="--json">
Output the login status as JSON instead of the default human-readable format. Useful for scripting and CI/CD pipelines.
@@ -670,7 +708,7 @@ The following examples demonstrate different ways to authenticate as a user with
</Accordion>
- #### Examples
+#### Examples
<AccordionGroup>
<Accordion title="Check the active user session">
@@ -683,10 +721,12 @@ The following examples demonstrate different ways to authenticate as a user with
```bash
✓ Authenticated as [email protected]
- Domain: https://app.infisical.com
- - Auth method: login
+ - Profile: [email protected] (via default profile)
+ - Auth method: email
- Token source: infisical login (keyring)
- Token expiration: 6h 12m
- - Organization: org-id-123
+ - User ID: 4377366c-e6b4-437f-865c-bbf90ace32f9
+ - Organization: Acme (9c0f4df6-57fb-4b5f-927b-799dc0121520)
```
</Accordion>
@@ -712,6 +752,7 @@ The following examples demonstrate different ways to authenticate as a user with
```
</Accordion>
+
</AccordionGroup>
</Accordion>
diff --git a/docs/cli/commands/logout.mdx b/docs/cli/commands/logout.mdx
new file mode 100644
index 0000000000..d663d42647
--- /dev/null
+++ b/docs/cli/commands/logout.mdx
@@ -0,0 +1,54 @@
+---
+title: "infisical logout"
+description: "End a login session"
+---
+
+```bash
+infisical logout
+```
+
+## Description
+
+This command ends a login session. The CLI removes the stored credentials of the profile from this machine, and revokes its session on the server.
+
+The profile is kept, so `infisical login --profile <name>` signs back in without setting it up again. To remove the profile as well, run `infisical profile delete`.
+
+By default the command logs out of the profile that the current directory and terminal are set to. See [profile](./profile) for how the CLI selects profiles.
+
+<Info>
+ While each profile stores its own credentials, multiple profiles for one
+ account on a single machine share a server session. Logout always removes the
+ current profile's credentials, and revokes the shared session only when no
+ profile that you keep still uses it.
+</Info>
+
+### Flags
+
+<AccordionGroup>
+ <Accordion title="--all">
+ Log out of every profile on this machine.
+
+ ```bash
+ infisical logout --all
+ ```
+
+ </Accordion>
+
+ <Accordion title="--local-only">
+ Remove the stored credentials without revoking the session on the server. The session stays valid until it expires.
+
+ ```bash
+ infisical logout --local-only
+ ```
+
+ </Accordion>
+
+ <Accordion title="--profile">
+ Log out of a specific profile.
+
+ ```bash
+ infisical logout --profile globex
+ ```
+
+ </Accordion>
+</AccordionGroup>
diff --git a/docs/cli/commands/org.mdx b/docs/cli/commands/org.mdx
new file mode 100644
index 0000000000..10d249bd62
--- /dev/null
+++ b/docs/cli/commands/org.mdx
@@ -0,0 +1,65 @@
+---
+title: "infisical org"
+description: "List organizations and set the one a profile uses"
+---
+
+```bash
+infisical org
+```
+
+## Description
+
+This command shows the organizations that your account can use, and sets the organization that the current profile uses by default.
+
+A profile is a single login: an account on the specified Infisical instance, with the organization that it uses by default. See [profile](./profile) for how the CLI selects a profile.
+
+### Sub-commands
+
+<Accordion title="infisical org list" defaultOpen="true">
+ List the organizations that the account of this profile can use. The organization that the current profile uses is marked with an asterisk.
+
+```bash
+infisical org list
+```
+
+Sub-organizations appear indented under the organization that it belongs to.
+
+```bash
+CURRENT NAME SLUG ID
+ Acme acme 9c0f4df6-57fb-4b5f-927b-799dc0121520
+* └─ Research acme-research ff714dbe-8a8a-4a88-83b8-2bf776f91ed3
+ Globex globex-inc d68da2e6-8441-4341-a6cd-fd6d7643e3bc
+```
+
+</Accordion>
+
+<Accordion title="infisical org switch">
+ Set the organization that the current profile uses by default. This command is an alias for `infisical profile set-org`.
+
+```bash
+infisical org switch globex-inc
+```
+
+If you omit the organization, the CLI will ask you to pick one.
+
+<Tip>
+ To use another organization for a single command, pass `--org`. To keep a
+ second organization available at the same time, run `infisical profile new`.
+</Tip>
+
+</Accordion>
+
+### Choosing an organization for one command
+
+Pass `--org` to retarget a single command. Name the organization by name, slug, or id.
+
+```bash
+infisical --org globex-inc secrets
+```
+
+The default organization of the profile does not change. The CLI caches the session for each organization that you use this way.
+
+<Tip>
+ The `org` flag can be substituted with the `INFISICAL_ORG` environment
+ variable.
+</Tip>
diff --git a/docs/cli/commands/profile.mdx b/docs/cli/commands/profile.mdx
new file mode 100644
index 0000000000..2659770b4e
--- /dev/null
+++ b/docs/cli/commands/profile.mdx
@@ -0,0 +1,311 @@
+---
+title: "infisical profile"
+description: "Keep a login per organization and choose between them"
+---
+
+```bash
+infisical profile
+```
+
+## Description
+
+A profile is a single login: an account on the specified Infisical instance, with the organization that it uses by default. Each profile keeps its own session, so you can work in several organizations at the same time.
+
+The organization is a setting on a profile, not part of its identity. To use another organization for a single command, pass `--org`. To change the default organization for a profile, run `infisical profile set-org`.
+
+### How a profile is selected
+
+Every command selects a profile in this order:
+
+1. The `--profile` flag.
+2. The `INFISICAL_PROFILE` environment variable.
+3. A directory that you bound to a profile, with `infisical profile bind` or during `infisical init`.
+4. The default profile for the machine, set with `infisical profile use`.
+
+The first one that applies wins. If an override hides a bound directory, the CLI reports which profile it used and why.
+
+<Info>
+ Your first login creates a profile for you. The name comes from your account
+ and organization, for example `[email protected]`.
+</Info>
+
+### Sub-commands
+
+<Accordion title="infisical profile list" defaultOpen="true">
+ List every profile on this machine, with its account, organization, instance, and session state.
+
+```bash
+infisical profile list
+```
+
+The current profile is marked with an asterisk.
+
+```bash
+CURRENT NAME EMAIL ORGANIZATION SESSION DOMAIN DIRECTORY SCOPES
+* [email protected] [email protected] Acme active https://app.infisical.com ~/code/acme
+ globex [email protected] Globex active https://app.infisical.com -
+ research [email protected] Acme / Research active https://app.infisical.com -
+```
+
+</Accordion>
+
+<Accordion title="infisical profile current">
+ Show which profile a command run in the current terminal or directory will use, and why it was selected.
+
+```bash
+infisical profile current
+```
+
+```bash
+Profile: globex
+Selected via: INFISICAL_PROFILE environment variable
+Organization: Globex (9c0f4df6-57fb-4b5f-927b-799dc0121520)
+Organization via: profile default
+Domain: https://app.infisical.com
+```
+
+#### Flags
+
+ <Accordion title="--plain">
+ Print only the profile name. Use this in a shell prompt.
+
+ ```bash
+ infisical profile current --plain
+ ```
+
+ </Accordion>
+
+</Accordion>
+
+<Accordion title="infisical profile new">
+ Create a profile for another organization without logging in again. The new profile reuses the account and instance that you are signed in to.
+
+```bash
+infisical profile new [name]
+```
+
+If you omit `--org`, the CLI will ask you to pick an organization.
+
+```bash
+infisical profile new globex --org globex-inc
+```
+
+#### Flags
+
+ <Accordion title="--use">
+ Also make the new profile the default for this machine.
+
+ ```bash
+ infisical profile new globex --org globex-inc --use
+ ```
+
+ </Accordion>
+
+ <Accordion title="--pin">
+ Also pin this terminal to the new profile. Run the command through `eval`,
+ because a command cannot change the environment of the shell that started it.
+
+ ```bash
+ eval "$(infisical profile new globex --org globex-inc --pin)"
+ ```
+
+ </Accordion>
+
+</Accordion>
+
+<Accordion title="infisical profile use">
+ Make a profile the default for this machine. The default applies when no flag, no environment variable, and no bound directory selects a profile.
+
+```bash
+infisical profile use globex
+```
+
+<Tip>
+ To choose a profile for one terminal, use `infisical profile pin`. To choose
+ one for a directory, use `infisical profile bind`.
+</Tip>
+
+</Accordion>
+
+<Accordion title="infisical profile pin">
+ Pin the current terminal to a profile. Other terminals keep the profile that they already use.
+
+The command prints an export statement. Run it through `eval` to apply it to the shell that you are in.
+
+```bash
+eval "$(infisical profile pin globex)"
+```
+
+<Info>
+ In PowerShell, run `infisical profile pin globex | Invoke-Expression`. In
+ `cmd.exe`, or in a script, set `INFISICAL_PROFILE=globex` yourself.
+</Info>
+
+</Accordion>
+
+<Accordion title="infisical profile unpin">
+ Remove the pin from the current terminal. The terminal falls back to a bound directory, or to the default profile.
+
+```bash
+eval "$(infisical profile unpin)"
+```
+
+</Accordion>
+
+<Accordion title="infisical profile bind">
+ Bind a directory, and every directory under it, to a profile. Commands that run inside it select that profile with no flag and no environment variable.
+
+```bash
+infisical profile bind globex ~/code/globex
+```
+
+If you omit the path, the CLI binds the current directory. If bindings overlap, the nearest one wins.
+
+`infisical init` also offers to bind a directory, if you have more than one profile.
+
+<Info>
+ The binding is stored in your own configuration, never in the repository, so
+ it does not affect anyone else who clones the project.
+</Info>
+
+</Accordion>
+
+<Accordion title="infisical profile unbind">
+ Remove the profile binding from a directory.
+
+```bash
+infisical profile unbind [path]
+```
+
+If you omit the path, the CLI removes the binding that covers the current directory.
+
+</Accordion>
+
+<Accordion title="infisical profile set-org">
+ Set the organization that a profile uses by default. The change persists for future commands.
+
+```bash
+infisical profile set-org globex-inc
+```
+
+<Tip>
+ To use another organization for a single command, pass `--org`. To keep a
+ second organization available as its own profile, run `infisical profile new`.
+</Tip>
+
+</Accordion>
+
+<Accordion title="infisical profile rename">
+ Rename a profile. The stored session, the default-profile setting, and any directory bindings follow the new name.
+
+```bash
+infisical profile rename old-name new-name
+```
+
+<Warning>
+ Update any terminal that you pinned to the old name. The pin holds the old
+ name, so those terminals no longer find the profile.
+</Warning>
+
+</Accordion>
+
+<Accordion title="infisical profile delete">
+ Delete a profile and remove its stored session. The CLI revokes the session on the server as well.
+
+```bash
+infisical profile delete globex
+```
+
+#### Flags
+
+ <Accordion title="--local-only">
+ Remove the profile without revoking its session on the server.
+
+ ```bash
+ infisical profile delete globex --local-only
+ ```
+
+ </Accordion>
+
+</Accordion>
+
+### Global flags
+
+These flags work on every command, not only on `infisical profile`.
+
+<AccordionGroup>
+ <Accordion title="--profile">
+ Use a specific profile for this command.
+
+ ```bash
+ infisical --profile globex secrets
+ ```
+
+ <Tip>
+ The `profile` flag can be substituted with the `INFISICAL_PROFILE`
+ environment variable.
+ </Tip>
+
+ </Accordion>
+
+ <Accordion title="--org">
+ Use a specific organization for this command. Name it by name, slug, or id. The default organization of the profile does not change.
+
+ ```bash
+ infisical --org globex-inc secrets
+ ```
+
+ The CLI caches the session for each organization that you use this way.
+
+ <Tip>
+ The `org` flag can be substituted with the `INFISICAL_ORG` environment
+ variable.
+ </Tip>
+
+ </Accordion>
+</AccordionGroup>
+
+### Examples
+
+<AccordionGroup>
+ <Accordion title="Work in two organizations at once">
+ ```bash
+ # You are already logged in to Acme.
+ infisical profile new globex --org globex-inc
+
+ # Use Globex in this terminal only.
+ eval "$(infisical profile pin globex)"
+ infisical secrets
+ ```
+
+ </Accordion>
+
+ <Accordion title="Give each repository its own organization">
+ ```bash
+ infisical profile bind acme ~/code/acme
+ infisical profile bind globex ~/code/globex
+
+ cd ~/code/globex
+ infisical profile current # globex
+ ```
+
+ </Accordion>
+
+ <Accordion title="Run one command against another organization">
+ ```bash
+ infisical --org globex-inc secrets
+ ```
+
+ The default organization of the profile stays as it was.
+
+ </Accordion>
+
+ <Accordion title="Log in to a second account">
+ ```bash
+ infisical login --save-as contractor
+ infisical --profile contractor secrets
+ ```
+
+ </Accordion>
+</AccordionGroup>
diff --git a/docs/cli/commands/reset.mdx b/docs/cli/commands/reset.mdx
index da4d2a596c..36ad9fd23b 100644
--- a/docs/cli/commands/reset.mdx
+++ b/docs/cli/commands/reset.mdx
@@ -8,4 +8,12 @@ infisical reset
```
## Description
-This command provides a way to clear all Infisical-generated configuration data, effectively resetting the software to its default settings. This can be an effective way to address any persistent issues that arise while using the CLI.
\ No newline at end of file
+
+This command removes all configuration data that Infisical created, and returns the CLI to its default settings. Use it when a problem persists and you want a clean state.
+
+The command removes every profile and its stored credentials. It also revokes those sessions on the server.
+
+<Warning>
+ Run this only when you want to start again. You must log in after it, and any
+ terminal that you pinned to a profile will no longer resolve.
+</Warning>
diff --git a/docs/cli/commands/user.mdx b/docs/cli/commands/user.mdx
index 108b1f23b4..6f98b7df3c 100644
--- a/docs/cli/commands/user.mdx
+++ b/docs/cli/commands/user.mdx
@@ -9,27 +9,38 @@ infisical user
## Description
-This command allows you to manage the current logged in users on the CLI
+This command manages the accounts that are logged in to the CLI.
+
+Each login is stored as a profile: an account on the specified Infisical instance, with the organization that it uses by default. See [profile](./profile) to create profiles, to select one per terminal or per directory, and to work in several organizations at the same time.
### Sub-commands
<Accordion title="infisical user switch" defaultOpen="true">
- Use this command to switch between profiles that are currently logged into the CLI
+ Pick which profile the CLI uses by default on this machine.
```bash
infisical user switch
```
+<Tip>
+ `infisical profile use <name>` does the same thing without a prompt.
+ `infisical profile list` shows the available profile names.
+</Tip>
+
</Accordion>
<Accordion title="infisical user update domain">
- With this command, you can modify the backend API that is utilized for all requests associated with a specific profile.
- For instance, you have the option to point the profile to use either the Infisical Cloud or your own self-hosted Infisical instance.
+ Change the Infisical instance that a profile points to. Use this to move a profile between Infisical Cloud and your own self-hosted instance.
```bash
infisical user update domain
```
+<Warning>
+ The command clears the stored session of that profile. Run
+ `infisical login --profile <name>` to sign in to the new instance.
+</Warning>
+
</Accordion>
<Accordion title="infisical user get token">
diff --git a/docs/cli/commands/vault.mdx b/docs/cli/commands/vault.mdx
index 357465dd78..807a06573e 100644
--- a/docs/cli/commands/vault.mdx
+++ b/docs/cli/commands/vault.mdx
@@ -32,3 +32,8 @@ description: "Change the vault type in Infisical"
To safeguard your login details when using the CLI, Infisical attempts to store them in a system keyring. If a system keyring can't be found on your machine, the data is stored in a config file.
+<Warning>
+ Changing the vault removes your profiles and their stored credentials. The new
+ vault starts empty, so run `infisical login` after the change.
+</Warning>
+
diff --git a/docs/docs.json b/docs/docs.json
index 20e8e16cbb..3e70196a88 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -1301,6 +1301,9 @@
"group": "Core commands",
"pages": [
"cli/commands/login",
+ "cli/commands/logout",
+ "cli/commands/profile",
+ "cli/commands/org",
"cli/commands/init",
"cli/commands/run",
"cli/commands/secrets",