devenv CLI Reference: All Commands, Flags, and Options

The devenv command-line interface is the primary way to interact with your developer environment. It provides subcommands for creating and activating environments, managing processes and tasks, building containers, searching packages, and more. All global flags can be mixed with any subcommand.

$ devenv --help
https://devenv.sh 2.0.0: Fast, Declarative, Reproducible, and Composable Developer Environments

Usage: devenv [OPTIONS] [COMMAND]

Global Flags

Global flags can be used with any subcommand and control overarching behaviors such as Nix evaluation, environment hermeticity, output format, and the terminal UI.

Input overrides

These flags let you override the source of devenv.nix and individual inputs without editing devenv.yaml.

Flag	Description
`--from <FROM>`	Source for `devenv.nix`. Can be a flake reference (`github:org/repo`) or local path (`path:./dir`).
`-o, --override-input <NAME> <URI>`	Override a named input from `devenv.yaml`. Repeatable.
`-O, --option <OPTION:TYPE> <VALUE>`	Override a `devenv.nix` option with a typed value. See below.

--from examples:

$ devenv --from github:cachix/devenv shell
$ devenv --from github:cachix/devenv?dir=examples/simple shell
$ devenv --from path:/absolute/path/to/project shell
$ devenv --from path:./relative/path shell

--override-input examples:

$ devenv --override-input nixpkgs github:NixOS/nixpkgs/nixos-unstable shell
$ devenv --override-input nixpkgs path:/path/to/local/nixpkgs shell

--option / -O type syntax: The option name must include a type suffix: <attribute.path>:<type>.

Type	Description
`string`	String value
`int`	Integer value
`float`	Floating-point value
`bool`	Boolean (`true`/`false`)
`path`	Nix path
`pkg`	A single package from nixpkgs
`pkgs`	A list of packages (appends by default; append `!` to replace)

$ devenv --option languages.rust.channel:string beta shell
$ devenv --option services.postgres.enable:bool true shell
$ devenv --option packages:pkgs "ncdu git" shell          # appends
$ devenv --option packages:pkgs! "ncdu git" shell         # replaces

Nix options

Flag	Short	Env var	Description
`--max-jobs <N>`	`-j`	`DEVENV_MAX_JOBS`	Maximum concurrent Nix builds. Defaults to 1/4 of CPU cores.
`--cores <N>`	`-u`	`DEVENV_CORES`	CPU cores per build. Defaults to available cores divided by max-jobs.
`--system <SYSTEM>`	`-s`		Override the target system (e.g. `x86_64-linux`, `aarch64-darwin`).
`--impure`	`-i`		Relax hermeticity — allow access to the host environment.
`--no-impure`			Force a hermetic environment, overriding `devenv.yaml`.
`--offline`			Disable substituters; treat all cached files as up-to-date.
`--nix-option <NAME> <VALUE>`			Pass an option directly to Nix via `--option`. Repeatable.
`--nix-debugger`			Enter the Nix debugger on evaluation failure.

$ devenv -j 4 shell
$ devenv --nix-option sandbox false shell
$ devenv --nix-option keep-outputs true build

Shell options

Flag	Short	Env var	Description
`--clean [<VARS>...]`	`-c`		Strip parent environment variables. Optionally pass a comma-separated list of variables to keep.
`--profile <NAME>`	`-P`		Activate a named profile. Repeatable for multiple profiles.
`--reload`			Enable auto-reload when config files change (default).
`--no-reload`			Disable auto-reload.
`--shell <SHELL>`		`DEVENV_SHELL_TYPE`	Interactive shell to use: `bash`, `zsh`, `fish`, or `nu`.

$ devenv --clean shell               # strip all env vars
$ devenv --clean HOME,USER shell     # keep HOME and USER
$ devenv --profile backend shell
$ devenv -P backend -P testing shell

Cache options

Flag	Description
`--eval-cache`	Enable caching of Nix evaluation results (default).
`--no-eval-cache`	Disable Nix evaluation caching.
`--refresh-eval-cache`	Force a cache refresh for Nix evaluation.
`--refresh-task-cache`	Force a cache refresh for task results.

SecretSpec options

Flag	Env var	Description
`--secretspec-provider <PROVIDER>`	`SECRETSPEC_PROVIDER`	Override the secretspec provider.
`--secretspec-profile <PROFILE>`	`SECRETSPEC_PROFILE`	Override the secretspec profile.

Tracing options

Flag	Env var	Description
`--trace-to <SPEC>`	`DEVENV_TRACE_TO`	Enable tracing. Syntax: `[format:]destination`. Repeatable.
`--trace-output <DEST>` (legacy)	`DEVENV_TRACE_OUTPUT`	Legacy: use `--trace-to` instead.
`--trace-format <FMT>` (legacy)	`DEVENV_TRACE_FORMAT`	Legacy: use `--trace-to` instead.

--trace-to syntax: [format:]destination

Format	Description
`json` (default)	JSON structured log
`pretty`	Human-readable log
`full`	Verbose structured log
`otlp-grpc`	OpenTelemetry gRPC
`otlp-http-protobuf`	OpenTelemetry HTTP/Protobuf
`otlp-http-json`	OpenTelemetry HTTP/JSON

Destination	Description
`stdout`	Standard output
`stderr`	Standard error
`file:<path>`	Write to file
`http(s)://host:port`	OTLP endpoint

$ devenv --trace-to pretty:stderr shell
$ devenv --trace-to json:file:/tmp/trace.json shell
$ devenv --trace-to otlp-grpc:http://collector:4317 shell
$ devenv --trace-to pretty:stderr --trace-to json:file:/tmp/t.json shell

Global options

Flag	Short	Env var	Description
`--verbose`	`-v`		Enable additional debug logs.
`--quiet`	`-q`		Silence all logs.
`--tui`		`DEVENV_TUI`	Enable the interactive terminal UI (default when TTY is interactive).
`--no-tui`			Disable the interactive terminal UI.
`--help`	`-h`		Print help.
`--version`	`-V`		Print version and exit.

devenv init

Scaffold a new devenv project. Creates devenv.yaml, devenv.nix, .gitignore, and optionally .envrc.

$ devenv init [TARGET] [--include-envrc]

Flag	Env var	Description
`[TARGET]`		Optional path to create the project in. Defaults to the current directory.
`--include-envrc`	`DEVENV_INCLUDE_ENVRC`	Also create an `.envrc` file for direnv integration.

$ devenv init                        # scaffold in current directory
$ devenv init ./my-project           # scaffold in ./my-project
$ devenv init --include-envrc        # also create .envrc

devenv generate

Generate devenv.yaml and devenv.nix using AI from a natural language description.

$ devenv generate

You can also generate environments at devenv.new without installing devenv.

devenv shell

Activate the developer environment in an interactive shell session.

$ devenv shell [CMD [ARGS...]]

Argument	Description
`[CMD]`	Optional command to run inside the shell instead of starting an interactive session.
`[ARGS...]`	Arguments to pass to CMD.

$ devenv shell                       # interactive shell
$ devenv shell python manage.py runserver
$ devenv --profile backend shell
$ devenv --clean HOME,USER shell

devenv update

Update devenv.lock from the inputs declared in devenv.yaml. Without arguments, updates all inputs.

$ devenv update [NAME]

Argument	Description
`[NAME]`	Optional input name to update selectively.

$ devenv update                      # update all inputs
$ devenv update nixpkgs              # update only nixpkgs

devenv search

Search for packages and options available in nixpkgs.

$ devenv search <NAME>

$ devenv search nodejs
$ devenv search postgres
$ devenv search "python3"

devenv info

Print information about the current developer environment — inputs, packages, processes, services, scripts, and tasks.

$ devenv info

devenv show is an alias for devenv info.

devenv up

Start all processes in the foreground. Processes are defined in the processes option of devenv.nix.

$ devenv up [PROCESSES...] [OPTIONS]

Flag	Short	Description
`[PROCESSES...]`		Optionally start only specific named processes.
`--detach`	`-d`	Start processes in the background (daemon mode).
`--mode <MODE>`	`-m`	Execution mode for process dependency tasks. Default: `before`.
`--strict-ports`		Error if a port is in use instead of auto-allocating.
`--no-strict-ports`		Disable strict port mode, overriding `devenv.yaml`.

$ devenv up                          # start all processes
$ devenv up server worker            # start only server and worker
$ devenv up --detach                 # run in background

devenv down

Stop processes running in the background (started with devenv up --detach).

$ devenv down

devenv processes

Subcommands for managing individual processes when devenv is running.

$ devenv processes <SUBCOMMAND>

`devenv processes up`

Start processes in the foreground. Accepts the same flags as devenv up.

$ devenv processes up [PROCESSES...] [--detach] [--mode <MODE>]

`devenv processes down`

Stop all background processes.

$ devenv processes down

`devenv processes wait`

Block until all processes report ready.

$ devenv processes wait [--timeout <SECONDS>]

Flag	Default	Description
`--timeout <SECONDS>`	`120`	Maximum seconds to wait for readiness.

`devenv processes list`

List all managed processes and their current status.

$ devenv processes list

`devenv processes status`

Get the status of a specific process.

$ devenv processes status <NAME>

`devenv processes logs`

Get logs for a specific process.

$ devenv processes logs <NAME> [-n <LINES>] [--stdout] [--stderr]

Flag	Default	Description
`-n, --lines <N>`	`100`	Number of log lines to show.
`--stdout`		Show only stdout (mutually exclusive with `--stderr`).
`--stderr`		Show only stderr (mutually exclusive with `--stdout`).

`devenv processes restart`

Restart a running process.

$ devenv processes restart <NAME>

`devenv processes start`

Start a process (or all processes if no name is given).

$ devenv processes start [NAME] [--detach]

`devenv processes stop`

Stop a running process (or all processes if no name is given).

$ devenv processes stop [NAME]

devenv tasks

Subcommands for running and listing tasks defined in devenv.nix.

$ devenv tasks <SUBCOMMAND>

`devenv tasks run`

Run one or more tasks by name, respecting their dependency graph.

$ devenv tasks run [TASKS...] [OPTIONS]

Flag	Short	Description
`[TASKS...]`		Task names to run. If empty, runs all tasks.
`--mode <MODE>`	`-m`	Execution mode (affects dependency resolution). Default: `before`.
`--show-output`		Show task output for all tasks, even on success.
`--input <KEY=VALUE>`		Set a task input value. Repeatable. Value is parsed as JSON if valid, otherwise as string.
`--input-json <JSON>`		Set task inputs from a JSON object string.

$ devenv tasks run                        # run all tasks
$ devenv tasks run myapp:setup
$ devenv tasks run myapp:db-migrate --show-output
$ devenv tasks run myapp:build --input VERSION=1.2.3

`devenv tasks list`

List all available tasks and their descriptions.

$ devenv tasks list

devenv test

Run the test suite defined in enterTest. Automatically starts and stops processes around the test run.

$ devenv test [--override-dotfile]

Flag	Description
`--override-dotfile`	Override `.devenv` with a temporary directory for isolation.

$ devenv test
$ devenv test --override-dotfile

devenv ci is an alias for devenv test.

devenv container

Build, copy, or run OCI containers defined in the containers option of devenv.nix.

$ devenv container <SUBCOMMAND>

`devenv container build`

Build a container image.

$ devenv container build <NAME>

$ devenv container build app

`devenv container copy`

Copy a built container to a registry using skopeo.

$ devenv container copy <NAME> [--registry <REGISTRY>] [--copy-args <ARGS>]

Flag	Description
`--registry <REGISTRY>`	Destination registry URL.
`--copy-args <ARGS>`	Extra arguments to pass to `skopeo copy`. Repeatable.

$ devenv container copy app --registry ghcr.io/myorg/

`devenv container run`

Build and run a container locally.

$ devenv container run <NAME> [--copy-args <ARGS>]

devenv inputs

Manage inputs in devenv.yaml.

$ devenv inputs <SUBCOMMAND>

`devenv inputs add`

Add a new input to devenv.yaml.

$ devenv inputs add <NAME> <URL> [--follows <INPUT>...]

Argument/Flag	Description
`<NAME>`	Name for the new input.
`<URL>`	URI of the input (see yaml-options for supported URL formats).
`-f, --follows <INPUT>`	Input(s) this new input should follow. Repeatable.

$ devenv inputs add nixpkgs-stable github:NixOS/nixpkgs/nixos-24.11
$ devenv inputs add fenix github:nix-community/fenix --follows nixpkgs

devenv changelogs

Show relevant changelogs for devenv and its dependencies.

$ devenv changelogs

devenv repl

Launch an interactive Nix REPL pre-loaded with the current devenv configuration, for inspecting and debugging devenv.nix.

$ devenv repl

$ devenv repl
nix-repl> config.packages
nix-repl> config.env

devenv gc

Delete old shell generations and free up Nix store space. See Garbage Collection.

$ devenv gc

devenv build

Build one or more attributes from devenv.nix and place the results in the Nix store.

$ devenv build [ATTRIBUTES...]

$ devenv build
$ devenv build outputs.rust-app
$ devenv build outputs.python-app outputs.rust-app

devenv eval

Evaluate one or more attributes from devenv.nix and return the result as JSON.

$ devenv eval [ATTRIBUTES...]

$ devenv eval config.env
$ devenv eval config.packages

devenv direnvrc

Print a direnvrc snippet that adds devenv support to direnv. Pipe the output into your .envrc.

$ devenv direnvrc

Add to your .envrc:

eval "$(devenv direnvrc)"

# Optionally pass flags:
# use devenv --impure --option services.postgres.enable:bool true
use devenv

See direnv integration for full setup instructions.

devenv version

Print the installed version of devenv.

$ devenv version

devenv mcp

Launch a Model Context Protocol (MCP) server for AI assistant integration. The server exposes package and option search capabilities.

$ devenv mcp [--http [PORT]]

Flag	Description
`--http [PORT]`	Run as an HTTP server instead of stdio. Optionally specify a port (default: `8080`).

$ devenv mcp                         # stdio mode (for most AI tools)
$ devenv mcp --http                  # HTTP on port 8080
$ devenv mcp --http 9000             # HTTP on port 9000

devenv lsp

Start the nixd language server for devenv.nix, providing autocomplete, hover documentation, and go-to-definition.

$ devenv lsp [--print-config]

Flag	Description
`--print-config`	Print the nixd configuration JSON and exit (useful for editor setup).

devenv hook

Print a shell hook for automatic environment activation when you change into a project directory.

$ devenv hook <SHELL>

Value	Description
`bash`	Bash hook — add `eval "$(devenv hook bash)"` to `~/.bashrc`
`zsh`	Zsh hook — add `eval "$(devenv hook zsh)"` to `~/.zshrc`
`fish`	Fish hook — add `devenv hook fish \| source` to `~/.config/fish/config.fish`
`nu`	Nushell hook — see `devenv hook nu` output for instructions

$ devenv hook bash
$ eval "$(devenv hook bash)"         # add to ~/.bashrc

devenv allow

Allow automatic environment activation for the current directory (used with devenv hook).

$ devenv allow

devenv revoke

Revoke automatic environment activation for the current directory.

$ devenv revoke

Environment variables

In addition to per-flag environment variables documented above, devenv respects:

Variable	Description
`DEVENV_MAX_JOBS`	Maximum concurrent Nix builds (same as `-j`).
`DEVENV_CORES`	CPU cores per Nix build (same as `-u`).
`DEVENV_TUI`	Enable/disable the TUI (`1`/`0` or `true`/`false`).
`DEVENV_TRACE_TO`	Comma-separated `[format:]destination` trace specs.
`DEVENV_TRACE_OUTPUT` (legacy)	Legacy trace output destination.
`DEVENV_TRACE_FORMAT` (legacy)	Legacy trace format.
`DEVENV_SHELL_TYPE`	Shell type for interactive sessions (`bash`, `zsh`, `fish`, `nu`).
`SECRETSPEC_PROVIDER`	Secretspec provider override.
`SECRETSPEC_PROFILE`	Secretspec profile override.
`DEVENV_INCLUDE_ENVRC`	When set, `devenv init` includes an `.envrc` file.
`NIXPKGS_ACCEPT_ANDROID_SDK_LICENSE`	Accept the Android SDK license (`1` to accept).

Reference

Documentation Index

​Global Flags

​Input overrides

​Nix options

​Shell options

​Cache options

​SecretSpec options

​Tracing options

​Global options

​devenv init

​devenv generate

​devenv shell

​devenv update

​devenv search

​devenv info

​devenv up

​devenv down

​devenv processes

​devenv processes up

​devenv processes down

​devenv processes wait

​devenv processes list

​devenv processes status

​devenv processes logs

​devenv processes restart

​devenv processes start

​devenv processes stop

​devenv tasks

​devenv tasks run

​devenv tasks list

​devenv test

​devenv container

​devenv container build

​devenv container copy

​devenv container run

​devenv inputs

​devenv inputs add

​devenv changelogs

​devenv repl

​devenv gc

​devenv build

​devenv eval

​devenv direnvrc

​devenv version

​devenv mcp

​devenv lsp

​devenv hook

​devenv allow

​devenv revoke

​Environment variables

Build docs developers (and LLMs) love

Global Flags

Input overrides

Nix options

Shell options

Cache options

SecretSpec options

Tracing options

Global options

devenv init

devenv generate

devenv shell

devenv update

devenv search

devenv info

devenv up

devenv down

devenv processes

`devenv processes up`

`devenv processes down`

`devenv processes wait`

`devenv processes list`

`devenv processes status`

`devenv processes logs`

`devenv processes restart`

`devenv processes start`

`devenv processes stop`

devenv tasks

`devenv tasks run`

`devenv tasks list`

devenv test

devenv container

`devenv container build`

`devenv container copy`

`devenv container run`

devenv inputs

`devenv inputs add`

devenv changelogs

devenv repl

devenv gc

devenv build

devenv eval

devenv direnvrc

devenv version

devenv mcp

devenv lsp

devenv hook

devenv allow

devenv revoke

Environment variables