docs: add autogenerated cli actions docs

.github/workflows/warn-autogenerated-files.yaml

@@ -7,6 +7,7 @@ on:
     paths:
       - docs/config/reference.mdx
       - docs/config/keybind/reference.mdx
+      - docs/features/commands.mdx
 
 name: Autogenerated files check
 

docs/features/commands.mdx

@@ -0,0 +1,228 @@
+---
+title: Reference
+description: Reference of all Ghostty action subcommands.
+editOnGithubLink: https://github.com/ghostty-org/ghostty/tree/main/src/cli
+---
+Ghostty includes a number of utility actions that can be accessed as subcommands.
+Actions provide utilities to work with config, list keybinds, list fonts, demo themes,
+and debug.
+## version
+The `version` command is used to display information about Ghostty. Recognized as
+either `+version` or `--version`.
+
+```
+ghostty --version
+```
+
+## help
+The `help` command shows general help about Ghostty. Recognized as either
+`-h, `--help`, or like other actions `+help`.
+
+You can also specify `--help` or `-h` along with any action such as
+`+list-themes` to see help for a specific action.
+
+```
+ghostty --help
+```
+
+## list-fonts
+The `list-fonts` command is used to list all the available fonts for
+Ghostty. This uses the exact same font discovery mechanism Ghostty uses to
+find fonts to use.
+
+When executed with no arguments, this will list all available fonts, sorted
+by family name, then font name. If a family name is given with `--family`,
+the sorting will be disabled and the results instead will be shown in the
+same priority order Ghostty would use to pick a font.
+
+Flags:
+
+  * `--bold`: Filter results to specific bold styles. It is not guaranteed
+    that only those styles are returned. They are only prioritized.
+
+  * `--italic`: Filter results to specific italic styles. It is not guaranteed
+    that only those styles are returned. They are only prioritized.
+
+  * `--style`: Filter results based on the style string advertised by a font.
+    It is not guaranteed that only those styles are returned. They are only
+    prioritized.
+
+  * `--family`: Filter results to a specific font family. The family handling
+    is identical to the `font-family` set of Ghostty configuration values, so
+    this can be used to debug why your desired font may not be loading.
+
+```
+ghostty +list-fonts
+```
+
+## list-keybinds
+The `list-keybinds` command is used to list all the available keybinds for
+Ghostty.
+
+When executed without any arguments this will list the current keybinds
+loaded by the config file. If no config file is found or there aren't any
+changes to the keybinds it will print out the default ones configured for
+Ghostty
+
+Flags:
+
+  * `--default`: will print out all the default keybinds
+
+  * `--docs`: currently does nothing, intended to print out documentation
+    about the action associated with the keybinds
+
+  * `--plain`: will disable formatting and make the output more
+    friendly for Unix tooling. This is default when not printing to a tty.
+
+```
+ghostty +list-keybinds
+```
+
+## list-themes
+The `list-themes` command is used to preview or list all the available
+themes for Ghostty.
+
+If this command is run from a TTY, a TUI preview of the themes will be
+shown. While in the preview, `F1` will bring up a help screen and `ESC` will
+exit the preview. Other keys that can be used to navigate the preview are
+listed in the help screen.
+
+If this command is not run from a TTY, or the output is piped to another
+command, a plain list of theme names will be printed to the screen. A plain
+list can be forced using the `--plain` CLI flag.
+
+Two different directories will be searched for themes.
+
+The first directory is the `themes` subdirectory of your Ghostty
+configuration directory. This is `$XDG_CONFIG_DIR/ghostty/themes` or
+`~/.config/ghostty/themes`.
+
+The second directory is the `themes` subdirectory of the Ghostty resources
+directory. Ghostty ships with a multitude of themes that will be installed
+into this directory. On macOS, this directory is the
+`Ghostty.app/Contents/Resources/ghostty/themes`. On Linux, this directory
+is the `share/ghostty/themes` (wherever you installed the Ghostty "share"
+directory). If you're running Ghostty from the source, this is the
+`zig-out/share/ghostty/themes` directory.
+
+You can also set the `GHOSTTY_RESOURCES_DIR` environment variable to point
+to the resources directory.
+
+Flags:
+
+  * `--path`: Show the full path to the theme.
+
+  * `--plain`: Force a plain listing of themes.
+
+```
+ghostty +list-themes
+```
+
+## list-colors
+The `list-colors` command is used to list all the named RGB colors in
+Ghostty.
+
+```
+ghostty +list-colors
+```
+
+## list-actions
+The `list-actions` command is used to list all the available keybind
+actions for Ghostty. These are distinct from the CLI Actions which can
+be listed via `+help`
+
+Flags:
+
+  * `--docs`: will print out the documentation for each action.
+
+```
+ghostty +list-actions
+```
+
+## show-config
+The `show-config` command shows the current configuration in a valid Ghostty
+configuration file format.
+
+When executed without any arguments this will output the current
+configuration that is different from the default configuration. If you're
+using the default configuration this will output nothing.
+
+If you are a new user and want to see all available options with
+documentation, run `ghostty +show-config --default --docs`.
+
+The output is not in any specific order, but the order should be consistent
+between runs. The output is not guaranteed to be exactly match the input
+configuration files, but it will result in the same behavior. Comments,
+whitespace, and other formatting is not preserved from user configuration
+files.
+
+Flags:
+
+  * `--default`: Show the default configuration instead of loading
+    the user configuration.
+
+  * `--changes-only`: Only show the options that have been changed
+    from the default. This has no effect if `--default` is specified.
+
+  * `--docs`: Print the documentation above each option as a comment,
+    This is very noisy but is very useful to learn about available
+    options, especially paired with `--default`.
+
+```
+ghostty +show-config
+```
+
+## validate-config
+The `validate-config` command is used to validate a Ghostty config file.
+
+When executed without any arguments, this will load the config from the default
+location.
+
+Flags:
+
+  * `--config-file`: can be passed to validate a specific target config file in
+    a non-default location
+
+```
+ghostty +validate-config
+```
+
+## show-face
+The `show-face` command shows what font face Ghostty will use to render a
+specific codepoint. Note that this command does not take into consideration
+grapheme clustering or any other Unicode features that might modify the
+presentation of a codepoint, so this may show a different font face than
+Ghostty uses to render a codepoint in a terminal session.
+
+Flags:
+
+  * `--cp`: Find the face for a single codepoint. The codepoint may be specified
+    in decimal (`--cp=65`), hexadecimal (`--cp=0x41`), octal (`--cp=0o101`), or
+    binary (`--cp=0b1000001`).
+
+  * `--string`: Find the face for all of the codepoints in a string. The
+    string must be a valid UTF-8 sequence.
+
+  * `--style`: Search for a specific style. Valid options are `regular`, `bold`,
+    `italic`, and `bold_italic`.
+
+  * `--presentation`: If set, force searching for a specific presentation
+    style. Valid options are `text` and `emoji`. If unset, the presentation
+    style of a codepoint will be inferred from the Unicode standard.
+
+```
+ghostty +show-face
+```
+
+## crash-report
+The `crash-report` command is used to inspect and send crash reports.
+
+When executed without any arguments, this will list existing crash reports.
+
+This command currently only supports listing crash reports. Viewing
+and sending crash reports is unimplemented and will be added in the future.
+
+```
+ghostty +crash-report
+```
+

docs/nav.json

@@ -93,6 +93,11 @@
           "path": "/",
           "title": "Overview"
         },
+        {
+          "type": "link",
+          "path": "/commands",
+          "title": "CLI Actions"
+        },
         {
           "type": "link",
           "path": "/theme",