Información general sobre la sintaxis: comandos, opciones y argumentos

2025-06-22

Importante

System.CommandLine actualmente está en versión preliminar y esta documentación es para la versión 2.0 beta 5. Cierta información se relaciona con el producto de versión preliminar que puede modificarse sustancialmente antes de su lanzamiento. Microsoft no ofrece ninguna garantía, expresa o implícita, con respecto a la información proporcionada aquí.

En este artículo se explica la sintaxis de la línea de comandos que System.CommandLine reconoce. La información es útil para los usuarios y desarrolladores de aplicaciones de línea de comandos de .NET, incluida la CLI de .NET.

Fichas

System.CommandLine analiza la entrada de la línea de comandos en tokens, que son cadenas delimitadas por espacios. Por ejemplo, considere la siguiente línea de comandos:

dotnet tool install dotnet-suggest --global --verbosity quiet

Esta entrada se analiza mediante la aplicación dotnet en tokens tool, install, dotnet-suggest, --global, --verbosity y quiet.

Los tokens se interpretan como comandos, opciones o argumentos. La aplicación de línea de comandos que se invoca determina cómo se interpretan los tokens después del primero. En la tabla siguiente se muestra cómo System.CommandLine interpreta el ejemplo anterior:

Seña	Analizado como
`tool`	Subcomando
`install`	Subcomando
`dotnet-suggest`	Argumento para el comando install
`--global`	Opción para el comando install
`--verbosity`	Opción para el comando install
`quiet`	Argumento de la opción `--verbosity`

Un token puede contener espacios si está entre comillas ("). Este es un ejemplo:

dotnet tool search "ef migrations add"

Órdenes

Un comando en la entrada de la línea de comandos es un token que especifica una acción o define un grupo de acciones relacionadas. Por ejemplo:

En dotnet run, run es un comando que especifica una acción.
En dotnet tool install, install es un comando que especifica una acción y tool es un comando que especifica un grupo de comandos relacionados. Hay otros comandos relacionados con herramientas, como tool uninstall, tool listy tool update.

Comando raíz

El comando raíz es el que especifica el nombre del ejecutable de la aplicación. Por ejemplo, el comando dotnet especifica el ejecutable dotnet.exe.

System.CommandLine.Command es la clase de uso general para cualquier comando o subcomando, mientras que System.CommandLine.RootCommand es una versión especializada destinada al punto de entrada raíz de la aplicación, heredando todas las características de pero agregando comportamientos y valores predeterminados específicos de System.CommandLine.Command la raíz, como la opción ayuda, la opción Versión y la directiva Suggest.

Subcomandos

La mayoría de las aplicaciones de línea de comandos admiten subcomandos, también conocidos como verbos. Por ejemplo, el dotnet comando tiene un run subcomando que se invoca escribiendo dotnet run.

Los subcomandos pueden tener sus propios subcomandos. En dotnet tool install, install es un subcomando de tool.

Puede agregar subcomandos como se muestra en el ejemplo siguiente:

RootCommand rootCommand = new();

Command sub1Command = new("sub1", "First-level subcommand");
rootCommand.Subcommands.Add(sub1Command);

Command sub1aCommand = new("sub1a", "Second level subcommand");
sub1Command.Subcommands.Add(sub1aCommand);

El subcomando más interno de este ejemplo se puede invocar de la siguiente manera:

myapp sub1 sub1a

Opciones

Una opción es un parámetro con nombre que se puede pasar a un comando. POSIX Normalmente, los CLIs prefijon el nombre de la opción con dos guiones (--). En el ejemplo siguiente se muestran dos opciones:

dotnet tool update dotnet-suggest --verbosity quiet --global
                                  ^---------^       ^------^

Como se muestra en este ejemplo, el valor de la opción puede ser explícito (quiet para --verbosity) o implícito (nada a continuación --global). Las opciones que no tienen ningún valor especificado suelen ser parámetros booleanos que tienen como valor predeterminado true si se especifica la opción en la línea de comandos.

Para algunas aplicaciones de línea de comandos de Windows, identifica una opción mediante una barra diagonal inicial (/) con el nombre de la opción. Por ejemplo:

msbuild /version
        ^------^

System.CommandLine admite convenciones de prefijo POSIX y Windows.

Al configurar una opción, especifique el nombre de la opción, incluido el prefijo:

Option<int> delayOption = new("--delay", "-d")
{
    Description = "An option whose argument is parsed as an int.",
    DefaultValueFactory = parseResult => 42,
};
Option<string> messageOption = new("--message", "-m")
{
    Description = "An option whose argument is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Options.Add(delayOption);
rootCommand.Options.Add(messageOption);

Para agregar una opción a un comando y de forma recursiva a todos sus subcomandos, use la System.CommandLine.Symbol.Recursive propiedad .

Opciones necesarias

Algunas opciones tienen argumentos necesarios. Por ejemplo, en la CLI de .NET, --output requiere un argumento de nombre de carpeta. Si no se proporciona el argumento , se produce un error en el comando. Para que sea necesaria una opción, establezca su System.CommandLine.Symbol.Required propiedad trueen , como se muestra en el ejemplo siguiente:

Option<FileInfo> fileOption = new("--output")
{
    Required = true
};

Si una opción necesaria tiene un valor predeterminado (especificado a través DefaultValueFactory de la propiedad ), la opción no tiene que especificarse en la línea de comandos. En ese caso, el valor predeterminado proporciona el valor de opción necesario.

Argumentos

Un argumento es un parámetro sin nombre que se puede pasar a un comando. En el ejemplo siguiente se muestra un argumento para el build comando .

dotnet build myapp.csproj
             ^----------^

Al configurar un argumento, se especifica el nombre del argumento (no se usa para el análisis, pero se puede usar para obtener valores analizados por nombre o mostrar ayuda) y escriba:

Argument<int> delayArgument = new("delay")
{
    Description = "An argument that is parsed as an int.",
    DefaultValueFactory = parseResult => 42
};
Argument<string> messageArgument = new("message")
{
    Description = "An argument that is parsed as a string."
};

RootCommand rootCommand = new();
rootCommand.Arguments.Add(delayArgument);
rootCommand.Arguments.Add(messageArgument);

Valores predeterminados

Ambos argumentos y opciones pueden tener valores predeterminados que se aplican si no se proporciona ningún argumento explícitamente. Por ejemplo, muchas opciones son parámetros booleanos implícitos con un valor predeterminado de true cuando el nombre de la opción aparece en la línea de comandos. Los siguientes ejemplos de línea de comandos son equivalentes:

dotnet tool update dotnet-suggest --global
                                  ^------^

dotnet tool update dotnet-suggest --global true
                                  ^-----------^

Un argumento definido sin un valor predeterminado se trata como argumento obligatorio.

Análisis de errores

Las opciones y los argumentos tienen tipos esperados y se produce un error cuando no se puede analizar el valor. Por ejemplo, los siguientes errores de comando porque "silent" no es uno de los valores válidos para --verbosity:

dotnet build --verbosity silent

Option<string> verbosityOption = new("--verbosity", "-v")
{
    Description = "Set the verbosity level.",
};
verbosityOption.AcceptOnlyFromAmong("quiet", "minimal", "normal", "detailed", "diagnostic");
RootCommand rootCommand = new() { verbosityOption };

ParseResult parseResult = rootCommand.Parse(args);
foreach (ParseError parseError in parseResult.Errors)
{
    Console.WriteLine(parseError.Message);
}

Argument 'silent' not recognized. Must be one of:
        'quiet'
        'minimal'
        'normal'
        'detailed'
        'diagnostic'

Los argumentos también tienen expectativas sobre cuántos valores se pueden proporcionar. En la sección sobre la aridad de argumentos se proporcionan ejemplos.

Orden de opciones y argumentos

Puede proporcionar opciones antes que argumentos o argumentos antes que opciones en la línea de comandos. Los siguientes comandos son equivalentes:

dotnet add package System.CommandLine --prerelease
dotnet add package --prerelease System.CommandLine

Las opciones se pueden especificar en cualquier orden. Los siguientes comandos son equivalentes:

dotnet add package System.CommandLine --prerelease --no-restore --source https://api.nuget.org/v3/index.json
dotnet add package System.CommandLine --source https://api.nuget.org/v3/index.json --no-restore --prerelease

Cuando hay varios argumentos, el orden importa. Los siguientes comandos no son equivalentes; difieren en el orden de los valores, lo que podría dar lugar a resultados diferentes:

myapp argument1 argument2
myapp argument2 argument1

Alias

En POSIX y Windows, es habitual que algunos comandos y opciones tengan alias. Normalmente son formularios cortos que son más fáciles de escribir. Los alias también se pueden usar con otros fines, como para simular la insensibilidad entre mayúsculas y minúsculas y para admitir ortografías alternativas de una palabra.

Las formas cortas de POSIX suelen tener un único guión inicial seguido de un solo carácter. Los siguientes comandos son equivalentes:

dotnet build --verbosity quiet
dotnet build -v quiet

El estándar GNU recomienda alias automáticos. Es decir, puede escribir cualquier parte de un nombre de opción o comando de formato largo, que se aceptará. Este comportamiento haría equivalente a las siguientes líneas de comandos:

dotnet publish --output ./publish
dotnet publish --outpu ./publish
dotnet publish --outp ./publish
dotnet publish --out ./publish
dotnet publish --ou ./publish
dotnet publish --o ./publish

System.CommandLine no admite alias automáticos. Cada alias debe especificarse explícitamente. Tanto los comandos como las opciones exponen una Aliases propiedad. Option tiene un constructor que acepta alias como parámetros, por lo que puede definir una opción con varios alias en una sola línea:

Option<bool> helpOption = new("--help", ["-h", "/h", "-?", "/?"]);
Command command = new("serialize") { helpOption };
command.Aliases.Add("serialise");

Se recomienda minimizar el número de alias de opción que defina y evitar definir determinados alias en particular. Para obtener más información, consulte Alias de formato corto.

Distinción entre mayúsculas y minúsculas

Los nombres de comandos y opciones y los alias distinguen mayúsculas de minúsculas de manera predeterminada según la convención POSIX, y System.CommandLine sigue esta convención. Si quiere que la CLI no distinga mayúsculas de minúsculas, defina alias para las distintas alternativas de uso de mayúsculas y minúsculas. Por ejemplo, --additional-probing-path podría tener alias --Additional-Probing-Path y --ADDITIONAL-PROBING-PATH.

En algunas herramientas de línea de comandos, una diferencia en el uso de mayúsculas y minúsculas especifica una diferencia de función. Por ejemplo, git clean -X se comporta de forma diferente a git clean -x. La CLI de .NET está escrita completamente en minúsculas.

La distinción entre mayúsculas y minúsculas no se aplica a los valores de argumento de las opciones basadas en enumeraciones. Los nombres de enumeraciones se emparejan independientemente del uso de mayúsculas y minúsculas.

El token `--`

La convención POSIX interpreta el token de guión doble (--) como un mecanismo de escape. Todo lo que sigue al token de guión doble se interpreta como argumentos del comando. Esta funcionalidad se puede usar para enviar argumentos que parecen opciones, ya que impide que se interpreten como opciones.

Supongamos que myapp toma un message argumento y quiere que el valor de message sea --interactive. La siguiente línea de comandos podría dar resultados inesperados.

myapp --interactive

Si myapp no tiene una --interactive opción, el --interactive token se interpreta como argumento. Pero si la aplicación tiene una --interactive opción, esta entrada se interpretará como referencia a esa opción.

La siguiente línea de comandos usa el token de guión doble para establecer el valor del argumento message en "--interactive":

myapp -- --interactive
      ^^

System.CommandLine admite esta funcionalidad de guion doble.

Delimitadores de argumento de opción

System.CommandLine permite usar un espacio, '=' o ':' como delimitador entre un nombre de opción y su argumento. Por ejemplo, los siguientes comandos son equivalentes:

dotnet build -v quiet
dotnet build -v=quiet
dotnet build -v:quiet

Una convención POSIX le permite omitir el delimitador cuando se especifica un alias de opción de un solo carácter. Por ejemplo, los siguientes comandos son equivalentes:

myapp -vquiet
myapp -v quiet

System.CommandLine admite esta sintaxis de forma predeterminada.

Aridad de los argumentos

La aridad de un argumento de opción o comando es el número de valores que se pueden pasar si se especifica esa opción o comando.

Arity se expresa con un valor mínimo y un valor máximo, como se muestra en la tabla siguiente:

Mín.	Máx.	Validez de ejemplo	Ejemplo
0	0	Válido:	--archivo
		No válido:	--file a.json
		No válido:	--file a.json --file b.json
0	1	Válido:	--bandera
		Válido:	--flag true
		Válido:	--flag false
		No válido:	--flag false --flag false
1	1	Válido:	--file a.json
		No válido:	--archivo
		No válido:	--file a.json --file b.json
0	n	Válido:	--archivo
		Válido:	--file a.json
		Válido:	--file a.json --file b.json
1	n	Válido:	--file a.json
		Válido:	--file a.json b.json
		No válido:	--archivo

System.CommandLine tiene una estructura System.CommandLine.ArgumentArity para definir la aridad con los siguientes valores:

System.CommandLine.ArgumentArity.Zero - No se admiten valores.
System.CommandLine.ArgumentArity.ZeroOrOne - Puede tener un valor, puede que no tenga valores.
System.CommandLine.ArgumentArity.ExactlyOne - Debe tener un valor.
System.CommandLine.ArgumentArity.ZeroOrMore - Puede tener un valor, varios valores o ningún valor.
System.CommandLine.ArgumentArity.OneOrMore - Puede tener varios valores, debe tener al menos un valor.

Puede establecer explícitamente la aridad mediante la propiedad , pero en la Arity mayoría de los casos que no es necesario. System.CommandLine determina automáticamente la aridad del argumento en función del tipo de argumento:

Tipo de argumento	Aridad predeterminada
`Boolean`	`ArgumentArity.ZeroOrOne`
Tipos de colección	`ArgumentArity.ZeroOrMore`
Todo lo demás	`ArgumentArity.ExactlyOne`

Invalidaciones de opciones

Si la aridad máxima es 1, System.CommandLine todavía se puede configurar para aceptar varias instancias de una opción. En ese caso, la última instancia de una opción repetida sobrescribe las instancias anteriores. En el ejemplo siguiente, el valor 2 se pasaría al myapp comando .

myapp --delay 3 --message example --delay 2

Varios argumentos

De forma predeterminada, al llamar a un comando, puede repetir un nombre de opción para especificar varios argumentos para una opción que tenga una aridad máxima mayor que una.

myapp --items one --items two --items three

Para permitir varios argumentos sin repetir el nombre de la opción, establezca en System.CommandLine.Option.AllowMultipleArgumentsPerTokentrue. Esta configuración le permite escribir la siguiente línea de comandos.

myapp --items one two three

La misma configuración tiene un efecto diferente si la aridad máxima del argumento es 1. Permite repetir una opción, pero solo toma el último valor de la línea. En el ejemplo siguiente, el valor three se pasaría a la aplicación.

myapp --item one --item two --item three

Agrupación de opciones

POSIX recomienda que admita la agrupación de opciones de un solo carácter, también conocida como apilamiento. Las opciones agrupadas son alias de opción de un solo carácter especificados juntos tras un prefijo de un solo guion. Solo la última opción puede especificar un argumento. Por ejemplo, las siguientes líneas de comandos son equivalentes:

git clean -f -d -x
git clean -fdx

Si se proporciona un argumento después de una agrupación de opciones, se aplica a la última opción del lote. Las siguientes líneas de comandos son equivalentes:

myapp -a -b -c arg
myapp -abc arg

En ambas variantes de este ejemplo, el argumento arg solo se aplicaría a la opción -c.

Opciones booleanas (marcas)

Si true o false se pasa a una opción que tiene un argumento bool, se analiza según lo previsto. Pero una opción cuyo tipo de argumento normalmente bool no requiere que se especifique un argumento. Las opciones booleanas, a veces conocidas como "marcas", suelen tener una aridad de System.CommandLine.ArgumentArity.ZeroOrOne. La presencia del nombre de opción en la línea de comandos, sin ningún argumento después, da como resultado un valor predeterminado de true. La ausencia del nombre de opción en la entrada de la línea de comandos da como resultado un valor de false. Si el myapp comando imprime el valor de una opción booleana denominada --interactive, la entrada siguiente crea la siguiente salida:

myapp
myapp --interactive
myapp --interactive false
myapp --interactive true

False
True
False
True

Opción De versión

Las aplicaciones basadas en System.CommandLine proporcionan automáticamente el número de versión en respuesta a la --version opción usada con el comando raíz. Por ejemplo:

dotnet --version

6.0.100

Archivos de respuesta

Un archivo de respuesta es un archivo que contiene un conjunto de tokens para una aplicación de línea de comandos. Los archivos de respuesta son una característica de System.CommandLine que resulta útil en dos escenarios:

Para invocar una aplicación de línea de comandos especificando la entrada más larga que el límite de caracteres del terminal.
Para invocar al mismo comando repetidamente sin volver a escribir toda la línea.

Para usar un archivo de respuesta, escriba el nombre de archivo con el prefijo @ en el lugar de la línea donde quiera insertar comandos, opciones y argumentos. La extensión de archivo .rsp es una convención común, pero puede usar cualquier extensión de archivo.

Las líneas siguientes son equivalentes:

dotnet build --no-restore --output ./build-output/
dotnet @sample1.rsp
dotnet build @sample2.rsp --output ./build-output/

Contenido de sample1.rsp:

build
--no-restore
--output
./build-output/

Contenido de sample2.rsp:

--no-restore

Estas son las reglas de sintaxis que determinan cómo se interpreta el texto de un archivo de respuesta:

Los tokens se delimitan por espacios. Una línea que contiene Buenos días se trata como dos tokens, Buenos y días.
Varios tokens entre comillas se interpretan como un solo token. Una línea que contiene "Buenas mañanas!" se trata como un token, ¡Buenos días!.
Cualquier texto entre un # símbolo y el final de la línea se trata como comentario y se omite.
Los tokens con @ prefijo pueden hacer referencia a archivos de respuesta adicionales.
El archivo de respuesta puede tener varias líneas de texto. Las líneas se concatenan y se interpretan como una secuencia de tokens.

Directivas

System.CommandLine presenta un elemento sintáctico denominado directiva representada por System.CommandLine.Directive tipo. La [diagram] directiva es un ejemplo. Cuando incluyas [diagram] después del nombre de la aplicación, System.CommandLine muestra un diagrama del resultado de análisis en lugar de invocar la aplicación de línea de comandos:

dotnet [diagram] build --no-restore --output ./build-output/
       ^-----^

[ dotnet [ build [ --no-restore <True> ] [ --output <./build-output/> ] ] ]

El propósito de las directivas es proporcionar funcionalidad transversal que se puede aplicar a través de aplicaciones de línea de comandos. Dado que las directivas son sintácticamente distintas de la propia sintaxis de la aplicación, pueden proporcionar funcionalidad que se aplica en todas las aplicaciones.

Una directiva debe cumplir las siguientes reglas de sintaxis:

Es un token en la línea de comandos que viene después del nombre de la aplicación, pero antes de cualquier subcomando o opciones.
Está entre corchetes.
No contiene espacios.

Se omite una directiva no reconocida sin provocar un error de análisis.

Una directiva puede incluir un argumento, separado del nombre de la directiva por dos puntos.

Las siguientes directivas están integradas:

[diagram]
[suggest]

Directiva `[diagram]`

Tanto los usuarios como los desarrolladores pueden resultar útiles para ver cómo una aplicación interpretará una entrada determinada. Una de las características predeterminadas de una System.CommandLine aplicación es la [diagram] directiva, que permite obtener una vista previa del resultado de analizar el comando de entrada. Por ejemplo:

myapp [diagram] --delay not-an-int --interactive --file filename.txt extra

![ myapp [ --delay !<not-an-int> ] [ --interactive <True> ] [ --file <filename.txt> ] *[ --fgcolor <White> ] ]   ???--> extra

En el ejemplo anterior:

El comando (myapp), sus opciones secundarias y los argumentos de esas opciones se agrupan mediante corchetes.
Para el resultado de la opción [ --delay !<not-an-int> ], ! indica un error de análisis. El valor not-an-int de una int opción no se puede analizar en el tipo esperado. El error también se marca mediante ! delante del comando que contiene la opción errónea: ![ myapp....
Para el resultado *[ --fgcolor <White> ]de la opción , la opción no se especificó en la línea de comandos, por lo que se usó el valor predeterminado configurado. White es el valor efectivo de esta opción. El asterisco indica que el valor es el valor predeterminado.
???--> apunta a la entrada que no coincide con ninguno de los comandos o opciones de la aplicación.

Directiva Suggest

La [suggest] directiva le permite buscar comandos cuando no conoce el comando exacto.

dotnet [suggest] buil

build
build-server
msbuild