Add CLI Command
Developmentadd-cli-commandAdd CLI Command is an Agent Skill for development published in the dotnet/dotnet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Add or change a dotnet CLI command, subcommand, or option across the relevant CLI projects. USE FOR: adding or changing a dotnet CLI command/subcommand, adding a new Option<T> or Argument<T>, registering a subcommand in the command tree, changing an option's help description or a command's runtime message, wiring a command parser, or updating --help output.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/dotnet/dotnet/blob/HEAD/src/sdk/.github/skills/add-cli-command/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/add-cli-command, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Add or change a dotnet CLI command or option
See references/file-map.md for the exact file map and the
two-resx reference table. Read it before editing.
Add an option to an existing command
-
Declare the option in
src/Cli/Microsoft.DotNet.Cli.Definitions/Commands/<Area>/<Name>CommandDefinition.cs. Prefer aCommonOptionsfactory (Common/CommonOptions.cs) when one exists:public readonly Option<bool> NoLogoOption = CommonOptions.CreateNoLogoOption(); // or, declared inline: public readonly Option<string> OutputOption = new Option<string>("--output", "-o") { Description = CommandDefinitionStrings.BuildOutputOptionDescription };Add it to the command in the constructor:
Options.Add(OutputOption);. -
Consume it in the managed implementation under
src/Cli/dotnet/Commands/<Area>/...viadefinition.OutputOption; runtime messages come fromCliCommandStrings.<Key>. -
Strings: add the help description to
CommandDefinitionStrings.resxand any runtime message toCliCommandStrings.resx, then regenerate the.xlfsiblings. -
Test: add parser/validation tests under
test/dotnet.Tests/CommandTests/<Area>/and update any Verify help snapshots.
Add a new command
Everything above, plus:
-
Create
Commands/<Area>/<Name>CommandDefinition.csin the Definitions project. -
Register it in the root tree (
Commands/DotNetCommandDefinition.csconstructor):Subcommands.Add(<Name>Command = new()); -
Create the managed implementation and a
<Name>CommandParser.csexposingConfigureCommand(...)undersrc/Cli/dotnet/Commands/<Name>/. -
Wire the parser in
src/Cli/dotnet/Parser.csConfigureManagedActions:<Name>CommandParser.ConfigureCommand(rootCommand.<Name>Command);
Native AOT: a newly registered command already runs under Native AOT via the managed fallback (the
dotnet-aothost runsdotnet.dllthrough hostfxr), and its parsing and--helpreach the AOT CLI for free. Making the command execute in-process in the native binary is separate, deliberate work — follow the add-dotnet-aot-command skill when AOT support is required.
Checklist
- Option/command declared in
Definitions, registered in its parent's constructor. - Managed behavior wired in
src/Cli/dotnetand (for new commands) inParser.cs. - Help description in
CommandDefinitionStrings.resx; runtime message inCliCommandStrings.resx. -
.xlffiles regenerated via/t:UpdateXlf(not hand-edited), resx + xlf committed together. - No heavy dependency leaked into
Definitions. - For in-process AOT execution, followed add-dotnet-aot-command (managed fallback applies otherwise).
- Tests added/updated; Verify
*.verified.txtsnapshots promoted if CLI output changed.