junobuild · peterpeterparker · Aug 4, 2025 · Aug 1, 2025 · Aug 1, 2025 · Aug 3, 2025
diff --git a/.llms-snapshots/llms-full.txt b/.llms-snapshots/llms-full.txt
@@ -7371,24 +7371,6 @@ If you've previously authenticated your terminal and decide to log in again, the
 
 This allows you to reuse your authorization, especially when creating new modules like satellites or orbiters.
 
-#### Modes
-
-The CLI supports multiple environment modes (`production`, `staging`, `development`, etc.).
-
-Each mode requires its own login and identity for security reasons. For example: `juno login --mode staging` or `juno login --mode development`. If no mode is specified, it defaults to `production`.
-
-#### How does it work?
-
-A new [principal](/docs/terminology.md#principal) is generated on your local machine and added as a administrator [access key](/docs/miscellaneous/access-keys.md) of the selected modules. This principal is then used to authenticate any CLI calls made from your terminal to your satellites, mission controls or other modules.
-
-The key is saved in the OS-specific user's variables path, for example:
-
-| OS  | Path |
-| --- | --- |
-| Mac | `~/Library/Preferences/juno-nodejs` |
-| Windows | `%APPDATA%\juno-nodejs\Config` (for example, `C:\Users\USERNAME\AppData\Roaming\juno-nodejs\Config`) |
-| Linux | `~/.config/juno-nodejs` (or `$XDG_CONFIG_HOME/juno-nodejs`) |
-
 ---
 
 ### Logout
@@ -7634,34 +7616,74 @@ Usage: juno open [options]Options:  -b, --browser         A particular browser t
 
 ---
 
-### Use
+### Version
 
-Switch between multiple profiles.
+Check the version of the modules and CLI.
 
 ```
-Usage: juno use [options]Options:  -p, --profile         The profile that should be use.  -l, --list            What are the available profiles.  -h, --help            Output usage information.
+Usage: juno init [options]Options:  -c, --cli             Check only the version of the CLI.  -m, --mode            Choose which environment to use (production, staging, development). Defaults to production if omitted.  --container-url       Override a custom container URL. If not provided, defaults to production or the local container in development mode.  --console-url         Specify a custom URL to access the developer Console.  -h, --help            Output usage information.
 ```
 
 ---
 
-### Version
+### Who am I?
 
-Check the version of the modules and CLI.
+Display your current profile, access key, and links to your satellite.
 
 ```
-Usage: juno init [options]Options:  -c, --cli             Check only the version of the CLI.  -m, --mode            Choose which environment to use (production, staging, development). Defaults to production if omitted.  --container-url       Override a custom container URL. If not provided, defaults to production or the local container in development mode.  --console-url         Specify a custom URL to access the developer Console.  -h, --help            Output usage information.
+Usage: juno whoami [options]Options:  -h, --help            Output usage information.  -m, --mode            Choose which environment to use (production, staging, development). Defaults to production if omitted.  --container-url       Override a custom container URL. If not provided, defaults to production or the local container in development mode.  --console-url         Specify a custom URL to access the developer Console.
 ```
 
 ---
 
-### Who am I?
+## Environment
 
-Display your current profile, access key, and links to your satellite.
+Some CLI flags affect the context of your commands, such as which environment you're working in or which identity you're using. These flags are global and apply to most commands.
+
+---
+
+### Mode
+
+The `--mode` flag lets you target a specific environment when executing CLI commands. This is useful for working across development, staging, and production setups.
 
 ```
-Usage: juno whoami [options]Options:  -h, --help            Output usage information.  -m, --mode            Choose which environment to use (production, staging, development). Defaults to production if omitted.  --container-url       Override a custom container URL. If not provided, defaults to production or the local container in development mode.  --console-url         Specify a custom URL to access the developer Console.
+juno login --mode developmentjuno deploy --mode staging
+```
+
+The value for `--mode` can be any string. If omitted, it defaults to production.
+
+---
+
+### Profile
+
+The optional `--profile` flag lets you switch between different identities. Useful when working with multiple Mission Controls.
+
+```
+juno login --profile teamjuno deploy --profile team --mode staging
 ```
 
+It accepts any string. If omitted, no profile is used.
+
+---
+
+### Local Persistence
+
+Unless you run it in headless mode with a token, the Juno CLI stores data locally in the following OS-specific user's variables path to work properly.
+
+| OS  | Path |
+| --- | --- |
+| Mac | `~/Library/Preferences/juno-nodejs` |
+| Windows | `%APPDATA%\juno-nodejs\Config` (for example, `C:\Users\USERNAME\AppData\Roaming\juno-nodejs\Config`) |
+| Linux | `~/.config/juno-nodejs` (or `$XDG_CONFIG_HOME/juno-nodejs`) |
+
+These config files are created based on the selected `--profile` and `--mode`:
+
+| File | Encrypted | Purpose |
+| --- | --- | --- |
+| `juno[-profile][-mode]` | ✅   | Stores the [access key](/docs/miscellaneous/access-keys.md) ([principal](/docs/terminology.md#principal)) and list of modules. |
+| `juno[-profile][-mode]-cli-settings` |     | Stores CLI preferences, e.g. whether the access key file is encrypted (to avoid unnecessary prompts). |
+| `juno[-profile][-mode]-cli-state` |     | Stores ephemeral state like applied config hashes. |
+
 # Configuration
 
 When the `juno` command is run from your terminal or used in a CI environment, it will automatically attempt to locate a config file named `juno.config.ts` or `juno.config.js` or `juno.config.json` within your project's root directory.
@@ -8110,20 +8132,6 @@ import { defineConfig } from "@junobuild/config";export default defineConfig(({
 
 ---
 
-## Modes
-
-By default, the CLI runs command for the `production` mode.
-
-This means when running a `juno` command in your terminal, it will pass the mode `production` to read your configuration.
-
-You can overwrite the default mode used for a command by passing the `--mode` option flag. For example, if you want to deploy your app for a `staging` mode:
-
-```
-juno deploy --mode staging
-```
-
----
-
 ## Multiple Environments
 
 You might want to deploy or manage a project across different environments, such as staging and production. Juno supports this through the `ids` field, allowing you to define separate Satellite IDs for each ([mode](#modes)).

diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx
@@ -61,26 +61,6 @@ If you've previously authenticated your terminal and decide to log in again, the
 
 This allows you to reuse your authorization, especially when creating new modules like satellites or orbiters.
 
-#### Modes
-
-The CLI supports multiple environment modes (`production`, `staging`, `development`, etc.).
-
-Each mode requires its own login and identity for security reasons.
-For example: `juno login --mode staging` or `juno login --mode development`.
-If no mode is specified, it defaults to `production`.
-
-#### How does it work?
-
-A new [principal] is generated on your local machine and added as a administrator [access key](../miscellaneous/access-keys.md) of the selected modules. This principal is then used to authenticate any CLI calls made from your terminal to your satellites, mission controls or other modules.
-
-The key is saved in the OS-specific user's variables path, for example:
-
-| OS      | Path                                                                                                 |
-| ------- | ---------------------------------------------------------------------------------------------------- |
-| Mac     | `~/Library/Preferences/juno-nodejs`                                                                  |
-| Windows | `%APPDATA%\juno-nodejs\Config` (for example, `C:\Users\USERNAME\AppData\Roaming\juno-nodejs\Config`) |
-| Linux   | `~/.config/juno-nodejs` (or `$XDG_CONFIG_HOME/juno-nodejs`)                                          |
-
 ---
 
 ### Logout
@@ -292,14 +272,6 @@ import Open from "./cli/open.md";
 
 ---
 
-### Use
-
-import Use from "./cli/use.md";
-
-<Use />
-
----
-
 ### Version
 
 import Version from "./cli/version.md";
@@ -314,6 +286,58 @@ import WhoAmI from "./cli/whoami.md";
 
 <WhoAmI />
 
+---
+
+## Environment
+
+Some CLI flags affect the context of your commands, such as which environment you're working in or which identity you're using. These flags are global and apply to most commands.
+
+---
+
+### Mode
+
+The `--mode` flag lets you target a specific environment when executing CLI commands. This is useful for working across development, staging, and production setups.
+
+```bash
+juno login --mode development
+juno deploy --mode staging
+```
+
+The value for `--mode` can be any string. If omitted, it defaults to production.
+
+---
+
+### Profile
+
+The optional `--profile` flag lets you switch between different identities. Useful when working with multiple Mission Controls.
+
+```bash
+juno login --profile team
+juno deploy --profile team --mode staging
+```
+
+It accepts any string. If omitted, no profile is used.
+
+---
+
+### Local Persistence
+
+Unless you run it in headless mode with a token, the Juno CLI stores data locally in the following OS-specific user's variables path to work properly.
+
+| OS      | Path                                                                                                 |
+| ------- | ---------------------------------------------------------------------------------------------------- |
+| Mac     | `~/Library/Preferences/juno-nodejs`                                                                  |
+| Windows | `%APPDATA%\juno-nodejs\Config` (for example, `C:\Users\USERNAME\AppData\Roaming\juno-nodejs\Config`) |
+| Linux   | `~/.config/juno-nodejs` (or `$XDG_CONFIG_HOME/juno-nodejs`)                                          |
+
+These config files are created based on the selected `--profile` and `--mode`:
+
+| File                                 | Encrypted | Purpose                                                                                               |
+| ------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------- |
+| `juno[-profile][-mode]`              | ✅        | Stores the [access key](../miscellaneous/access-keys.md) ([principal]) and list of modules.           |
+| `juno[-profile][-mode]-cli-settings` |           | Stores CLI preferences, e.g. whether the access key file is encrypted (to avoid unnecessary prompts). |
+| `juno[-profile][-mode]-cli-state`    |           | Stores ephemeral state like applied config hashes.                                                    |
+
 [satellite]: ../terminology.md#satellite
 [mission control]: ../terminology.md#mission-control
 [principal]: ../terminology.md#principal

diff --git a/docs/reference/cli/use.md b/docs/reference/cli/use.md
diff --git a/docs/reference/configuration.mdx b/docs/reference/configuration.mdx
@@ -481,20 +481,6 @@ export default defineConfig(({ mode }) => ({
 
 ---
 
-## Modes
-
-By default, the CLI runs command for the `production` mode.
-
-This means when running a `juno` command in your terminal, it will pass the mode `production` to read your configuration.
-
-You can overwrite the default mode used for a command by passing the `--mode` option flag. For example, if you want to deploy your app for a `staging` mode:
-
-```bash
-juno deploy --mode staging
-```
-
----
-
 ## Multiple Environments
 
 You might want to deploy or manage a project across different environments, such as staging and production. Juno supports this through the `ids` field, allowing you to define separate Satellite IDs for each [mode](#modes).