symfony · chalasr · Jun 13, 2025 · Jun 12, 2025
@@ -564,6 +564,10 @@ public function addCommand(callable|Command $command): ?Command
                 ->setDescription($attribute->description ?? '')
                 ->setHelp($attribute->help ?? '')
                 ->setCode($command);
+
+            foreach ($attribute->usages as $usage) {
+                $command->addUsage($usage);
+            }
         }
 
         $command->setApplication($this);

@@ -25,13 +25,15 @@ class AsCommand
      * @param string[]    $aliases     The list of aliases of the command. The command will be executed when using one of them (i.e. "cache:clean")
      * @param bool        $hidden      If true, the command won't be shown when listing all the available commands, but it can still be run as any other command
      * @param string|null $help        The help content of the command, displayed with the help page
+     * @param string[]    $usages      The list of usage examples, displayed with the help page
      */
     public function __construct(
         public string $name,
         public ?string $description = null,
         array $aliases = [],
         bool $hidden = false,
         public ?string $help = null,
+        public array $usages = [],
     ) {
         if (!$hidden && !$aliases) {
             return;

@@ -8,6 +8,7 @@ CHANGELOG
  * Introduce `Symfony\Component\Console\Application::addCommand()` to simplify using invokable commands when the component is used standalone
  * Deprecate `Symfony\Component\Console\Application::add()` in favor of `Symfony\Component\Console\Application::addCommand()`
  * Add `BackedEnum` support with `#[Argument]` and `#[Option]` inputs in invokable commands
+ * Allow Usages to be specified via #[AsCommand] attribute.
 
 7.3
 ---

@@ -134,6 +134,10 @@ public function __construct(?string $name = null)
             $this->setHelp($attribute?->help ?? '');
         }
 
+        foreach ($attribute?->usages ?? [] as $usage) {
+            $this->addUsage($usage);
+        }
+
         if (\is_callable($this) && (new \ReflectionMethod($this, 'execute'))->getDeclaringClass()->name === self::class) {
             $this->code = new InvokableCommand($this, $this(...));
         }

@@ -91,6 +91,7 @@ public function process(ContainerBuilder $container): void
 
             $description = $tags[0]['description'] ?? null;
             $help = $tags[0]['help'] ?? null;
+            $usages = $tags[0]['usages'] ?? null;
 
             unset($tags[0]);
             $lazyCommandMap[$commandName] = $id;
@@ -108,6 +109,7 @@ public function process(ContainerBuilder $container): void
 
                 $description ??= $tag['description'] ?? null;
                 $help ??= $tag['help'] ?? null;
+                $usages ??= $tag['usages'] ?? null;
             }
 
             $definition->addMethodCall('setName', [$commandName]);
@@ -124,6 +126,12 @@ public function process(ContainerBuilder $container): void
                 $definition->addMethodCall('setHelp', [str_replace('%', '%%', $help)]);
             }
 
+            if ($usages) {
+                foreach ($usages as $usage) {
+                    $definition->addMethodCall('addUsage', [$usage]);
+                }
+            }
+
             if (!$description) {
                 if (Command::class !== (new \ReflectionMethod($class, 'getDefaultDescription'))->class) {
                     trigger_deprecation('symfony/console', '7.3', 'Overriding "Command::getDefaultDescription()" in "%s" is deprecated and will be removed in Symfony 8.0, use the #[AsCommand] attribute instead.', $class);

@@ -457,6 +457,8 @@ public function testCommandAttribute()
         $this->assertSame('foo', $command->getName());
         $this->assertSame('desc', $command->getDescription());
         $this->assertSame('help', $command->getHelp());
+        $this->assertCount(2, $command->getUsages());
+        $this->assertStringContainsString('usage1', $command->getUsages()[0]);
         $this->assertTrue($command->isHidden());
         $this->assertSame(['f'], $command->getAliases());
     }
@@ -542,7 +544,7 @@ function createClosure()
     };
 }
 
-#[AsCommand(name: 'foo', description: 'desc', hidden: true, aliases: ['f'], help: 'help')]
+#[AsCommand(name: 'foo', description: 'desc', usages: ['usage1', 'usage2'], hidden: true, aliases: ['f'], help: 'help')]
 class Php8Command extends Command
 {
 }

@@ -315,6 +315,7 @@ public function testProcessInvokableCommand()
         $definition->addTag('console.command', [
             'command' => 'invokable',
             'description' => 'The command description',
+            'usages' => ['usage1', 'usage2'],
             'help' => 'The %command.name% command help content.',
         ]);
         $container->setDefinition('invokable_command', $definition);
@@ -325,6 +326,8 @@ public function testProcessInvokableCommand()
         self::assertTrue($container->has('invokable_command.command'));
         self::assertSame('The command description', $command->getDescription());
         self::assertSame('The %command.name% command help content.', $command->getHelp());
+        self::assertCount(2, $command->getUsages());
+        $this->assertStringContainsString('usage1', $command->getUsages()[0]);
     }
 
     public function testProcessInvokableSignalableCommand()