Command Line Options
The following are the help messages that will be printed when you invoke any sub-command with --help:
colmena
Colmena 0.3.2 Zhaofeng Li <hello@zhaofeng.li> NixOS deployment tool Colmena helps you deploy to multiple hosts running NixOS. For more details, read the manual at <https://colmena.cli.rs/0.3>. USAGE: colmena [OPTIONS] [SUBCOMMAND] OPTIONS: -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.3>. [default: hive.nix] -h, --help Print help information --show-trace Passes --show-trace to Nix commands -V, --version Print version information --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, always, never] SUBCOMMANDS: 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 exec Run a command on remote machines help Print this message or the help of the given subcommand(s) nix-info Show information about the current Nix installation upload-keys Upload keys to remote hosts
colmena apply
colmena-apply Apply configurations on remote machines USAGE: colmena apply [OPTIONS] [goal] ARGS: <goal> Same as the targets for switch-to-configuration. "push" means only copying the closures to remote nodes. [default: switch] [possible values: build, push, switch, boot, test, dry-activate, keys] OPTIONS: -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.3>. [default: hive.nix] --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`. --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] --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] --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. -h, --help Print help information --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. --no-gzip Disables the use of gzip when copying closures to the remote host. --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`. --no-substitutes Disables the use of substituters when copying closures to the remote host. --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-* -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallemism limit. [default: 10] --show-trace Passes --show-trace to Nix commands -v, --verbose Deactivates the progress spinner and prints every line of output. --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, always, never]
colmena apply-local
colmena-apply-local Apply configurations on the local machine USAGE: colmena apply-local [OPTIONS] [goal] ARGS: <goal> Same as the targets for switch-to-configuration. "push" is noop in apply-local. [default: switch] [possible values: push, switch, boot, test, dry-activate, keys] OPTIONS: -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.3>. [default: hive.nix] -h, --help Print help information --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. --node <node> Override the node name to use --show-trace Passes --show-trace to Nix commands --sudo Attempt to escalate privileges if not run as root --sudo-command <COMMAND> Command to use to escalate privileges [default: sudo] -v, --verbose Deactivates the progress spinner and prints every line of output. --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, always, never]
colmena build
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: -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.3>. [default: hive.nix] --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`. --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] --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] --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. -h, --help Print help information --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. --no-gzip Disables the use of gzip when copying closures to the remote host. --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`. --no-substitutes Disables the use of substituters when copying closures to the remote host. --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-* -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallemism limit. [default: 10] --show-trace Passes --show-trace to Nix commands -v, --verbose Deactivates the progress spinner and prints every line of output. --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, always, never]
colmena upload-keys
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: -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.3>. [default: hive.nix] --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`. --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] --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] --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. -h, --help Print help information --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. --no-gzip Disables the use of gzip when copying closures to the remote host. --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`. --no-substitutes Disables the use of substituters when copying closures to the remote host. --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-* -p, --parallel <LIMIT> Limits the maximum number of hosts to be deployed in parallel. Set to 0 to disable parallemism limit. [default: 10] --show-trace Passes --show-trace to Nix commands -v, --verbose Deactivates the progress spinner and prints every line of output. --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, always, never]
colmena eval
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] ARGS: <FILE> The .nix file containing the expression OPTIONS: -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.3>. [default: hive.nix] -E <EXPRESSION> The Nix expression -h, --help Print help information --instantiate Actually instantiate the expression --show-trace Passes --show-trace to Nix commands --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, always, never]
colmena exec
colmena-exec Run a command on remote machines USAGE: colmena exec [OPTIONS] [--] <COMMAND>... ARGS: <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: -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.3>. [default: hive.nix] -h, --help Print help information --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-* -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. --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, always, never]
colmena nix-info
colmena-nix-info Show information about the current Nix installation USAGE: colmena nix-info [OPTIONS] OPTIONS: -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.3>. [default: hive.nix] -h, --help Print help information --show-trace Passes --show-trace to Nix commands --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, always, never]