lib.cli: command-line serialization functions

lib.cli.toGNUCommandLineShell

Automatically convert an attribute set to command-line options.

This helps protect against malformed command lines and also to reduce boilerplate related to command-line construction for simple use cases.

toGNUCommandLineShell returns an escaped shell string.

Inputs

options

How to format the arguments, see toGNUCommandLine

attrs

The attributes to transform into arguments.

Examples

Example

lib.cli.toGNUCommandLineShell usage example

cli.toGNUCommandLineShell {} {
  data = builtins.toJSON { id = 0; };
  X = "PUT";
  retry = 3;
  retry-delay = null;
  url = [ "https://example.com/foo" "https://example.com/bar" ];
  silent = false;
  verbose = true;
}
=> "'-X' 'PUT' '--data' '{\"id\":0}' '--retry' '3' '--url' 'https://example.com/foo' '--url' 'https://example.com/bar' '--verbose'";

Located at lib/cli.nix:58 in <nixpkgs>.

lib.cli.toGNUCommandLine

Automatically convert an attribute set to a list of command-line options.

toGNUCommandLine returns a list of string arguments.

Inputs

options

How to format the arguments, see below.

attrs

The attributes to transform into arguments.

Options

mkOptionName

How to string-format the option name; By default one character is a short option (-), more than one characters a long option (--).

mkBool

How to format a boolean value to a command list; By default it’s a flag option (only the option name if true, left out completely if false).

mkList

How to format a list value to a command list; By default the option name is repeated for each value and mkOption is applied to the values themselves.

mkOption

How to format any remaining value to a command list; On the toplevel, booleans and lists are handled by mkBool and mkList, though they can still appear as values of a list. By default, everything is printed verbatim and complex types are forbidden (lists, attrsets, functions). null values are omitted.

optionValueSeparator

How to separate an option from its flag; By default, there is no separator, so option -c and value 5 would become ["-c" "5"]. This is useful if the command requires equals, for example, -c=5.

Examples

Example

lib.cli.toGNUCommandLine usage example

cli.toGNUCommandLine {} {
  data = builtins.toJSON { id = 0; };
  X = "PUT";
  retry = 3;
  retry-delay = null;
  url = [ "https://example.com/foo" "https://example.com/bar" ];
  silent = false;
  verbose = true;
}
=> [
  "-X" "PUT"
  "--data" "{\"id\":0}"
  "--retry" "3"
  "--url" "https://example.com/foo"
  "--url" "https://example.com/bar"
  "--verbose"
]

Located at lib/cli.nix:134 in <nixpkgs>.

lib.cli.toCommandLineShellGNU

Converts the given attributes into a single shell-escaped command-line string. Similar to toCommandLineGNU, but returns a single escaped string instead of a list of arguments. For further reference see: lib.cli.toCommandLineGNU

Located at lib/cli.nix:180 in <nixpkgs>.

lib.cli.toCommandLineGNU

Converts an attribute set into a list of GNU-style command-line arguments.

toCommandLineGNU returns a list of string arguments.

Inputs

options

Options, see below.

attrs

The attributes to transform into arguments.

Options

isLong

A function that determines whether an option is long or short.

explicitBool

Whether or not boolean option arguments should be formatted explicitly.

formatArg

A function that turns the option argument into a string.

Examples

Example

lib.cli.toCommandLineGNU usage example

lib.cli.toCommandLineGNU {} {
  v = true;
  verbose = [true true false null];
  i = ".bak";
  testsuite = ["unit" "integration"];
  e = ["s/a/b/" "s/b/c/"];
  n = false;
  data = builtins.toJSON {id = 0;};
}
=> [
  "--data={\"id\":0}"
  "-es/a/b/"
  "-es/b/c/"
  "-i.bak"
  "--testsuite=unit"
  "--testsuite=integration"
  "-v"
  "--verbose"
  "--verbose"
]

Located at lib/cli.nix:241 in <nixpkgs>.

lib.cli.toCommandLineShell

Converts the given attributes into a single shell-escaped command-line string. Similar to toCommandLine, but returns a single escaped string instead of a list of arguments. For further reference see: lib.cli.toCommandLine

Located at lib/cli.nix:264 in <nixpkgs>.

lib.cli.toCommandLine

Converts an attribute set into a list of command-line arguments.

This is the most general command-line construction helper in lib.cli. It is parameterized by an optionFormat function, which defines how each option name and its value are rendered.

All other helpers in this file are thin wrappers around this function.

toCommandLine returns a flat list of strings, suitable for use as argv arguments or for further processing (e.g. shell escaping).

Inputs

optionFormat

A function that takes the option name and returns an option spec, where the option spec is an attribute set describing how the option should be rendered.

The returned attribute set must contain:

  • option (string): The option flag itself, e.g. "-v" or "--verbose".

  • sep (string or null): How to separate the option from its argument. If null, the option and its argument are returned as two separate list elements. If a string (e.g. "="), the option and argument are concatenated.

  • explicitBool (bool): Controls how boolean values are handled:

    • false: true emits only the option flag, false emits nothing.
    • true: both true and false are rendered as explicit arguments via formatArg.

Optional fields:

  • formatArg: Converts the option value to a string. Defaults to lib.generators.mkValueStringDefault { }.

attrs

An attribute set mapping option names to values.

Supported value types:

  • null: omitted entirely
  • bool: handled according to explicitBool
  • list: each element is rendered as a separate occurrence of the option
  • any other value: rendered as a single option argument

Empty attribute names are rejected.

Examples

Example

lib.cli.toCommandLine basic usage example

let
  optionFormat = optionName: {
    option = "-${optionName}";
    sep = "=";
    explicitBool = true;
  };
in
lib.cli.toCommandLine optionFormat {
  v = true;
  verbose = [
    true
    true
    false
    null
  ];
  i = ".bak";
  testsuite = [
    "unit"
    "integration"
  ];
  e = [
    "s/a/b/"
    "s/b/c/"
  ];
  n = false;
  data = builtins.toJSON { id = 0; };
}
=> [
  "-data={\"id\":0}"
  "-e=s/a/b/"
  "-e=s/b/c/"
  "-i=.bak"
  "-n=false"
  "-testsuite=unit"
  "-testsuite=integration"
  "-v=true"
  "-verbose=true"
  "-verbose=true"
  "-verbose=false"
]

Example

lib.cli.toCommandLine usage with a more complex option format

let
  optionFormat =
    optionName:
    let
      isLong = builtins.stringLength optionName > 1;
    in
    {
      option = if isLong then "--${optionName}" else "-${optionName}";
      sep = if isLong then "=" else null;
      explicitBool = true;
      formatArg =
        value:
        if builtins.isAttrs value then
          builtins.toJSON value
        else
          lib.generators.mkValueStringDefault { } value;
    };
in
lib.cli.toCommandLine optionFormat {
  v = true;
  verbose = [
    true
    true
    false
    null
  ];
  n = false;
  output = "result.txt";
  testsuite = [
    "unit"
    "integration"
  ];
  data = {
    id = 0;
    name = "test";
  };
}
=> [
  "--data={\"id\":0,\"name\":\"test\"}"
  "-n"
  "false"
  "--output=result.txt"
  "--testsuite=unit"
  "--testsuite=integration"
  "-v"
  "true"
  "--verbose=true"
  "--verbose=true"
  "--verbose=false"
]

See also

  • lib.cli.toCommandLineShell
  • lib.cli.toCommandLineGNU
  • lib.cli.toCommandLineShellGNU

Located at lib/cli.nix:435 in <nixpkgs>.