Settings

Settings are stored in /etc/nixos-cli/config.toml, and are stored in TOML format.

If preferred, this can be overridden by an environment variable NIXOS_CLI_CONFIG at runtime. This is useful for testing configuration files.

Additionally, some configuration values can be overridden on the command-line with the --config flag.

Example invocation:

$ nixos --config apply.imply_impure_with_tag=false apply

The preferred way to create this settings file is through the provided Nix module that generates the TOML using the programs.nixos-cli.config option. Refer to the module documentation for other available options.

Available Settings

These are the available settings for nixos-cli and their default values.

General

• aliases

  Defines alternative aliases for long commands to improve user ergonomics. The default list of aliases are mapped to common operations, and they can be overridden. They can also be disabled by setting use_default_aliases = false.

  Example:

  genlist = ['generation', 'list']
  rollback = ['generation', 'rollback']
  switch = ['generation', 'switch']
  

  Default:

  boot = ['apply', '--no-activate']
  build = ['apply', '--no-activate', '--no-boot', '--output', './result']
  build-image = ['apply', '--no-activate', '--no-boot', '--output', './result', '--image']
  build-vm = ['apply', '--no-activate', '--no-boot', '--output', './result', '--vm']
  build-vm-with-bootloader = ['apply', '--no-activate', '--no-boot', '--output', './result', '--vm-with-bootloader']
  dry-activate = ['apply', '--dry']
  dry-build = ['apply', '--no-activate', '--no-boot', '--dry']
  list-generations = ['generation', 'list', '--table']
  switch = ['apply']
  test = ['apply', '--no-boot']
  

• auto_rollback

  Enables automatic rollback of a NixOS system profile when an activation command fails. This can be disabled when a reboot or some other circumstance is needed for successful activation

  Default: true

• color

  Turns on ANSI color sequences for decorated output in supported terminals.

  Default: true

• config_location

  Path to a Nix file or directory to look for user configuration in by default.

  Default: '/etc/nixos'

• no_confirm

  Disables prompts that ask for user confirmation; useful for scripts and other automation.

  Default: false

  This setting has been deprecated, and will be removed in a future release.

  Set confirmation.always to true instead.

• root_command

  Specifies which command to use for privilege escalation (e.g., sudo or doas).

  Default: 'sudo'

• use_default_aliases

  Enables commonly used command aliases by default; these can be overridden by configuring the aliases setting. Defaults are shown in the aliases setting.

  Default: true

• use_nvd

  Use the better-looking nvd diffing tool when comparing configurations instead of nix store diff-closures.

  Default: false

apply

Settings for apply command

• apply.ignore_dirty_tree

  Allows 'apply' to use Git commit messages even when the working directory is dirty.

  Default: false

• apply.imply_impure_with_tag

  Automatically appends '--impure' to the 'apply' command when using '--tag' in flake-based workflows.

  Default: false

• apply.reexec_as_root

  Re-execute process as root using root_command. Only applies when activating or creating boot entries on a local system, or upgrading the root user's Nix channels.

  Default: false

• apply.specialisation

  Specifies which specialisation to use when activating a configuration with 'apply'.

  Default: ''

• apply.use_git_commit_msg

  When enabled, the last Git commit message will be used as the value for '--tag' automatically.

  Default: false

• apply.use_nom

  Enables nix-output-monitor to show more user-friendly build progress output for the 'apply' command.

  Default: false

confirmation

Settings for confirmation prompts throughout the program

• confirmation.always

  Disables prompts that ask for user confirmation; useful for automation.

  Default: false

• confirmation.empty

  Control confirmation prompt behavior when no input is provided. Possible values are default-no (treat as a no input), default-yes (treat as a yes input), or retry (try again).

  Default: 'default-no'

• confirmation.invalid

  Control confirmation prompt behavior when invalid input is provided. Possible values are default-no (treat as a no input), default-yes (treat as a yes input), or retry (try again).

  Default: 'retry'

enter

Settings for enter command

• enter.mount_resolv_conf

  Ensures internet access by mounting the host's /etc/resolv.conf into the chroot environment.

  Default: true

init

Settings for init command

• init.desktop_config

  Specifies the desktop environment configuration to inject during initialization.

  Default: ''

• init.extra_attrs

  Extra attributes to add to the generated configuration.nix file. Usually configured indirectly through the NixOS module.

  Default: ``

• init.extra_config

  Extra Nix code to add to the generated configuration.nix verbatim. Usually configured indirectly through the NixOS module.

  Default: ''

• init.xserver_enabled

  Controls whether X11-related services and packages are configured by default during init.

  Default: false

option

Settings for option command

• option.debounce_time

  Controls how often search results are recomputed when typing in the options UI, in milliseconds.

  Default: 25

• option.min_score

  Sets the cutoff score for showing results in fuzzy-matched option lookups.

  Default: 1

• option.prettify

  If enabled, renders option documentation in a prettier Markdown format where applicable.

  Default: true

ssh

Settings for SSH

• ssh.known_hosts_files

  List of paths to known hosts files. /etc/ssh/ssh_known_hosts and $HOME/.ssh/known_hosts are always included.

  Default: []

• ssh.private_key_cmd

  Specifies the command to run to obtain the private key for SSH connections. The command receives the host and user as the environment variables $NIXOS_CLI_SSH_HOST and $NIXOS_CLI_SSH_USER respectively, and should output a single private key to standard output.

  Example: ssh = ['sh', '-c', 'rbw get $NIXOS_CLI_SSH_HOST']

  Default: []