CLI, services, CI and tokens

Day to day Flox is a handful of commands against a manifest, with services and auto-activation layered on. For machines, FloxHub issues service account tokens and personal access tokens that the CLI reads from FLOX_FLOXHUB_TOKEN. A free-account requirement for package resolution is the main automation change to plan around.

This page is drawn from https://flox.dev/docs/man/flox, https://flox.dev/docs/man/flox-activate, https://flox.dev/docs/concepts/services, https://flox.dev/docs/concepts/auto-activation, https://flox.dev/docs/concepts/generations, https://flox.dev/docs/concepts/authentication, https://flox.dev/docs/concepts/service-accounts, https://flox.dev/docs/concepts/personal-access-tokens, https://flox.dev/docs/tutorials/ci-cd, https://flox.dev/docs/changelog, https://flox.dev/blog/flox-account-tokens-for-people-and-machines/, https://flox.dev/blog/making-flox-better-for-people-and-machines/ and https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/.

Everyday commands

The CLI groups its commands into local development, sharing and administration (https://flox.dev/docs/man/flox).

Say: “The manifest is the product. Every command is a way to edit it and lock the result.” (the manifest and lock are described at https://flox.dev/docs/concepts/environments).

Services

Services are long-running programs defined in the [services] table of the manifest, each with a command, optional per-service vars, and ordering against other services (https://flox.dev/docs/concepts/services). The docs’ example is a PostgreSQL service configured through environment variables (https://flox.dev/docs/concepts/services).

• Start with the environment: flox activate -s starts the manifest’s services, and they are “cleaned up once the last activation of this environment terminates” (https://flox.dev/docs/man/flox-activate).
• Start by default: set services.auto-start = true (https://flox.dev/docs/man/flox-activate).
• Manage: flox services start, stop, restart, status and logs each have a man page (https://flox.dev/docs/man/flox-services-start).
• Stopping: the default is SIGTERM, with no escalation to SIGKILL unless you set shutdown.timeout-seconds (https://flox.dev/docs/concepts/services). A service that forks a daemon needs is-daemon = true and a shutdown.command (https://flox.dev/docs/concepts/services).

Auto-activation and direnv

Auto-activation activates an environment when you cd into a directory containing .flox, and deactivates it when you leave (https://flox.dev/docs/concepts/auto-activation). It is on by default and needs the Flox prompt hook, which any in-place flox activate installs, for example eval "$(flox activate -D)" in ~/.bashrc (https://flox.dev/docs/concepts/auto-activation).

Safety: “An environment is never auto-activated until you have allowed it.” The first visit prompts [y/N], and flox activate allow or deny records a decision ahead of time (https://flox.dev/docs/concepts/auto-activation). Services are not started unless services.auto-start = true (https://flox.dev/docs/concepts/auto-activation). Flox announced the feature on 2026-07-29 and said people had been “hacking direnv” to get this behavior (https://flox.dev/blog/auto-activation-is-now-native-in-flox/).

direnv still works: with use flox in .envrc the activation is in-place and both hook.on-activate and [profile] scripts run (https://flox.dev/docs/concepts/activation).

CI

The docs’ pitch: “the exact same set of software can be used for local development and a CI/CD pipeline” (https://flox.dev/docs/tutorials/ci-cd).

A pipeline that only uses an environment committed to the repository “needs no credentials at all”; credentials are needed to pull a FloxHub environment, install from a private catalog, or publish (https://flox.dev/docs/tutorials/ci-cd). The CI blog (2024-09-26) shows the floxdocs repo validating its own environment in CI (https://flox.dev/blog/integrating-flox-with-ci-for-consistent-reproducible-dev-environments/).

Tokens for people and machines

Both need Flox CLI 1.14.0 or newer (https://flox.dev/docs/concepts/service-accounts). Lifetimes on offer are 30 days (default), 90 days, 1 year or no expiration, and a token is shown once (https://flox.dev/docs/concepts/service-accounts). A service account “is never an organization owner”, so it cannot create more service accounts, and its access “cannot be narrowed to a subset of environments or packages” (https://flox.dev/docs/concepts/service-accounts). More than one live token can exist, so rotation needs no maintenance window (https://flox.dev/blog/flox-account-tokens-for-people-and-machines/, 2026-08-03).

Use in CI: put the token in FLOX_FLOXHUB_TOKEN and the CLI reads it without a login step (https://flox.dev/docs/tutorials/ci-cd). Without a browser, flox auth login --token-file <path> accepts a personal access token or service account token (https://flox.dev/docs/man/flox-auth). A read-only service account cannot push or publish, so a leaked CI token “cannot be used to change what the rest of the team installs” (https://flox.dev/docs/tutorials/ci-cd).

The August 2026 post says the new credentials help protect the service “from abusive or runaway automation”, and that FloxHub sign-up is “completely free” (https://flox.dev/blog/making-flox-better-for-people-and-machines/, 2026-08-13).

The free-account requirement

The authentication page says that “Starting Tuesday, October 20, 2026”, commands that resolve packages need a free Flox account, arriving with Flox 1.19.3 (https://flox.dev/docs/concepts/authentication). I did not find 1.19.3 in the changelog I read, so treat the version as the docs’ claim [verify] (https://flox.dev/docs/changelog). Per the same page, these stay open: flox search, flox show, flox activate with a current lockfile, and flox build with a current lockfile (https://flox.dev/docs/concepts/authentication). flox install, flox upgrade and flox run need sign-in (https://flox.dev/docs/concepts/authentication). It states: “this is not a paywall” (https://flox.dev/docs/concepts/authentication).

Ask: “Does CI install or upgrade packages on each run, or only activate a committed lockfile?” Per the page, the first needs a token and the second needs nothing (https://flox.dev/docs/concepts/authentication).

FLOX_* variables

Generations

A generation is a “version number of an environment” on FloxHub, created by flox push (generation 1) and by every command that modifies the environment (https://flox.dev/docs/concepts/generations). flox generations list shows versions, switch <number> goes to one, rollback undoes the last change, and history shows which generation was live when (https://flox.dev/docs/concepts/generations). Rolling back “doesn’t create a new generation” but adds a history entry (https://flox.dev/docs/concepts/generations).

Upgrades and the changelog

Upgrading the CLI uses your package manager, for example brew upgrade flox on macOS with Homebrew (https://flox.dev/docs/install-flox/install). The 2026 changelog lists, newest first, v1.18.2 (October 14), v1.18.1 (October 7) and v1.18.0 (October 6) (https://flox.dev/docs/changelog). v1.18.2 “updates the bundled Nix to 2.31.6” for a Nix privilege escalation advisory, and the page says all releases before 1.18.2 are affected (https://flox.dev/docs/changelog). That is the line to cite when a customer asks why they should upgrade a fleet.