Command Line Options
You are currently reading the unstable version of the Colmena Manual, built against the tip of the development branch.
The following are the help messages that will be printed when you invoke any sub-command with --help:
colmena
NixOS deployment tool Colmena helps you deploy to multiple hosts running NixOS. For more details, read the manual at <https://colmena.cli.rs/0.5>. Note: You are using a pre-release version of Colmena, so the supported options may be different from what's in the manual. Usage: colmena [OPTIONS] <COMMAND> Commands: apply Apply configurations on remote machines apply-local Apply configurations on the local machine build Build configurations but not push to remote machines eval Evaluate an expression using the complete configuration upload-keys Upload keys to remote hosts exec Run a command on remote machines repl Start an interactive REPL with the complete configuration nix-info Show information about the current Nix installation help Print this message or the help of the given subcommand(s) Options: --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') -V, --version Print version --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena apply
Apply configurations on remote machines Usage: colmena apply [OPTIONS] [GOAL] Arguments: [GOAL] The goal of the deployment. 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: 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> 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 host evaluated at the same time based on naive heuristics. Set to 0 to disable the limit. [default: auto] -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallelism limit. [default: 10] --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --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. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -v, --verbose Deactivates the progress spinner and prints every line of output. --no-keys Do not upload secret keys set in `deployment.keys`. By default, Colmena will upload 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 `colmena upload-keys`. --reboot Reboots nodes after activation and waits for them to come back up. --no-substitute Disables the use of substituters when copying closures to the remote host. --no-gzip Disables the use of gzip when copying closures to the remote host. --build-on-target Build the system profiles on the target nodes themselves. If enabled, the system profiles will be built on the target nodes themselves, not on the host running Colmena itself. This overrides per-node perferences set in `deployment.buildOnTarget`. To temporarily disable remote build on all nodes, use `--no-build-on-target`. --force-replace-unknown-profiles If `deployment.replaceUnknownProfiles` is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set true and perform unknown profile replacement. --evaluator <EVALUATOR> 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: chunked] [possible values: chunked, streaming] --on <NODES> 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-* -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena apply-local
Apply configurations on the local machine Usage: colmena apply-local [OPTIONS] [GOAL] Arguments: [GOAL] Same as the targets for switch-to-configuration. "push" is noop in apply-local. [default: 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 --show-trace Passes --show-trace to Nix commands -v, --verbose Deactivates the progress spinner and prints every line of output. --impure Passes --impure to Nix commands --no-keys Do not deploy secret keys set in `deployment.keys`. By default, Colmena will deploy keys set in `deployment.keys` before activating the profile on this host. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. --node <NODE> Override the node name to use -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena build
Build configurations but not push to remote machines This subcommand behaves as if you invoked `apply` with the `build` goal. Usage: colmena build [OPTIONS] Options: --eval-node-limit <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 host evaluated at the same time based on naive heuristics. Set to 0 to disable the limit. [default: auto] -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallelism limit. [default: 10] --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --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. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -v, --verbose Deactivates the progress spinner and prints every line of output. --no-keys Do not upload secret keys set in `deployment.keys`. By default, Colmena will upload 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 `colmena upload-keys`. --reboot Reboots nodes after activation and waits for them to come back up. --no-substitute Disables the use of substituters when copying closures to the remote host. --no-gzip Disables the use of gzip when copying closures to the remote host. --build-on-target Build the system profiles on the target nodes themselves. If enabled, the system profiles will be built on the target nodes themselves, not on the host running Colmena itself. This overrides per-node perferences set in `deployment.buildOnTarget`. To temporarily disable remote build on all nodes, use `--no-build-on-target`. --force-replace-unknown-profiles If `deployment.replaceUnknownProfiles` is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set true and perform unknown profile replacement. --evaluator <EVALUATOR> 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: chunked] [possible values: chunked, streaming] --on <NODES> 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-* -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena upload-keys
Upload keys to remote hosts This subcommand behaves as if you invoked `apply` with the pseudo `keys` goal. Usage: colmena upload-keys [OPTIONS] Options: --eval-node-limit <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 host evaluated at the same time based on naive heuristics. Set to 0 to disable the limit. [default: auto] -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallelism limit. [default: 10] --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --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. --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -v, --verbose Deactivates the progress spinner and prints every line of output. --no-keys Do not upload secret keys set in `deployment.keys`. By default, Colmena will upload 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 `colmena upload-keys`. --reboot Reboots nodes after activation and waits for them to come back up. --no-substitute Disables the use of substituters when copying closures to the remote host. --no-gzip Disables the use of gzip when copying closures to the remote host. --build-on-target Build the system profiles on the target nodes themselves. If enabled, the system profiles will be built on the target nodes themselves, not on the host running Colmena itself. This overrides per-node perferences set in `deployment.buildOnTarget`. To temporarily disable remote build on all nodes, use `--no-build-on-target`. --force-replace-unknown-profiles If `deployment.replaceUnknownProfiles` is set for a target, using this switch will treat deployment.replaceUnknownProfiles as though it was set true and perform unknown profile replacement. --evaluator <EVALUATOR> 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: chunked] [possible values: chunked, streaming] --on <NODES> 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-* -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena eval
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: colmena eval [OPTIONS] [FILE] Arguments: [FILE] The .nix file containing the expression Options: -E <EXPRESSION> The Nix expression --instantiate Actually instantiate the expression --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena exec
Run a command on remote machines Usage: colmena exec [OPTIONS] <COMMAND>... Arguments: <COMMAND>... Command to run It's recommended to use -- to separate Colmena options from the command to run. For example: colmena exec --on @routers -- tcpdump -vni any ip[9] == 89 Options: -p, --parallel <LIMIT> Limits the maximum number of hosts to run the command in parallel. In `colmena exec`, the parallelism limit is disabled (0) by default. [default: 0] --show-trace Passes --show-trace to Nix commands -v, --verbose Deactivates the progress spinner and prints every line of output. --impure Passes --impure to Nix commands --on <NODES> 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-* --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena nix-info
Show information about the current Nix installation Usage: colmena nix-info [OPTIONS] Options: --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors
colmena repl
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: colmena repl [OPTIONS] Options: --show-trace Passes --show-trace to Nix commands --impure Passes --impure to Nix commands --nix-option <NAME> <VALUE> Passes arbitrary options to Nix commands This only works when building locally. -f, --config <CONFIG> If this argument is not specified, Colmena 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://colmena.cli.rs/0.5>. -h, --help Print help (see a summary with '-h') --color <WHEN> When to colorize the output. By default, Colmena 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: auto] Possible values: - auto: Detect automatically - always: Always display colors - never: Never display colors