@-files (Response File Parsing)

CommandLineUtils support parsing of response files. The command-line parser treats arguments beginning with '@' as a file path to a response file.

myapp.exe @args.txt

A response file contains additional arguments that will be treated as if they were passed in on the command line.

• Response files can have comments that begin with the # symbol.
• You cannot use the backslash character (\) to concatenate lines.

By default, response file parsing is disabled for your application and all sub-commands. You can enable response file parsing using either the Builder API or Attributes.

• Using Attributes
• Using Builder API

When using Attributes, you can enable response file parsing by setting the ResponseFileHandling property of the CommandAttribute.

[Command(Name = "done", Description = "Keep track on things you've done", ResponseFileHandling = ResponseFileHandling.ParseArgsAsLineSeparated)]
[Subcommand(typeof(ListCommand))]
class Program
{
    public static int Main(string[] args) => CommandLineApplication.Execute<Program>(args);

    [Argument(0, "The description of what you've done")]
    public string Description { get; }

    [Option(CommandOptionType.MultipleValue, LongName = "tag", Description = "A tag for the item")]
    public string[] Tags { get; }

    private void OnExecute()
    {
        //...
    }
}

[Command(Description = "List all done items", ResponseFileHandling = ResponseFileHandling.ParseArgsAsLineSeparated)]
class ListCommand
{
    [Option(CommandOptionType.MultipleValue, LongName = "tag", Description = "Only list items with the corresponding tag(s)")]
    public string[] Tags { get; }

    private void OnExecute()
    {
        //...
    }
}

In the example above, the ResponseFileHandling property has been set to ResponseFileHandling.ParseArgsAsLineSeparated meaning that each argument or option will be on its own line.

Let's assume that you want to run the application with the following command:

done "Completed the Boston marathon" --tag major --tag fitness

You can achieve the same result by creating a file called input.txt with the following contents:

Completed the Boston marathon
--tag
major
--tag
fitness

And then passing that file on the command-line instead:

done @input.txt

Using in combination with sub-commands

You can specify sub-commands in the response file, and CommandLineUtils will execute the correct sub-command. Given the previous code sample, when passing the following response file

list
--tag
major
--tag
fitness

The list command will be executed, and the values of major and fitness will be passed for the Tags option.

Combining response files with arguments

You can pass a combination of command-line arguments and response files. For example, you can specify the following response file:

--tag
major
--tag
fitness

And then pass that in combination with other command-line arguments, e.g.:

done "Completed the Boston marathon" @input.txt

This would be the equivalent of executing

done "Completed the Boston marathon" --tag major --tag fitness

You can also use it in combination with sub-commands:

done list @input.txt

This will execute the list command and pass the values of major and fitness for the Tags option.

When using sub-commands, you need to take care to explicitly set the ResponseFileHandling property for the sub-commands as well.

• Using Attributes
• Using Builder API

[Command(Name = "done", Description = "Keep track on things you've done", ResponseFileHandling = ResponseFileHandling.ParseArgsAsLineSeparated)]
[Subcommand(typeof(ListCommand))]
class Program
{
    public static int Main(string[] args) => CommandLineApplication.Execute<Program>(args);

    [Argument(0, "The description of what you've done")]
    public string Description { get; }

    [Option(CommandOptionType.MultipleValue, LongName = "tag", Description = "A tag for the item")]
    public string[] Tags { get; }

    private void OnExecute()
    {
        //...
    }
}

[Command(Description = "List all done items", ResponseFileHandling = ResponseFileHandling.ParseArgsAsLineSeparated)]
class ListCommand
{
    [Option(CommandOptionType.MultipleValue, LongName = "tag", Description = "Only list items with the corresponding tag(s)")]
    public string[] Tags { get; }

    private void OnExecute()
    {
        //...
    }
}

Space separated arguments

You can set the ResponseFileHandling property to ParseArgsAsSpaceSeparated. In this case, each argument in the response file needs to be separated by a space, instead of a new line, e.g.

"Completed the Boston marathon" --tag major --tag fitness