Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Command line

This document contains the help content for the navi command-line program.

Command Overview:

NixOS deployment tool

Navi helps you deploy to multiple hosts running NixOS. For more details, read the manual at https://navi.cli.rs/0.0.

Note: You are using a pre-release version of Navi, so the supported options may be different from what's in the manual.

Usage: navi [OPTIONS] <COMMAND>

Subcommands:
  • apply — Apply configurations on remote machines
  • apply-local — Apply configurations on the local machine
  • build — Build configurations but not push to remote hosts
  • eval — Evaluate an expression using the complete configuration
  • upload-keys — Upload keys to remote hosts
  • exec — Run a command on remote machines
  • list — List available hosts and their configuration
  • repl — Start an interactive REPL with the complete configuration
  • nix-info — Show information about the current Nix installation
  • tui — Start an interactive TUI dashboard
  • serial — Connect to node serial console
  • ssh — SSH into a host
  • disk-unlock — Unlock a disk on a remote host
  • facts — Manage persistent facts
  • provision — Provision infrastructure for nodes
  • install — Install NixOS on target nodes
  • daemon — Start the Navi Daemon
Options:

  • -f, --config <CONFIG> — If this argument is not specified, Navi will search upwards from the current working directory for a file named "flake.nix" or "hive.nix". This behavior is disabled if --config/-f is given explicitly.

    For a sample configuration, check the manual at https://navi.cli.rs/0.0.

  • --show-trace — Show debug information for Nix commands

    Passes --show-trace to Nix commands

  • --impure — Allow impure expressions

    Passes --impure to Nix commands

  • --nix-option <NAME> — Passes an arbitrary option to Nix commands

    This only works when building locally.

  • --color <WHEN> — When to colorize the output

    By default, Navi enables colorized output when the terminal supports it.

    It's also possible to specify the preference using environment variables. See https://bixense.com/clicolors.

    Default value: auto

    Possible values:

    • auto: Detect automatically
    • always: Always display colors
    • never: Never display colors

Apply configurations on remote machines

Usage: navi apply [OPTIONS] [GOAL]

Arguments:

  • <GOAL> — Deployment goal

    Same as the targets for switch-to-configuration, with the following extra pseudo-goals:

    • build: Only build the system profiles - push: Only copy the closures to remote nodes - keys: Only upload the keys to the remote nodes

    switch is the default goal unless --reboot is passed, in which case boot is the default.

    Default value: switch

    Possible values:

    • build: Build the configurations only
    • push: Push the closures only
    • switch: Make the configuration the boot default and activate now
    • boot: Make the configuration the boot default
    • test: Activate the configuration, but don't make it the boot default
    • dry-activate: Show what would be done if this configuration were activated
    • upload-keys: Only upload keys
Options:

  • --eval-node-limit <LIMIT> — Evaluation node limit

    Limits the maximum number of hosts to be evaluated at once. The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of hosts evaluated at the same time based on naive heuristics.

    Set to 0 to disable the limit.

    Default value: auto

  • -p, --parallel <LIMIT> — Deploy parallelism limit

    Limits the maximum number of hosts to be deployed in parallel.

    Set to 0 to disable parallelism limit.

    Default value: 10

  • --keep-result — Create GC roots for built profiles.

    The built system profiles will be added as GC roots so that they will not be removed by the garbage collector. The links will be created under .gcroots in the directory the Hive configuration is located.

  • -v, --verbose — Be verbose

    Deactivates the progress spinner and prints every line of output.

  • --no-keys — Do not upload keys

    By default, Navi will upload secret keys set in deployment.keys before deploying the new profile on a node. To upload keys without building or deploying the rest of the configuration, use navi upload-keys.

  • --reboot — Reboot nodes after activation

    Reboots nodes after activation and waits for them to come back up.

  • --no-substitute — Do not use substitutes

    Disables the use of substituters when copying closures to the remote host.

  • --no-gzip — Do not use gzip

    Disables the use of gzip when copying closures to the remote host.

  • --build-on-target — Build the system profiles on the target nodes

    If enabled, the system profiles will be built on the target nodes themselves, not on the host running Navi. This overrides per-node preferences set in deployment.buildOnTarget. To temporarily disable remote build on all nodes, use --no-build-on-target.

  • --force-replace-unknown-profiles — Ignore all targeted nodes deployment.replaceUnknownProfiles setting

    If deployment.replaceUnknownProfiles is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set to true and perform unknown profile replacement.

  • --install-bootloader — Install bootloader

    If enabled, the bootloader will be installed during activation. This is equivalent to NIXOS_INSTALL_BOOTLOADER=1.

  • --evaluator <EVALUATOR> — The evaluator to use (experimental)

    If set to chunked (default), evaluation of nodes will happen in batches. If set to streaming, the experimental streaming evaluator (nix-eval-jobs) will be used and nodes will be evaluated in parallel.

    This is an experimental feature.

    Default value: chunked

    Possible values: chunked, streaming

  • --on <NODES> — Node selector

    Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples:

    • host1,host2,host3 - edge-* - edge-,core- - @a-tag,@tags-can-have-*

Apply configurations on the local machine

Usage: navi apply-local [OPTIONS] [GOAL]

Arguments:

  • <GOAL> — Deployment goal

    Same as the targets for switch-to-configuration. "push" is noop in apply-local.

    Default value: switch

    Possible values:

    • build: Build the configurations only
    • push: Push the closures only
    • switch: Make the configuration the boot default and activate now
    • boot: Make the configuration the boot default
    • test: Activate the configuration, but don't make it the boot default
    • dry-activate: Show what would be done if this configuration were activated
    • upload-keys: Only upload keys
Options:

  • --sudo — Attempt to escalate privileges if not run as root

  • -v, --verbose — Be verbose

    Deactivates the progress spinner and prints every line of output.

  • --no-keys — Do not deploy keys

    Do not deploy secret keys set in deployment.keys. By default, Navi will deploy keys set in deployment.keys before activating the profile on this host.

  • --install-bootloader — Install bootloader

    If enabled, the bootloader will be installed during activation. This is equivalent to NIXOS_INSTALL_BOOTLOADER=1.

  • --node <NODE> — Override the node name to use

Build configurations but not push to remote hosts

This subcommand behaves as if you invoked apply with the build goal.

Usage: navi build [OPTIONS]

Options:

  • --eval-node-limit <LIMIT> — Evaluation node limit

    Limits the maximum number of hosts to be evaluated at once. The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of hosts evaluated at the same time based on naive heuristics.

    Set to 0 to disable the limit.

    Default value: auto

  • -p, --parallel <LIMIT> — Deploy parallelism limit

    Limits the maximum number of hosts to be deployed in parallel.

    Set to 0 to disable parallelism limit.

    Default value: 10

  • --keep-result — Create GC roots for built profiles.

    The built system profiles will be added as GC roots so that they will not be removed by the garbage collector. The links will be created under .gcroots in the directory the Hive configuration is located.

  • -v, --verbose — Be verbose

    Deactivates the progress spinner and prints every line of output.

  • --no-keys — Do not upload keys

    By default, Navi will upload secret keys set in deployment.keys before deploying the new profile on a node. To upload keys without building or deploying the rest of the configuration, use navi upload-keys.

  • --reboot — Reboot nodes after activation

    Reboots nodes after activation and waits for them to come back up.

  • --no-substitute — Do not use substitutes

    Disables the use of substituters when copying closures to the remote host.

  • --no-gzip — Do not use gzip

    Disables the use of gzip when copying closures to the remote host.

  • --build-on-target — Build the system profiles on the target nodes

    If enabled, the system profiles will be built on the target nodes themselves, not on the host running Navi. This overrides per-node preferences set in deployment.buildOnTarget. To temporarily disable remote build on all nodes, use --no-build-on-target.

  • --force-replace-unknown-profiles — Ignore all targeted nodes deployment.replaceUnknownProfiles setting

    If deployment.replaceUnknownProfiles is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set to true and perform unknown profile replacement.

  • --install-bootloader — Install bootloader

    If enabled, the bootloader will be installed during activation. This is equivalent to NIXOS_INSTALL_BOOTLOADER=1.

  • --evaluator <EVALUATOR> — The evaluator to use (experimental)

    If set to chunked (default), evaluation of nodes will happen in batches. If set to streaming, the experimental streaming evaluator (nix-eval-jobs) will be used and nodes will be evaluated in parallel.

    This is an experimental feature.

    Default value: chunked

    Possible values: chunked, streaming

  • --on <NODES> — Node selector

    Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples:

    • host1,host2,host3 - edge-* - edge-,core- - @a-tag,@tags-can-have-*

Evaluate an expression using the complete configuration

Your expression should take an attribute set with keys pkgs, lib and nodes (like a NixOS module) and return a JSON-serializable value. For example, to retrieve the configuration of one node, you may write something like:

{ nodes, ... }: nodes.node-a.config.networking.hostName

Usage: navi eval [OPTIONS] [FILE]

Arguments:
  • <FILE> — The .nix file containing the expression
Options:
  • -E <EXPRESSION> — The Nix expression
  • --instantiate — Actually instantiate the expression

Upload keys to remote hosts

This subcommand behaves as if you invoked apply with the pseudo keys goal.

Usage: navi upload-keys [OPTIONS]

Options:

  • --eval-node-limit <LIMIT> — Evaluation node limit

    Limits the maximum number of hosts to be evaluated at once. The evaluation process is RAM-intensive. The default behavior is to limit the maximum number of hosts evaluated at the same time based on naive heuristics.

    Set to 0 to disable the limit.

    Default value: auto

  • -p, --parallel <LIMIT> — Deploy parallelism limit

    Limits the maximum number of hosts to be deployed in parallel.

    Set to 0 to disable parallelism limit.

    Default value: 10

  • --keep-result — Create GC roots for built profiles.

    The built system profiles will be added as GC roots so that they will not be removed by the garbage collector. The links will be created under .gcroots in the directory the Hive configuration is located.

  • -v, --verbose — Be verbose

    Deactivates the progress spinner and prints every line of output.

  • --no-keys — Do not upload keys

    By default, Navi will upload secret keys set in deployment.keys before deploying the new profile on a node. To upload keys without building or deploying the rest of the configuration, use navi upload-keys.

  • --reboot — Reboot nodes after activation

    Reboots nodes after activation and waits for them to come back up.

  • --no-substitute — Do not use substitutes

    Disables the use of substituters when copying closures to the remote host.

  • --no-gzip — Do not use gzip

    Disables the use of gzip when copying closures to the remote host.

  • --build-on-target — Build the system profiles on the target nodes

    If enabled, the system profiles will be built on the target nodes themselves, not on the host running Navi. This overrides per-node preferences set in deployment.buildOnTarget. To temporarily disable remote build on all nodes, use --no-build-on-target.

  • --force-replace-unknown-profiles — Ignore all targeted nodes deployment.replaceUnknownProfiles setting

    If deployment.replaceUnknownProfiles is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set to true and perform unknown profile replacement.

  • --install-bootloader — Install bootloader

    If enabled, the bootloader will be installed during activation. This is equivalent to NIXOS_INSTALL_BOOTLOADER=1.

  • --evaluator <EVALUATOR> — The evaluator to use (experimental)

    If set to chunked (default), evaluation of nodes will happen in batches. If set to streaming, the experimental streaming evaluator (nix-eval-jobs) will be used and nodes will be evaluated in parallel.

    This is an experimental feature.

    Default value: chunked

    Possible values: chunked, streaming

  • --on <NODES> — Node selector

    Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples:

    • host1,host2,host3 - edge-* - edge-,core- - @a-tag,@tags-can-have-*

Run a command on remote machines

Usage: navi exec [OPTIONS] <COMMAND>...

Arguments:

  • <COMMAND> — Command to run

    It's recommended to use -- to separate Navi options from the command to run. For example:

    navi exec --on @routers -- tcpdump -vni any ip[9] == 89

Options:

  • -p, --parallel <LIMIT> — Deploy parallelism limit

    Limits the maximum number of hosts to run the command in parallel.

    In navi exec, the parallelism limit is disabled (0) by default.

    Default value: 0

  • -v, --verbose — Be verbose

    Deactivates the progress spinner and prints every line of output.

  • --on <NODES> — Node selector

    Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples:

    • host1,host2,host3 - edge-* - edge-,core- - @a-tag,@tags-can-have-*

List available hosts and their configuration

Usage: navi list [OPTIONS]

Options:

  • -j, --json — Output in JSON format

  • --group-by <KEY> — Group hosts into sections by the given key

    Possible values:

    • tag: One section per tag (hosts with several tags appear in each)
    • provisioner: One section per provisioner
    • link: One section per connection link (SSH, GCP, ...)

Start an interactive REPL with the complete configuration

In the REPL, you can inspect the configuration interactively with tab completion. The node configurations are accessible under the nodes attribute set.

Usage: navi repl

Show information about the current Nix installation

Usage: navi nix-info

Start an interactive TUI dashboard

Usage: navi tui [OPTIONS]

Options:

  • -p, --parallel <PARALLEL> — Limit the maximum number of hosts to be deployed in parallel

    Default value: 10

  • --no-daemon — Disable daemon and force local execution

    Default value: false

Connect to node serial console

Usage: navi serial <NODE>

Arguments:
  • <NODE> — The node to connect to

SSH into a host

Usage: navi ssh [OPTIONS] [HOST] [-- <COMMAND>...]

Arguments:
  • <HOST> — Host to connect to (required unless -R is used)
  • <COMMAND> — Command and arguments to pass to SSH
Options:

  • -R, --remove-keys — Remove host keys from known_hosts

  • --on <NODES> — Node selector

    Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples:

    • host1,host2,host3 - edge-* - edge-,core- - @a-tag,@tags-can-have-*

Unlock a disk on a remote host

Usage: navi disk-unlock <HOST>

Arguments:
  • <HOST> — Host to unlock

Manage persistent facts

Usage: navi facts <COMMAND>

Subcommands:
  • derive — Derive facts from the Nix configuration (Pre-computation)

Derive facts from the Nix configuration (Pre-computation)

Usage: navi facts derive [FILTERS]...

Arguments:
  • <FILTERS> — Filter facts to generate (glob patterns)

Provision infrastructure for nodes

Usage: navi provision [OPTIONS] [PROVISIONER]

Arguments:
  • <PROVISIONER> — Explicitly select a provisioner to run
Options:

  • --list — List available provisioners

  • --reprovision — Destroy and recreate the infrastructure

  • --unlock — Unlock the disk after deployment

  • --update-tf-lock <UPDATE_TF_LOCK> — Update the local Terraform lock file from the sandbox state

  • --skip-install — Skip the OS installation step (nixos-anywhere), only provision infrastructure and update facts

  • --ip <IP> — IP address for bare-metal provisioning (skips interactive prompt)

  • --initial-password <INITIAL_PASSWORD> — Password for initial SSH connection to the installer (e.g. for bare-metal hosts that haven't been keyed yet). Passed to nixos-anywhere via --env-password

  • --on <NODES> — Node selector

    Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples:

    • host1,host2,host3 - edge-* - edge-,core- - @a-tag,@tags-can-have-*

Install NixOS on target nodes

Usage: navi install [OPTIONS]

Options:

  • --on <NODES> — Node selector

    Select a list of nodes to deploy to. The list is comma-separated and globs are supported. To match tags, prepend the filter by @. Valid examples:

    • host1,host2,host3 - edge-* - edge-,core- - @a-tag,@tags-can-have-*

  • --provisioner <PROVISIONER> — Explicitly select a provisioner to run

  • --force — Force installation even if provenance file exists

  • --unlock — Unlock the disk after installation

  • --list — List selected nodes without installing

  • --reinstall — Destroy and recreate the specific VM before installing

Start the Navi Daemon

Usage: navi daemon <COMMAND>

Subcommands:
  • start — Start the daemon server
  • status — Get daemon status

Start the daemon server

Usage: navi daemon start

Get daemon status

Usage: navi daemon status