From 293df6332e3c2933da51a19a1a69988bd03943cd Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 11:13:23 -0700 Subject: [PATCH 1/8] docs(auto-activation): add auto-activation concept page and man pages (DEV-89) - New concepts/auto-activation.mdx covering enablement (the BETA feature flag plus the prompt hook), the allow/deny consent flow, nested environments, and deactivation, written against the actual implementation. - Cross-link to it from concepts/activation.mdx. - Regenerate man/flox-activate and man/flox-config and add man/flox-activate-allow and man/flox-activate-deny, synced from the flox/flox man-page sources. - Add the new pages to the docs.json navigation. Co-Authored-By: Claude Opus 4.8 (1M context) --- concepts/activation.mdx | 6 + concepts/auto-activation.mdx | 228 +++++++++++++++++++++++++++++++++++ docs.json | 3 + man/flox-activate-allow.mdx | 95 +++++++++++++++ man/flox-activate-deny.mdx | 100 +++++++++++++++ man/flox-activate.mdx | 103 ++++++++++++++-- man/flox-config.mdx | 42 ++++++- 7 files changed, 561 insertions(+), 16 deletions(-) create mode 100644 concepts/auto-activation.mdx create mode 100644 man/flox-activate-allow.mdx create mode 100644 man/flox-activate-deny.mdx diff --git a/concepts/activation.mdx b/concepts/activation.mdx index b9d916c..89b2ab2 100644 --- a/concepts/activation.mdx +++ b/concepts/activation.mdx @@ -137,6 +137,12 @@ You could do this manually, but Flox will also prompt you to do it for you the first time you attempt to install a package in a directory without an environment and with no environments currently active. + + An in-place activation like this also installs the prompt hook used by + [auto-activation](/concepts/auto-activation), which can activate an + environment automatically when you enter its directory. + + ### Shell Command Sometimes you just want to run a command in the context of your environment, diff --git a/concepts/auto-activation.mdx b/concepts/auto-activation.mdx new file mode 100644 index 0000000..143e625 --- /dev/null +++ b/concepts/auto-activation.mdx @@ -0,0 +1,228 @@ +--- +title: "Auto-activation" +description: "Activate environments automatically when you enter their directory" +--- + +Flox environments are powerful, but remembering to run `flox activate` every +time you enter a project directory can be tedious. +**Auto-activation** activates an environment automatically when you `cd` into a +directory that contains a `.flox` directory, and deactivates it when you leave. +Your packages, environment variables, and hooks are ready without any manual +step. + + + Auto-activation is **experimental** and ships behind a feature flag. + Its behavior is subject to change. + Follow the steps under [Enabling auto-activation](#enabling-auto-activation) + to turn it on. + + +## Enabling auto-activation + +Two things are required: the feature flag, and the Flox prompt hook installed in +your shell. + +### 1. Turn on the feature flag + +Enable the `auto_activate` feature flag, either with an environment variable: + +```bash +export FLOX_FEATURES_AUTO_ACTIVATE=true +``` + +or in your Flox config (`~/.config/flox/flox.toml`): + +```bash +flox config --set features.auto_activate true +``` + +### 2. Install the prompt hook + +The prompt hook drives auto-activation, and it is installed by any **in-place** +activation. +Add an in-place activation of your +[default environment](/tutorials/default-environment) to your shell's startup +file: + + + + Add the following line to the end of your `~/.bashrc`: + + ```bash + eval "$(flox activate -D)" + ``` + + + Add the following line to the end of your `~/.zshrc`: + + ```bash + eval "$(flox activate -D)" + ``` + + + Add the following line to the end of your `~/.config/fish/config.fish`: + + ```bash + flox activate -D | source + ``` + + + Add the following line to the end of your `~/.tcshrc`: + + ```tcsh + eval "`flox activate -D`" + ``` + + + + + Any in-place `flox activate` installs the hook — not just `-D`. + If you already activate an environment in-place at startup (for example + `eval "$(flox activate -r owner/default)"`), the hook is already installed and + you only need to enable the feature flag. + The hook ships with Flox and stays dormant until the feature flag is set, so + enabling and disabling the flag is enough to turn auto-activation on and off. + + +`bash`, `zsh`, `fish`, and `tcsh` are supported. + +## How it works + +Once the hook is installed and the feature flag is on, the hook runs on every +prompt (or directory change, depending on your shell): + +1. **Discovery** — The hook walks from your current directory up to the + filesystem root, collecting every directory that contains a `.flox` + directory. +2. **Eligibility** — Each discovered environment is auto-activated only if you + have [allowed](#allowing-and-denying-environments) it. +3. **Activation** — Eligible environments are activated outermost-first. + Environment variables are set and hooks run. + Services are **not** started unless you set + [`services.auto-start = true`](/man/manifest.toml#options) in the manifest. +4. **Deactivation** — When you leave a directory, its environment is deactivated + and its changes to the shell are reverted. + +Most prompts hit a fast path: the hook detects that nothing relevant has changed +and exits immediately with no output. + +## Allowing and denying environments + +An environment is never auto-activated until you have **allowed** it. +This prevents unexpected code execution when you `cd` into a directory that +contains an unfamiliar `.flox` directory. + + + Before allowing auto-activation for an environment, review its manifest to + understand what its `hook` and `profile` scripts will run. + This matters most for environments from untrusted sources, such as cloned + repositories. + + +### Interactive prompt + +The first time you enter a directory whose environment you have neither allowed +nor denied, Flox prompts you in interactive shells: + +```text +Auto-activate the environment in '/path/to/project'? [y/N] +``` + +Answering **y** allows the environment, activates it, and records the choice so +you are not asked again. +Answering **N** (or pressing Enter) skips it for the current shell session only; +you are asked again in a new shell or when you re-enter the directory. + +This prompt appears only when the `auto_activate` config option is `prompt` +(the default). +Set it to `allowed` to skip the prompt and auto-activate only environments you +have already allowed: + +```bash +flox config --set auto_activate allowed +``` + +### Allowing and denying ahead of time + +Use [`flox activate allow`](/man/flox-activate-allow) and +[`flox activate deny`](/man/flox-activate-deny) to record a decision without +waiting for the prompt: + +```bash +flox activate allow +``` + +```bash +flox activate deny +``` + +Both target the environment in the current directory by default; pass `-d`, +`-r`, or `-D` to target another environment. +To stop being prompted for a specific directory: + +```bash +flox activate deny --dir /path/to/project +``` + +Decisions are stored in your Flox config (`~/.config/flox/flox.toml`) under +`auto_activate_environments`, keyed by the absolute path of the directory that +contains the `.flox` directory. +The latest decision for an environment replaces any previous one. + + + Allowing an environment is tied to its directory, not its manifest contents. + Once allowed, an environment stays allowed even if its manifest changes. + Creating an environment with `flox init` does not allow it automatically — you + allow it explicitly, or by answering **y** at the prompt. + + +## Nested environments + +When several `.flox` directories sit in your current directory's ancestor chain, +all eligible environments are activated at once, outermost-first. +An environment in `/home/you/projects` activates before one in +`/home/you/projects/app`. +The shell prompt reflects every active environment: + +```text +flox [projects app] $ +``` + +Use [`flox deactivate`](/man/flox-deactivate) to peel off layers one at a time, +starting with the innermost (closest to your current directory). + + + Environments in directories owned by other users still require an explicit + allow, like any other environment. + Directory ownership alone neither grants nor denies auto-activation. + + +## Deactivation + +[`flox deactivate`](/man/flox-deactivate) is the unified way to leave any +environment, whether it was activated manually or automatically. +It reverses the **innermost** environment: it reverts the environment variables +that environment set, restores the shell prompt, and **suppresses** that +environment so the hook does not re-activate it while you stay in the directory. + +Only the innermost environment can be deactivated. +Running `flox deactivate` against a non-innermost environment fails with a +helpful error — deactivate the inner layers first. +If you leave the directory and return later, the suppression is lifted and the +environment auto-activates again. + +## Comparison with manual activation + +Auto-activation and `flox activate` share the same core behavior — packages, +environment variables, and hooks — but differ in a few ways: + +| Behavior | `flox activate` (manual) | Auto-activation | +| --- | --- | --- | +| **Trigger** | Explicit `flox activate` command | Automatic on `cd` into a `.flox` directory | +| **Gate** | None — you chose to activate | Requires the feature flag and an allowed environment | +| **Deactivation** | `flox deactivate` or `exit` (subshell) | `flox deactivate` | +| **Failure** | Activation aborts on failure | A failed activation aborts; other layers still activate | + +See [Activating environments](/concepts/activation) for how activation works in +general, and [`flox-activate`](/man/flox-activate) for the full command +reference. diff --git a/docs.json b/docs.json index a57e23b..9e16ce4 100644 --- a/docs.json +++ b/docs.json @@ -114,6 +114,7 @@ "pages": [ "concepts/environments", "concepts/activation", + "concepts/auto-activation", "concepts/compatibility", "concepts/floxhub", "concepts/floxhub-environments", @@ -178,6 +179,8 @@ "group": "Environments", "pages": [ "man/flox-activate", + "man/flox-activate-allow", + "man/flox-activate-deny", "man/flox-edit", "man/flox-delete", "man/flox-envs" diff --git a/man/flox-activate-allow.mdx b/man/flox-activate-allow.mdx new file mode 100644 index 0000000..cd03759 --- /dev/null +++ b/man/flox-activate-allow.mdx @@ -0,0 +1,95 @@ +--- +title: "flox activate allow" +--- + +## NAME + +flox-activate-allow - allow auto-activation for an environment + +## SYNOPSIS + +```text +flox [] activate allow + [-d= | -r=/ | -D] +``` + +## DESCRIPTION + +> **Experimental:** Auto-activation is experimental and behind a feature +> flag, and its behavior is subject to change. Enable it by setting +> `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment, or by running +> `flox config --set features.auto_activate true`. See the +> *AUTO-ACTIVATION* section of *flox-activate(1)* for details. + +Records that the selected environment may be auto-activated. + +Once an environment is allowed, the Flox prompt hook activates it +automatically whenever you enter a directory containing it, without +prompting. The preference is stored in the user config file under +`auto_activate_environments`, keyed by the absolute path of the +directory that contains the `.flox` directory. + +By default `flox activate allow` targets the environment in the current +directory. Use the environment options below to target a different +environment. + +To stop an environment from being auto-activated, run +[`flox-activate-deny`](/man/flox-activate-deny). + +See the *AUTO-ACTIVATION* section of +[`flox-activate`](/man/flox-activate) for the full picture, including +the consent prompt and how to enable the feature. + +## OPTIONS + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--reference` +A FloxHub environment, specified in the form `/`. + +`-D`, `--default` +Use your default environment (`/default`). When +unauthenticated in an interactive context, you will be prompted to log +in. In non-interactive contexts (e.g., scripts or CI), this flag will +fail with an error when authentication is missing. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES + +Allow auto-activation for the environment in the current directory: + +```bash +flox activate allow +``` + +Allow auto-activation for an environment in another directory: + +```bash +flox activate allow -d /path/to/project +``` + +## SEE ALSO + +[`flox-activate`](/man/flox-activate), +[`flox-activate-deny`](/man/flox-activate-deny), +[`flox-config`](/man/flox-config) diff --git a/man/flox-activate-deny.mdx b/man/flox-activate-deny.mdx new file mode 100644 index 0000000..7d89d40 --- /dev/null +++ b/man/flox-activate-deny.mdx @@ -0,0 +1,100 @@ +--- +title: "flox activate deny" +--- + +## NAME + +flox-activate-deny - deny auto-activation for an environment + +## SYNOPSIS + +```text +flox [] activate deny + [-d= | -r=/ | -D] +``` + +## DESCRIPTION + +> **Experimental:** Auto-activation is experimental and behind a feature +> flag, and its behavior is subject to change. Enable it by setting +> `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment, or by running +> `flox config --set features.auto_activate true`. See the +> *AUTO-ACTIVATION* section of *flox-activate(1)* for details. + +Records that the selected environment must not be auto-activated. + +Once an environment is denied, the Flox prompt hook skips it silently +when you enter a directory containing it, and you are no longer prompted +for it. The preference is stored in the user config file under +`auto_activate_environments`, keyed by the absolute path of the +directory that contains the `.flox` directory. + +Denying an environment does not deactivate it if it is already active; +it only prevents future auto-activation. Run +[`flox-deactivate`](/man/flox-deactivate) to leave an environment +that is currently active. + +By default `flox activate deny` targets the environment in the current +directory. Use the environment options below to target a different +environment. + +To allow an environment to be auto-activated again, run +[`flox-activate-allow`](/man/flox-activate-allow). + +See the *AUTO-ACTIVATION* section of +[`flox-activate`](/man/flox-activate) for the full picture, including +the consent prompt and how to enable the feature. + +## OPTIONS + +### Environment Options + +If no environment is specified for an environment command, the +environment in the current directory or the active environment that was +last activated is used. + +`-d`, `--dir` +Path containing a .flox/ directory. + +`-r`, `--reference` +A FloxHub environment, specified in the form `/`. + +`-D`, `--default` +Use your default environment (`/default`). When +unauthenticated in an interactive context, you will be prompted to log +in. In non-interactive contexts (e.g., scripts or CI), this flag will +fail with an error when authentication is missing. + +### General Options + +`-h`, `--help` +Prints help information. + +The following options can be passed when running any `flox` subcommand +but must be specified *before* the subcommand. + +`-v`, `--verbose` +Increase logging verbosity. Invoke multiple times for increasing detail. + +`-q`, `--quiet` +Silence logs except for errors. + +## EXAMPLES + +Deny auto-activation for the environment in the current directory: + +```bash +flox activate deny +``` + +Stop being prompted for an environment in another directory: + +```bash +flox activate deny -d /path/to/project +``` + +## SEE ALSO + +[`flox-activate`](/man/flox-activate), +[`flox-activate-allow`](/man/flox-activate-allow), +[`flox-config`](/man/flox-config) diff --git a/man/flox-activate.mdx b/man/flox-activate.mdx index 058c76a..ff10be9 100644 --- a/man/flox-activate.mdx +++ b/man/flox-activate.mdx @@ -30,20 +30,20 @@ Configures a shell with everything defined by the environment: `flox activate` may run in one of four modes: -- interactive: `flox activate` when invoked from an interactive shell +- interactive: `flox activate` when invoked from an interactive shell\ Launches an interactive sub-shell. The shell to be launched is determined by `$FLOX_SHELL` or `$SHELL`. -- shell command: `flox activate -c CMD` +- shell command: `flox activate -c CMD`\ Runs `CMD` in the same environment as if run inside an interactive shell produced by an interactive `flox activate`. The shell `CMD` is run by is determined by `$FLOX_SHELL` or `$SHELL`. Because `CMD` is passed to a shell, shell features like running multiple commands with `&&` can be used. -- exec command: `flox activate -- CMD` +- exec command: `flox activate -- CMD`\ Execs `CMD` directly after performing all parts of activation except for running scripts in `[profile]`. - in-place: `flox activate` when invoked from a non-interactive shell - with its `stdout` redirected e.g. `eval "$(flox activate)"` + with its `stdout` redirected e.g. `eval "$(flox activate)"`\ Produces commands to be sourced by the parent shell. Flox will determine the parent shell from `$FLOX_SHELL` or otherwise automatically determine the parent shell and fall back to `$SHELL`. @@ -71,6 +71,78 @@ To reverse activation, run [`flox-deactivate`](/man/flox-deactivate). Inside a `flox activate` subshell, `flox deactivate` is equivalent to `exit`. +## AUTO-ACTIVATION + +> **Experimental:** Auto-activation is experimental and behind a feature +> flag, and its behavior is subject to change. Enable it by setting +> `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment, or by running +> `flox config --set features.auto_activate true`. See the +> *AUTO-ACTIVATION* section of *flox-activate(1)* for details. + +Auto-activation activates an environment automatically when you enter a +directory that contains it, and deactivates it when you leave, so you do +not have to run `flox activate` by hand. + +### Enabling auto-activation + +Two things are required: + +1. The Flox prompt hook must be installed in your shell. The hook is + installed by any in-place activation, so add a line such as + `eval "$(flox activate -D)"` to your shell’s startup file (for + example `~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`, or + `~/.tcshrc`). If you already activate a default or other environment + in-place at startup, the hook is already installed. The hook ships + with Flox and stays dormant until the feature flag below is set. Set + `disable_hook = true` to opt out of the hook entirely. +2. The `auto_activate` feature flag must be enabled, either with + `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment or with + `flox config --set features.auto_activate true`. + +`bash`, `zsh`, `fish`, and `tcsh` are supported. + +### How it works + +On each prompt the hook looks for `.flox` environments at or above the +current directory. An environment is auto-activated only if you have +allowed it. Allowed environments are activated outermost-first; when you +leave their directory they are deactivated again. Services are not +started unless `services.auto-start = true` is set in the manifest. + +### Allowing and denying environments + +The first time you enter a directory with an environment that you have +neither allowed nor denied, and `auto_activate` is set to `prompt` (the +default), Flox asks before activating it: + +```text +Auto-activate the environment in '/path/to/project'? [y/N] +``` + +Answering `y` allows the environment and activates it immediately, and +records the choice so you are not asked again. Answering `N` (or +pressing Enter) skips the environment for the current shell session +only; you are asked again in a new shell or when you re-enter the +directory. To stop being asked for a directory, run +[`flox-activate-deny`](/man/flox-activate-deny): + +```bash +flox activate deny --dir /path/to/project +``` + +Set the `auto_activate` config option to `allowed` to skip the prompt +entirely and auto-activate only environments you have already allowed. + +Manage these decisions ahead of time with the +[`flox-activate-allow`](/man/flox-activate-allow) and +[`flox-activate-deny`](/man/flox-activate-deny) subcommands. +Decisions are stored in the user config file under +`auto_activate_environments`. + +See [`flox-config`](/man/flox-config) for the `auto_activate`, +`auto_activate_environments`, `auto_activate_fish_mode`, and +`disable_hook` options. + ## OPTIONS ### Activate Options @@ -206,13 +278,15 @@ emit commands to configure an already-running (parent) shell. In both of these cases Flox needs to know which shell to use, and these variables are used to control the selection process. -- interactive and command modes: When launching a sub-shell Flox will - invoke the shell specified in `$FLOX_SHELL` if set or fall back to - invoke `$SHELL` by default. -- in-place mode: When performing an “in place” activation Flox will - attempt to detect its parent shell type unless overridden by the - `$FLOX_SHELL` variable, and if it cannot detect its parent shell type - then will produce a script with syntax determined by `$SHELL`. + * interactive and command modes: When launching a sub-shell + Flox will invoke + the shell specified in `$FLOX_SHELL` if set + or fall back to invoke `$SHELL` by default. + * in-place mode: When performing an "in place" activation + Flox will attempt to detect its parent shell type unless overridden by + the `$FLOX_SHELL` variable, + and if it cannot detect its parent shell type then will + produce a script with syntax determined by `$SHELL`. `$FLOX_PROMPT_COLOR_{1,2}` Flox adds text to the beginning of the shell prompt to indicate which @@ -254,5 +328,8 @@ eval "$(flox activate)" ## SEE ALSO [`flox-deactivate`](/man/flox-deactivate), -[`flox-push`](/man/flox-push), [`flox-pull`](/man/flox-pull), -[`flox-edit`](/man/flox-edit), [`flox-delete`](/man/flox-delete) +[`flox-activate-allow`](/man/flox-activate-allow), +[`flox-activate-deny`](/man/flox-activate-deny), +[`flox-config`](/man/flox-config), [`flox-push`](/man/flox-push), +[`flox-pull`](/man/flox-pull), [`flox-edit`](/man/flox-edit), +[`flox-delete`](/man/flox-delete) diff --git a/man/flox-config.mdx b/man/flox-config.mdx index ed95421..cc8fd38 100644 --- a/man/flox-config.mdx +++ b/man/flox-config.mdx @@ -77,6 +77,30 @@ Silence logs except for errors. ## SUPPORTED CONFIGURATION OPTIONS +`auto_activate` +How auto-activation treats environments you have not yet allowed or +denied, when the `auto_activate` feature flag is enabled. Possible +values are `prompt` (default) and `allowed`. `prompt` asks before +auto-activating an environment the first time you enter its directory. +`allowed` skips the prompt and auto-activates only environments you have +already allowed with `flox activate allow`. See the *AUTO-ACTIVATION* +section of [`flox-activate`](/man/flox-activate). + +`auto_activate_environments` +Per-directory auto-activation decisions. Keys are absolute paths to +directories containing a `.flox` directory, each mapping to `allow` or +`deny`. These are normally written for you by `flox activate allow` and +`flox activate deny` rather than edited by hand. + +`auto_activate_fish_mode` +Controls how the `fish` shell hook responds to directory changes during +auto-activation, mirroring direnv’s `direnv_fish_mode`. Possible values +are `eval_on_arrow` (default), `eval_after_arrow`, and `disable_arrow`. +`eval_on_arrow` evaluates on prompt and immediately when the working +directory changes. `eval_after_arrow` evaluates on prompt and defers +directory-change evaluation until just before the next command runs. +`disable_arrow` evaluates on prompt only, ignoring directory changes. + `config_dir` Directory where Flox should load its configuration file (default: `$XDG_CONFIG_HOME/flox`). This option will only take effect if set with @@ -92,11 +116,18 @@ Directory where Flox should store persistent data (default: `disable_hook` Don’t set up the Flox prompt hook as part of activation. The prompt hook -is required for `flox deactivate` to take effect (default: false). +is required for auto-activation and for `flox deactivate` to take effect +(default: false). `disable_metrics` Disable collecting and sending usage metrics. +`features.auto_activate` +Feature flag that enables auto-activation, which is experimental +(default: false). May also be set with +`FLOX_FEATURES_AUTO_ACTIVATE=true`. See the *AUTO-ACTIVATION* section of +[`flox-activate`](/man/flox-activate). + `floxhub_token` Token to authenticate on FloxHub. @@ -146,8 +177,8 @@ Use 'flox upgrade --dry-run' for details. (default: true) `keep_tempdir` -Flox creates a single tempdir for each process in -`$FLOX_CACHE_HOME/process`. +Flox creates a single tempdir for each process in\ +`$FLOX_CACHE_HOME/process`.\ Flox will delete this tempdir upon conclusion of the process unless `keep_tempdir == true` AND verbose logs are enabled. @@ -157,3 +188,8 @@ Flox will delete this tempdir upon conclusion of the process unless Variable for disabling the collection/sending of metrics data. If set to `true`, prevents Flox from submitting basic metrics information such as a unique token and the subcommand issued. + +`$FLOX_FEATURES_AUTO_ACTIVATE` +Set to `true` to enable auto-activation, which is experimental. +Equivalent to setting `features.auto_activate = true`. See the +*AUTO-ACTIVATION* section of [`flox-activate`](/man/flox-activate). From cde81209b1565a97d0701143d8640270357af300 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 13:31:17 -0700 Subject: [PATCH 2/8] docs: drop synced man pages and their nav entries Man pages under man/ are generated from flox/flox via sync-man-pages.sh, so they (and their docs.json "CLI reference" entries) land with that sync rather than this PR. The auto-activation man pages come from flox/flox#4407. Co-Authored-By: Claude Opus 4.8 (1M context) --- man/flox-activate-allow.mdx | 95 --------------------------------- man/flox-activate-deny.mdx | 100 ---------------------------------- man/flox-activate.mdx | 103 +++++------------------------------- man/flox-config.mdx | 42 ++------------- 4 files changed, 16 insertions(+), 324 deletions(-) delete mode 100644 man/flox-activate-allow.mdx delete mode 100644 man/flox-activate-deny.mdx diff --git a/man/flox-activate-allow.mdx b/man/flox-activate-allow.mdx deleted file mode 100644 index cd03759..0000000 --- a/man/flox-activate-allow.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "flox activate allow" ---- - -## NAME - -flox-activate-allow - allow auto-activation for an environment - -## SYNOPSIS - -```text -flox [] activate allow - [-d= | -r=/ | -D] -``` - -## DESCRIPTION - -> **Experimental:** Auto-activation is experimental and behind a feature -> flag, and its behavior is subject to change. Enable it by setting -> `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment, or by running -> `flox config --set features.auto_activate true`. See the -> *AUTO-ACTIVATION* section of *flox-activate(1)* for details. - -Records that the selected environment may be auto-activated. - -Once an environment is allowed, the Flox prompt hook activates it -automatically whenever you enter a directory containing it, without -prompting. The preference is stored in the user config file under -`auto_activate_environments`, keyed by the absolute path of the -directory that contains the `.flox` directory. - -By default `flox activate allow` targets the environment in the current -directory. Use the environment options below to target a different -environment. - -To stop an environment from being auto-activated, run -[`flox-activate-deny`](/man/flox-activate-deny). - -See the *AUTO-ACTIVATION* section of -[`flox-activate`](/man/flox-activate) for the full picture, including -the consent prompt and how to enable the feature. - -## OPTIONS - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--reference` -A FloxHub environment, specified in the form `/`. - -`-D`, `--default` -Use your default environment (`/default`). When -unauthenticated in an interactive context, you will be prompted to log -in. In non-interactive contexts (e.g., scripts or CI), this flag will -fail with an error when authentication is missing. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES - -Allow auto-activation for the environment in the current directory: - -```bash -flox activate allow -``` - -Allow auto-activation for an environment in another directory: - -```bash -flox activate allow -d /path/to/project -``` - -## SEE ALSO - -[`flox-activate`](/man/flox-activate), -[`flox-activate-deny`](/man/flox-activate-deny), -[`flox-config`](/man/flox-config) diff --git a/man/flox-activate-deny.mdx b/man/flox-activate-deny.mdx deleted file mode 100644 index 7d89d40..0000000 --- a/man/flox-activate-deny.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "flox activate deny" ---- - -## NAME - -flox-activate-deny - deny auto-activation for an environment - -## SYNOPSIS - -```text -flox [] activate deny - [-d= | -r=/ | -D] -``` - -## DESCRIPTION - -> **Experimental:** Auto-activation is experimental and behind a feature -> flag, and its behavior is subject to change. Enable it by setting -> `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment, or by running -> `flox config --set features.auto_activate true`. See the -> *AUTO-ACTIVATION* section of *flox-activate(1)* for details. - -Records that the selected environment must not be auto-activated. - -Once an environment is denied, the Flox prompt hook skips it silently -when you enter a directory containing it, and you are no longer prompted -for it. The preference is stored in the user config file under -`auto_activate_environments`, keyed by the absolute path of the -directory that contains the `.flox` directory. - -Denying an environment does not deactivate it if it is already active; -it only prevents future auto-activation. Run -[`flox-deactivate`](/man/flox-deactivate) to leave an environment -that is currently active. - -By default `flox activate deny` targets the environment in the current -directory. Use the environment options below to target a different -environment. - -To allow an environment to be auto-activated again, run -[`flox-activate-allow`](/man/flox-activate-allow). - -See the *AUTO-ACTIVATION* section of -[`flox-activate`](/man/flox-activate) for the full picture, including -the consent prompt and how to enable the feature. - -## OPTIONS - -### Environment Options - -If no environment is specified for an environment command, the -environment in the current directory or the active environment that was -last activated is used. - -`-d`, `--dir` -Path containing a .flox/ directory. - -`-r`, `--reference` -A FloxHub environment, specified in the form `/`. - -`-D`, `--default` -Use your default environment (`/default`). When -unauthenticated in an interactive context, you will be prompted to log -in. In non-interactive contexts (e.g., scripts or CI), this flag will -fail with an error when authentication is missing. - -### General Options - -`-h`, `--help` -Prints help information. - -The following options can be passed when running any `flox` subcommand -but must be specified *before* the subcommand. - -`-v`, `--verbose` -Increase logging verbosity. Invoke multiple times for increasing detail. - -`-q`, `--quiet` -Silence logs except for errors. - -## EXAMPLES - -Deny auto-activation for the environment in the current directory: - -```bash -flox activate deny -``` - -Stop being prompted for an environment in another directory: - -```bash -flox activate deny -d /path/to/project -``` - -## SEE ALSO - -[`flox-activate`](/man/flox-activate), -[`flox-activate-allow`](/man/flox-activate-allow), -[`flox-config`](/man/flox-config) diff --git a/man/flox-activate.mdx b/man/flox-activate.mdx index ff10be9..058c76a 100644 --- a/man/flox-activate.mdx +++ b/man/flox-activate.mdx @@ -30,20 +30,20 @@ Configures a shell with everything defined by the environment: `flox activate` may run in one of four modes: -- interactive: `flox activate` when invoked from an interactive shell\ +- interactive: `flox activate` when invoked from an interactive shell Launches an interactive sub-shell. The shell to be launched is determined by `$FLOX_SHELL` or `$SHELL`. -- shell command: `flox activate -c CMD`\ +- shell command: `flox activate -c CMD` Runs `CMD` in the same environment as if run inside an interactive shell produced by an interactive `flox activate`. The shell `CMD` is run by is determined by `$FLOX_SHELL` or `$SHELL`. Because `CMD` is passed to a shell, shell features like running multiple commands with `&&` can be used. -- exec command: `flox activate -- CMD`\ +- exec command: `flox activate -- CMD` Execs `CMD` directly after performing all parts of activation except for running scripts in `[profile]`. - in-place: `flox activate` when invoked from a non-interactive shell - with its `stdout` redirected e.g. `eval "$(flox activate)"`\ + with its `stdout` redirected e.g. `eval "$(flox activate)"` Produces commands to be sourced by the parent shell. Flox will determine the parent shell from `$FLOX_SHELL` or otherwise automatically determine the parent shell and fall back to `$SHELL`. @@ -71,78 +71,6 @@ To reverse activation, run [`flox-deactivate`](/man/flox-deactivate). Inside a `flox activate` subshell, `flox deactivate` is equivalent to `exit`. -## AUTO-ACTIVATION - -> **Experimental:** Auto-activation is experimental and behind a feature -> flag, and its behavior is subject to change. Enable it by setting -> `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment, or by running -> `flox config --set features.auto_activate true`. See the -> *AUTO-ACTIVATION* section of *flox-activate(1)* for details. - -Auto-activation activates an environment automatically when you enter a -directory that contains it, and deactivates it when you leave, so you do -not have to run `flox activate` by hand. - -### Enabling auto-activation - -Two things are required: - -1. The Flox prompt hook must be installed in your shell. The hook is - installed by any in-place activation, so add a line such as - `eval "$(flox activate -D)"` to your shell’s startup file (for - example `~/.bashrc`, `~/.zshrc`, `~/.config/fish/config.fish`, or - `~/.tcshrc`). If you already activate a default or other environment - in-place at startup, the hook is already installed. The hook ships - with Flox and stays dormant until the feature flag below is set. Set - `disable_hook = true` to opt out of the hook entirely. -2. The `auto_activate` feature flag must be enabled, either with - `FLOX_FEATURES_AUTO_ACTIVATE=true` in your environment or with - `flox config --set features.auto_activate true`. - -`bash`, `zsh`, `fish`, and `tcsh` are supported. - -### How it works - -On each prompt the hook looks for `.flox` environments at or above the -current directory. An environment is auto-activated only if you have -allowed it. Allowed environments are activated outermost-first; when you -leave their directory they are deactivated again. Services are not -started unless `services.auto-start = true` is set in the manifest. - -### Allowing and denying environments - -The first time you enter a directory with an environment that you have -neither allowed nor denied, and `auto_activate` is set to `prompt` (the -default), Flox asks before activating it: - -```text -Auto-activate the environment in '/path/to/project'? [y/N] -``` - -Answering `y` allows the environment and activates it immediately, and -records the choice so you are not asked again. Answering `N` (or -pressing Enter) skips the environment for the current shell session -only; you are asked again in a new shell or when you re-enter the -directory. To stop being asked for a directory, run -[`flox-activate-deny`](/man/flox-activate-deny): - -```bash -flox activate deny --dir /path/to/project -``` - -Set the `auto_activate` config option to `allowed` to skip the prompt -entirely and auto-activate only environments you have already allowed. - -Manage these decisions ahead of time with the -[`flox-activate-allow`](/man/flox-activate-allow) and -[`flox-activate-deny`](/man/flox-activate-deny) subcommands. -Decisions are stored in the user config file under -`auto_activate_environments`. - -See [`flox-config`](/man/flox-config) for the `auto_activate`, -`auto_activate_environments`, `auto_activate_fish_mode`, and -`disable_hook` options. - ## OPTIONS ### Activate Options @@ -278,15 +206,13 @@ emit commands to configure an already-running (parent) shell. In both of these cases Flox needs to know which shell to use, and these variables are used to control the selection process. - * interactive and command modes: When launching a sub-shell - Flox will invoke - the shell specified in `$FLOX_SHELL` if set - or fall back to invoke `$SHELL` by default. - * in-place mode: When performing an "in place" activation - Flox will attempt to detect its parent shell type unless overridden by - the `$FLOX_SHELL` variable, - and if it cannot detect its parent shell type then will - produce a script with syntax determined by `$SHELL`. +- interactive and command modes: When launching a sub-shell Flox will + invoke the shell specified in `$FLOX_SHELL` if set or fall back to + invoke `$SHELL` by default. +- in-place mode: When performing an “in place” activation Flox will + attempt to detect its parent shell type unless overridden by the + `$FLOX_SHELL` variable, and if it cannot detect its parent shell type + then will produce a script with syntax determined by `$SHELL`. `$FLOX_PROMPT_COLOR_{1,2}` Flox adds text to the beginning of the shell prompt to indicate which @@ -328,8 +254,5 @@ eval "$(flox activate)" ## SEE ALSO [`flox-deactivate`](/man/flox-deactivate), -[`flox-activate-allow`](/man/flox-activate-allow), -[`flox-activate-deny`](/man/flox-activate-deny), -[`flox-config`](/man/flox-config), [`flox-push`](/man/flox-push), -[`flox-pull`](/man/flox-pull), [`flox-edit`](/man/flox-edit), -[`flox-delete`](/man/flox-delete) +[`flox-push`](/man/flox-push), [`flox-pull`](/man/flox-pull), +[`flox-edit`](/man/flox-edit), [`flox-delete`](/man/flox-delete) diff --git a/man/flox-config.mdx b/man/flox-config.mdx index cc8fd38..ed95421 100644 --- a/man/flox-config.mdx +++ b/man/flox-config.mdx @@ -77,30 +77,6 @@ Silence logs except for errors. ## SUPPORTED CONFIGURATION OPTIONS -`auto_activate` -How auto-activation treats environments you have not yet allowed or -denied, when the `auto_activate` feature flag is enabled. Possible -values are `prompt` (default) and `allowed`. `prompt` asks before -auto-activating an environment the first time you enter its directory. -`allowed` skips the prompt and auto-activates only environments you have -already allowed with `flox activate allow`. See the *AUTO-ACTIVATION* -section of [`flox-activate`](/man/flox-activate). - -`auto_activate_environments` -Per-directory auto-activation decisions. Keys are absolute paths to -directories containing a `.flox` directory, each mapping to `allow` or -`deny`. These are normally written for you by `flox activate allow` and -`flox activate deny` rather than edited by hand. - -`auto_activate_fish_mode` -Controls how the `fish` shell hook responds to directory changes during -auto-activation, mirroring direnv’s `direnv_fish_mode`. Possible values -are `eval_on_arrow` (default), `eval_after_arrow`, and `disable_arrow`. -`eval_on_arrow` evaluates on prompt and immediately when the working -directory changes. `eval_after_arrow` evaluates on prompt and defers -directory-change evaluation until just before the next command runs. -`disable_arrow` evaluates on prompt only, ignoring directory changes. - `config_dir` Directory where Flox should load its configuration file (default: `$XDG_CONFIG_HOME/flox`). This option will only take effect if set with @@ -116,18 +92,11 @@ Directory where Flox should store persistent data (default: `disable_hook` Don’t set up the Flox prompt hook as part of activation. The prompt hook -is required for auto-activation and for `flox deactivate` to take effect -(default: false). +is required for `flox deactivate` to take effect (default: false). `disable_metrics` Disable collecting and sending usage metrics. -`features.auto_activate` -Feature flag that enables auto-activation, which is experimental -(default: false). May also be set with -`FLOX_FEATURES_AUTO_ACTIVATE=true`. See the *AUTO-ACTIVATION* section of -[`flox-activate`](/man/flox-activate). - `floxhub_token` Token to authenticate on FloxHub. @@ -177,8 +146,8 @@ Use 'flox upgrade --dry-run' for details. (default: true) `keep_tempdir` -Flox creates a single tempdir for each process in\ -`$FLOX_CACHE_HOME/process`.\ +Flox creates a single tempdir for each process in +`$FLOX_CACHE_HOME/process`. Flox will delete this tempdir upon conclusion of the process unless `keep_tempdir == true` AND verbose logs are enabled. @@ -188,8 +157,3 @@ Flox will delete this tempdir upon conclusion of the process unless Variable for disabling the collection/sending of metrics data. If set to `true`, prevents Flox from submitting basic metrics information such as a unique token and the subcommand issued. - -`$FLOX_FEATURES_AUTO_ACTIVATE` -Set to `true` to enable auto-activation, which is experimental. -Equivalent to setting `features.auto_activate = true`. See the -*AUTO-ACTIVATION* section of [`flox-activate`](/man/flox-activate). From 0ff56ffa3472ddd6310462e5eace457e98fdd7a9 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 13:31:48 -0700 Subject: [PATCH 3/8] docs: remove the auto-activation man pages from the nav These man pages are synced from flox/flox; their nav entries belong with that sync. The hand-authored concepts/auto-activation entry stays. docs.json is not auto-updated by the sync, so nav entries are maintained by hand (see AGENTS.md). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs.json | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs.json b/docs.json index 9e16ce4..e29a212 100644 --- a/docs.json +++ b/docs.json @@ -179,8 +179,6 @@ "group": "Environments", "pages": [ "man/flox-activate", - "man/flox-activate-allow", - "man/flox-activate-deny", "man/flox-edit", "man/flox-delete", "man/flox-envs" From 75c93e84e12d10f8bdb9fb00efc910b90feded49 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 13:32:13 -0700 Subject: [PATCH 4/8] docs(auto-activation): drop the redundant supported-shells line Co-Authored-By: Claude Opus 4.8 (1M context) --- concepts/auto-activation.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/concepts/auto-activation.mdx b/concepts/auto-activation.mdx index 143e625..165845e 100644 --- a/concepts/auto-activation.mdx +++ b/concepts/auto-activation.mdx @@ -84,8 +84,6 @@ file: enabling and disabling the flag is enough to turn auto-activation on and off. -`bash`, `zsh`, `fish`, and `tcsh` are supported. - ## How it works Once the hook is installed and the feature flag is on, the hook runs on every From c9cab4e904309ab66295f801dd5330b457915271 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 13:32:25 -0700 Subject: [PATCH 5/8] docs(auto-activation): allow/deny only accept the -d selector Co-Authored-By: Claude Opus 4.8 (1M context) --- concepts/auto-activation.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/concepts/auto-activation.mdx b/concepts/auto-activation.mdx index 165845e..c6e2a66 100644 --- a/concepts/auto-activation.mdx +++ b/concepts/auto-activation.mdx @@ -154,8 +154,8 @@ flox activate allow flox activate deny ``` -Both target the environment in the current directory by default; pass `-d`, -`-r`, or `-D` to target another environment. +Both target the environment in the current directory by default; pass `-d` +to target another environment. To stop being prompted for a specific directory: ```bash From d6d415d68398eb1dd74adbaf400d3180f6d1b8d0 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 13:32:36 -0700 Subject: [PATCH 6/8] docs(auto-activation): use the -d form in the deny example Co-Authored-By: Claude Opus 4.8 (1M context) --- concepts/auto-activation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/auto-activation.mdx b/concepts/auto-activation.mdx index c6e2a66..d13c994 100644 --- a/concepts/auto-activation.mdx +++ b/concepts/auto-activation.mdx @@ -159,7 +159,7 @@ to target another environment. To stop being prompted for a specific directory: ```bash -flox activate deny --dir /path/to/project +flox activate deny -d /path/to/project ``` Decisions are stored in your Flox config (`~/.config/flox/flox.toml`) under From 93f273ff4f1d1f7e3f83aea762a69ce07254089a Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 13:32:58 -0700 Subject: [PATCH 7/8] docs(auto-activation): clarify deactivation in the comparison table Co-Authored-By: Claude Opus 4.8 (1M context) --- concepts/auto-activation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/auto-activation.mdx b/concepts/auto-activation.mdx index d13c994..b730f0e 100644 --- a/concepts/auto-activation.mdx +++ b/concepts/auto-activation.mdx @@ -218,7 +218,7 @@ environment variables, and hooks — but differ in a few ways: | --- | --- | --- | | **Trigger** | Explicit `flox activate` command | Automatic on `cd` into a `.flox` directory | | **Gate** | None — you chose to activate | Requires the feature flag and an allowed environment | -| **Deactivation** | `flox deactivate` or `exit` (subshell) | `flox deactivate` | +| **Deactivation** | `flox deactivate` or `exit` (subshell) | `flox deactivate` (all auto-activated environments are in-place activations) | | **Failure** | Activation aborts on failure | A failed activation aborts; other layers still activate | See [Activating environments](/concepts/activation) for how activation works in From 5dbf1a56e8caf1c85b94d9a74fc9cecc9600ec16 Mon Sep 17 00:00:00 2001 From: Daniel Sauble Date: Thu, 18 Jun 2026 13:33:21 -0700 Subject: [PATCH 8/8] docs(auto-activation): note hierarchy activation in the comparison table Co-Authored-By: Claude Opus 4.8 (1M context) --- concepts/auto-activation.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/concepts/auto-activation.mdx b/concepts/auto-activation.mdx index b730f0e..85a4fa9 100644 --- a/concepts/auto-activation.mdx +++ b/concepts/auto-activation.mdx @@ -217,6 +217,7 @@ environment variables, and hooks — but differ in a few ways: | Behavior | `flox activate` (manual) | Auto-activation | | --- | --- | --- | | **Trigger** | Explicit `flox activate` command | Automatic on `cd` into a `.flox` directory | +| **Scope** | Activates one environment per command | Activates a whole hierarchy of nested environments at once | | **Gate** | None — you chose to activate | Requires the feature flag and an allowed environment | | **Deactivation** | `flox deactivate` or `exit` (subshell) | `flox deactivate` (all auto-activated environments are in-place activations) | | **Failure** | Activation aborts on failure | A failed activation aborts; other layers still activate |