REFERENCE / CLI CHEAT SHEET

CLI cheat sheet

The Flox commands a customer actually types, grouped the way flox --help groups them: manage, use, discover, modify, share, administer. Each row gives what the command does, the flags worth knowing, one example and the man page it came from. The last sections list the documented environment variables and config keys, and the exact non-interactive forms that are safe in scripts and AI agents.

How to read this page

The --help grouping in the top-level man page is “local development, sharing environments, and administration” (https://flox.dev/docs/man/flox). The tables below split local development into manage, use, discover and modify so each table fits on a screen.
Environment commands take -d <path> for a directory, -r <owner>/<name> for a FloxHub environment, and -D for your default environment. With none of them, “the environment in the current directory or the active environment that was last activated is used” (https://flox.dev/docs/man/flox-install).
General options such as -v and -q “must be specified before the subcommand” (https://flox.dev/docs/man/flox).

Manage environments

Command	What it does	Useful flags	Example	Man page
`flox init`	Creates a new empty environment in the current directory or on FloxHub; a `.flox` directory holds the metadata.	`-n <name>`, `-d <path>`, `--bare`, `--auto-setup`, `-r <owner>/<name>`	`flox init`	https://flox.dev/docs/man/flox-init
`flox envs`	Lists environments known to the local registry; the last activated one is listed first.	`--active`, `--json`	`flox envs --active`	https://flox.dev/docs/man/flox-envs
`flox delete`	Deletes all data for an environment; prompts first.	`-f` (skips the prompt, “required for non-interactive use”), `-d`	`flox delete -f -d ./old-env`	https://flox.dev/docs/man/flox-delete
`flox list`	Lists packages installed in an environment.	`-n`, `-e`, `-a` (increasing detail), `-c`, `-u`	`flox list -a`	https://flox.dev/docs/man/flox-list
`flox generations list`	Shows every generation you can switch to and which is live.	`--tree`, `--json`, `--no-pager`	`flox generations list -r acme/platform`	https://flox.dev/docs/man/flox-generations-list
`flox generations rollback`	Moves a FloxHub environment back one generation.	`-d`, `-r`	`flox generations rollback -r acme/platform`	https://flox.dev/docs/man/flox-generations-rollback
`flox generations switch`	Switches to a named generation.	`<generation>`, `-d`, `-r`	`flox generations switch 3 -r acme/platform`	https://flox.dev/docs/man/flox-generations-switch
`flox generations history`	Prints the change history of an environment.	`--json`, `-u`	`flox generations history --no-pager`	https://flox.dev/docs/man/flox-generations-history

Generations apply to environments on FloxHub: “every modification to the environment creates a new generation of the environment” (https://flox.dev/docs/man/flox-generations-list).

Use environments

Command	What it does	Useful flags	Example	Man page
`flox activate`	Configures a shell with the environment: packages on `$PATH`, variables, aliases, hooks, and optionally services. Has four modes: interactive, shell command, exec command and in-place.	`-c <cmd>`, `-- <cmd>`, `-r <owner>/<name>`, `-s`, `-m dev\|run`, `-g <generation>`, `-t`	`flox activate -r some_user/myenv`	https://flox.dev/docs/man/flox-activate
`flox deactivate`	Leaves the innermost active environment; inside a `flox activate` subshell it is equivalent to `exit`.	none	`flox deactivate`	https://flox.dev/docs/man/flox-deactivate
`flox run`	Runs a command from a Flox Catalog package without installing it.	`-p <package>`, `--reselect`	`flox run -p cowsay -- cowsay "Hello, Flox!"`	https://flox.dev/docs/man/flox-run
`flox services start`	Starts services declared in the manifest, one by name or all.	`<name>...`, `-d`, `-r`	`flox services start server`	https://flox.dev/docs/man/flox-services-start
`flox services stop`	Stops a named service or all running services.	`<name>...`	`flox services stop`	https://flox.dev/docs/man/flox-services-stop
`flox services restart`	Restarts a named service or all.	`<name>...`	`flox services restart myservice`	https://flox.dev/docs/man/flox-services-restart
`flox services status`	Shows name, status and PID per service.	`--json`	`flox services status myservice`	https://flox.dev/docs/man/flox-services-status
`flox services logs`	Shows service logs.	`--follow`, `-n <num>`	`flox services logs --follow service1 service3`	https://flox.dev/docs/man/flox-services-logs
`flox develop`	Enters a development shell for a Nix expression build, used to iterate on a failing build.	`-c <cmd>`, `--stability`, `-d`	`flox develop hello`	https://flox.dev/docs/man/flox-develop

Activating an environment from its cached lockfile “does not require a FloxHub account”; activating a private remote environment with -r requires login (https://flox.dev/docs/man/flox-activate). flox run fetches “by store path using substitution only” and does not yet support version constraints such as curl@8.0 (https://flox.dev/docs/man/flox-run).

Discover packages

Command	What it does	Useful flags	Example	Man page
`flox search`	Fuzzy search of the Flox Catalog by pkg-path or description. Needs no FloxHub account.	`-a` (all results, default at most 10), `--json`	`flox search ripgrep --json`	https://flox.dev/docs/man/flox-search
`flox show`	Shows description, outputs (defaults marked `*`) and available versions of one package. Needs no account.	`<pkg-path>`	`flox show ripgrep`	https://flox.dev/docs/man/flox-show

Modify environments

Command	What it does	Useful flags	Example	Man page
`flox install`	Adds packages transactionally: the environment is built first, and if the build fails it is left unmodified. Needs a free FloxHub account.	`<pkg>@<version>`, `<pkg>^<outputs>`, `-i <id>`, `-d`, `-r`	`flox install ripgrep`	https://flox.dev/docs/man/flox-install
`flox uninstall` (alias `rm`)	Removes packages.	`-d`, `-r`	`flox uninstall ripgrep`	https://flox.dev/docs/man/flox-uninstall
`flox edit`	Edits the manifest transactionally; the environment is rebuilt to validate the edit.	`-f <file>` (non-interactive, `-` reads stdin), `-n <name>`, `--sync`, `--reset`	`flox edit -f manifest.toml`	https://flox.dev/docs/man/flox-edit
`flox upgrade`	Upgrades packages, or one package group such as `toplevel`.	`--dry-run`, `-d`, `-r`	`flox upgrade --dry-run`	https://flox.dev/docs/man/flox-upgrade
`flox include upgrade`	Upgrades included (composed) environments.	`<included environment>...`	`flox include upgrade`	https://flox.dev/docs/man/flox-include-upgrade
`flox build`	Builds a package defined under `[build]` in the manifest; output lands at `result-<package>`.	`<package>...`, `-d`, `--stability`	`flox build hello`	https://flox.dev/docs/man/flox-build
`flox build clean`	Removes build artifacts.	`<package>...`	`flox build clean`	https://flox.dev/docs/man/flox-build-clean
`flox build import-nixpkgs`	Writes `.flox/pkgs/<name>/default.nix` from a nixpkgs package.	`--force`, `--stability`	`flox build import-nixpkgs hello`	https://flox.dev/docs/man/flox-build-import-nixpkgs
`flox build update-catalogs`	Updates catalog references for Nix expression builds.	`-d`	`flox build update-catalogs`	https://flox.dev/docs/man/flox-build-update-catalogs
`flox containerize`	Exports the environment as a container image, to a runtime, a file or stdout.	`-f <file>`, `--runtime`, `--tag`, `--label`, `-m dev\|run`	`flox containerize --runtime docker`	https://flox.dev/docs/man/flox-containerize

Install IDs default to the last attribute of the pkg-path, so python310Packages.pip becomes pip (https://flox.dev/docs/man/flox-install). The field reference for everything flox edit can change is https://flox.dev/docs/man/manifest.toml.

Command	What it does	Useful flags	Example	Man page
`flox push`	Sends an environment to FloxHub, or syncs local changes to a remote one; afterwards it is `<owner>/<name>`.	`-o <owner>` (first push only), `-r`, `-f` (overwrite FloxHub)	`flox push`	https://flox.dev/docs/man/flox-push
`flox pull`	Pulls an environment from FloxHub into a directory, or updates an existing one.	`<owner>/<name>`, `-c` (copy), `-g <generation>`, `-f`	`flox pull acme/platform`	https://flox.dev/docs/man/flox-pull
`flox publish`	Uploads package metadata and copies the package so it is available in the Flox Catalog. Requires a clean, pushed git repo.	`-o <org>`, `--signing-private-key <path>`, `--stability`	`flox publish hello`	https://flox.dev/docs/man/flox-publish

Push conflicts behave like git: running flox push from a different host may diverge, and “Passing --force” overwrites FloxHub with the local copy (https://flox.dev/docs/man/flox-push).

Administration

Command	What it does	Useful flags	Example	Man page
`flox auth`	FloxHub authentication: `login`, `logout`, `status`, `token`.	`login --token-file <path>`	`flox auth status`	https://flox.dev/docs/man/flox-auth
`flox config`	Views and sets configuration.	`-l`, `-r`, `--set <key> <value>`, `--delete <key>`	`flox config --set auth_notifications false`	https://flox.dev/docs/man/flox-config
`flox gc`	Garbage collects data for deleted environments and runs garbage collection on the Nix store.	none	`flox gc`	https://flox.dev/docs/man/flox-gc

Environment variables the man pages document

Variable	What it does	Source
`$FLOX_DISABLE_METRICS`	If `true`, Flox does not submit basic metrics such as a token and the subcommand issued.	https://flox.dev/docs/man/flox
`$FLOX_MAX_PARALLEL_DOWNLOADS`	Limits parallel package downloads (default is all in parallel); set to 1 or more on poor connections.	https://flox.dev/docs/man/flox
`$EDITOR`, `$VISUAL`	Override the editor used for manifests and commit messages.	https://flox.dev/docs/man/flox
`$NIX_SSL_CERT_FILE`, `$SSL_CERT_FILE`	TLS bundles; Flox never sets `SSL_CERT_FILE`, and sets `NIX_SSL_CERT_FILE` to its shipped bundle only if neither is set.	https://flox.dev/docs/man/flox
`$FLOX_SHELL`, `$SHELL`	Choose the shell for interactive, `-c` and in-place activation.	https://flox.dev/docs/man/flox-activate
`$FLOX_CONFIG_DIR`	Directory holding `flox.toml`, the user config file.	https://flox.dev/docs/man/flox-config

Config keys the man page documents

Set with flox config --set <key> <value> (https://flox.dev/docs/man/flox-config).

Key	Meaning
`auto_activate`	`prompt` (default), `allowlist` or `disabled`.
`auto_activate_environments`	Per-directory `allow` or `deny`; glob keys with `` and `*` are allowed.
`disable_hook`	Skips the prompt hook; this also disables auto-activation and `flox deactivate` (default: false).
`disable_metrics`	Disables usage metrics.
`floxhub_token`	Token to authenticate on FloxHub.
`search_limit`	How many items `flox search` shows by default.
`set_prompt`, `hide_default_prompt`	Control the shell prompt.
`trusted_environments`	Keys `"<owner>/<name>"` or `"<owner>/*"`, values `trust` or `deny`.
`upgrade_notifications`, `auth_notifications`	Advisory messages, default true.
`installer_channel`	`stable` (default), `nightly` or `qa`.

All of these come from https://flox.dev/docs/man/flox-config.

Safe in scripts and agents

The Flox docs index tells AI coding assistants: “Do not run bare flox activate.” It names two non-interactive forms (https://flox.dev/docs/llms.txt):

flox activate -d <dir> -c '<command>'   # hooks and profile scripts applied; the preferred form
flox activate -d <dir> -- <command>     # exec mode; does not run profile scripts

The same source says of the first form: “Prefer this form.” and of the second that it “replaces the process and does not run profile scripts” (https://flox.dev/docs/llms.txt).
Do not run bare flox edit. Use flox edit -d <dir> -f <file> to replace the manifest non-interactively (https://flox.dev/docs/llms.txt, https://flox.dev/docs/man/flox-edit).
After a direct edit of a pushed or pulled environment’s manifest, flox install, flox uninstall, flox edit and flox upgrade are blocked until flox edit --sync or flox edit --reset (https://flox.dev/docs/llms.txt).
flox delete -f is the only non-interactive delete (https://flox.dev/docs/man/flox-delete).
CI login: flox auth login --token-file <path> reads a JWT, personal access token or service account token, and with - reads stdin. The man page says “Use this in CI, containers, and other scripted setups.” (https://flox.dev/docs/man/flox-auth).
flox install and flox edit resolve packages from the Flox Catalog, which needs a free FloxHub account; in CI “supply a token instead” (https://flox.dev/docs/man/flox-install, https://go.flox.dev/auth).
With -D, “In non-interactive contexts (e.g., scripts or CI), this flag will fail with an error when authentication is missing” (https://flox.dev/docs/man/flox-install).
Check pkg-paths with flox search and flox show instead of guessing, because catalog names do not always match nixpkgs attribute paths (https://flox.dev/docs/llms.txt).
Flox keeps a skill library for coding agents at https://github.com/flox/flox-skills, with skills flox, floxify and flox-debug (https://flox.dev/docs/llms.txt).

Say: agents never run bare flox activate; they use -c or --. Ask: does your CI have a service account token, or a personal one? The man page accepts either (https://flox.dev/docs/man/flox-auth).

← POC and demo scripts · FAQ quickfire →