Command Line Arguments

The following are the help messages that will be printed when you invoke any sub-command with --help:

`colmena`

Colmena 0.2.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://zhaofengli.github.io/colmena/0.2>.


USAGE:
    colmena [FLAGS] [OPTIONS] [SUBCOMMAND]

FLAGS:
    -h, --help          
            Prints help information

        --show-trace    
            Passes --show-trace to Nix commands

    -V, --version       
            Prints version information


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://zhaofengli.github.io/colmena/0.2>.
             [default: hive.nix]

SUBCOMMANDS:
    apply          Apply configurations on remote machines
    apply-local    Apply configurations on the local machine
    build          Build the configuration but not push to remote machines
    eval           Evaluate expressions using the complete configuration
    exec           Run a command on remote machines
    help           Prints 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 [FLAGS] [OPTIONS] [goal]

FLAGS:
--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
Prints 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.

-V, --version
Prints version information

-v, --verbose
Deactivates the progress spinner and prints every line of output.

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]
--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]

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]

`colmena apply-local`

colmena-apply-local 
Apply configurations on the local machine

USAGE:
    colmena apply-local [FLAGS] [OPTIONS] [goal]

FLAGS:
    -h, --help       
            Prints 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.
        --sudo       
            Attempt to escalate privileges if not run as root

    -V, --version    
            Prints version information

    -v, --verbose    
            Deactivates the progress spinner and prints every line of output.


OPTIONS:
        --node <node>               
            Override the node name to use

        --sudo-command <COMMAND>    
            Command to use to escalate privileges [default: sudo]


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]

`colmena build`

colmena-build
Build the configuration but not push to remote machines

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

USAGE:
colmena build [FLAGS] [OPTIONS]

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

--no-keys
Do not upload secret keys set in `deployment.keys`.

-V, --version
Prints version information

-v, --verbose
Deactivates the progress spinner and prints every line of output.

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]
--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]

`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 [FLAGS] [OPTIONS]

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

--no-keys
Do not upload secret keys set in `deployment.keys`.

-V, --version
Prints version information

-v, --verbose
Deactivates the progress spinner and prints every line of output.

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]
--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]

`colmena eval`

colmena-eval 
Evaluate expressions 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 [FLAGS] [OPTIONS] [FILE]

FLAGS:
    -h, --help           
            Prints help information

        --instantiate    
            Actually instantiate the expression

    -V, --version        
            Prints version information


OPTIONS:
    -E <EXPRESSION>        
            The Nix expression


ARGS:
    <FILE>    
            The .nix file containing the expression

`colmena exec`

colmena-exec 
Run a command on remote machines

USAGE:
    colmena exec [FLAGS] [OPTIONS] [--] <COMMAND>...

FLAGS:
    -h, --help       
            Prints help information

    -V, --version    
            Prints version information

    -v, --verbose    
            Deactivates the progress spinner and prints every line of output.


OPTIONS:
        --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]

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

`colmena nix-info`

colmena-nix-info 
Show information about the current Nix installation

USAGE:
    colmena nix-info

FLAGS:
    -h, --help       
            Prints help information

    -V, --version    
            Prints version information