From 6515ac25daad6430b4fc6c07a44446d42d6e1cc9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= <zbyszek@amutable.com>
Date: Sat, 15 Aug 2026 12:51:02 +0200
Subject: [PATCH] escape: convert to VERB_COMMAND and add --introspect-cli

The custom help() is replaced by a COMMAND() description, and
--introspect-cli is added. The synopsis is updated to be more truthful
and consistent between the prog and man page.
---
 man/systemd-escape.xml                        |  7 ++-
 src/escape/escape-tool.c                      | 43 ++++++-------------
 .../units/TEST-74-AUX-UTILS.introspect-cli.sh |  1 +
 3 files changed, 20 insertions(+), 31 deletions(-)

diff --git a/man/systemd-escape.xml b/man/systemd-escape.xml
index 7a0fd062cf..b0d77aec69 100644
--- a/man/systemd-escape.xml
+++ b/man/systemd-escape.xml
@@ -25,7 +25,12 @@
     <cmdsynopsis>
       <command>systemd-escape</command>
       <arg choice="opt" rep="repeat">OPTIONS</arg>
-      <arg choice="opt" rep="repeat">STRING</arg>
+      <arg choice="plain" rep="repeat">STRING</arg>
+    </cmdsynopsis>
+    <cmdsynopsis>
+      <command>systemd-escape</command>
+      <arg choice="opt" rep="repeat">OPTIONS</arg>
+      <arg choice="plain"><option>--stdin</option></arg>
     </cmdsynopsis>
   </refsynopsisdiv>
 
diff --git a/src/escape/escape-tool.c b/src/escape/escape-tool.c
index faeeb02dd8..8446528d11 100644
--- a/src/escape/escape-tool.c
+++ b/src/escape/escape-tool.c
@@ -2,19 +2,19 @@
 
 #include <stdio.h>
 
+#include "sd-json.h"
+
 #include "alloc-util.h"
 #include "build.h"
 #include "fileio.h"
-#include "format-table.h"
 #include "log.h"
 #include "main-func.h"
-#include "options.h"
 #include "path-util.h"
-#include "pretty-print.h"
 #include "string-util.h"
 #include "strv.h"
 #include "unit-def.h"
 #include "unit-name.h"
+#include "verbs.h"
 
 static enum {
         ACTION_ESCAPE,
@@ -27,32 +27,12 @@ static bool arg_path = false;
 static bool arg_instance = false;
 static bool arg_stdin = false;
 
-static int help(void) {
-        _cleanup_free_ char *link = NULL;
-        _cleanup_(table_unrefp) Table *options = NULL;
-        int r;
-
-        r = terminal_urlify_man("systemd-escape", "1", &link);
-        if (r < 0)
-                return log_oom();
-
-        r = option_parser_get_help_table(&options);
-        if (r < 0)
-                return r;
-
-        printf("%s [OPTIONS...] [NAME...]\n\n"
-               "%sEscape strings for usage in systemd unit names.%s\n\n",
-               program_invocation_short_name,
-               ansi_highlight(),
-               ansi_normal());
-
-        r = table_print_or_warn(options);
-        if (r < 0)
-                return r;
-
-        printf("\nSee the %s for details.\n", link);
-        return 0;
-}
+COMMAND(
+        "systemd-escape\0",
+        "Escape strings for usage in systemd unit names.",
+        .argspec = "STRING…\0" "--stdin\0",
+        .man_pages = "systemd-escape.1\0",
+);
 
 static int parse_argv(int argc, char *argv[], char ***ret_args) {
         assert(argc >= 0);
@@ -64,7 +44,7 @@ static int parse_argv(int argc, char *argv[], char ***ret_args) {
                 switch (c) {
 
                 OPTION_COMMON_HELP:
-                        return help();
+                        return command_print_help("systemd-escape");
 
                 OPTION_COMMON_VERSION:
                         return version();
@@ -106,6 +86,9 @@ static int parse_argv(int argc, char *argv[], char ***ret_args) {
                        "When escaping/unescaping assume the string is a path"):
                         arg_path = true;
                         break;
+
+                OPTION_COMMON_INTROSPECT_CLI:
+                        return introspect_cli(SD_JSON_FORMAT_OFF);
                 }
 
         if (arg_stdin && option_parser_get_n_args(&opts) > 0)
diff --git a/test/units/TEST-74-AUX-UTILS.introspect-cli.sh b/test/units/TEST-74-AUX-UTILS.introspect-cli.sh
index ff8deae964..b2b8e47dc1 100755
--- a/test/units/TEST-74-AUX-UTILS.introspect-cli.sh
+++ b/test/units/TEST-74-AUX-UTILS.introspect-cli.sh
@@ -24,6 +24,7 @@ INTROSPECTABLE=(
     systemd-delta
     systemd-detect-virt
     systemd-dissect
+    systemd-escape
     systemd-firstboot
     systemd-hwdb
     systemd-id128