Skip to content

Commit 2accb8f

Browse files
anundanund
committed
docs: add autogenerated cli actions docs
1 parent 202578f commit 2accb8f

File tree

3 files changed

+234
-0
lines changed

3 files changed

+234
-0
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ on:
77
paths:
88
- docs/config/reference.mdx
99
- docs/config/keybind/reference.mdx
10+
- docs/features/commands.mdx
1011

1112
name: Autogenerated files check
1213

‎docs/features/commands.mdx‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
---
2+
title: Reference
3+
description: Reference of all Ghostty action subcommands.
4+
editOnGithubLink: https://github.com/ghostty-org/ghostty/tree/main/src/cli
5+
---
6+
Ghostty includes a number of utility actions that can be accessed as subcommands.
7+
Actions provide utilities to work with config, list keybinds, list fonts, demo themes,
8+
and debug.
9+
## version
10+
The `version` command is used to display information about Ghostty. Recognized as
11+
either `+version` or `--version`.
12+
13+
```
14+
ghostty --version
15+
```
16+
17+
## help
18+
The `help` command shows general help about Ghostty. Recognized as either
19+
`-h, `--help`, or like other actions `+help`.
20+
21+
You can also specify `--help` or `-h` along with any action such as
22+
`+list-themes` to see help for a specific action.
23+
24+
```
25+
ghostty --help
26+
```
27+
28+
## list-fonts
29+
The `list-fonts` command is used to list all the available fonts for
30+
Ghostty. This uses the exact same font discovery mechanism Ghostty uses to
31+
find fonts to use.
32+
33+
When executed with no arguments, this will list all available fonts, sorted
34+
by family name, then font name. If a family name is given with `--family`,
35+
the sorting will be disabled and the results instead will be shown in the
36+
same priority order Ghostty would use to pick a font.
37+
38+
Flags:
39+
40+
* `--bold`: Filter results to specific bold styles. It is not guaranteed
41+
that only those styles are returned. They are only prioritized.
42+
43+
* `--italic`: Filter results to specific italic styles. It is not guaranteed
44+
that only those styles are returned. They are only prioritized.
45+
46+
* `--style`: Filter results based on the style string advertised by a font.
47+
It is not guaranteed that only those styles are returned. They are only
48+
prioritized.
49+
50+
* `--family`: Filter results to a specific font family. The family handling
51+
is identical to the `font-family` set of Ghostty configuration values, so
52+
this can be used to debug why your desired font may not be loading.
53+
54+
```
55+
ghostty +list-fonts
56+
```
57+
58+
## list-keybinds
59+
The `list-keybinds` command is used to list all the available keybinds for
60+
Ghostty.
61+
62+
When executed without any arguments this will list the current keybinds
63+
loaded by the config file. If no config file is found or there aren't any
64+
changes to the keybinds it will print out the default ones configured for
65+
Ghostty
66+
67+
Flags:
68+
69+
* `--default`: will print out all the default keybinds
70+
71+
* `--docs`: currently does nothing, intended to print out documentation
72+
about the action associated with the keybinds
73+
74+
* `--plain`: will disable formatting and make the output more
75+
friendly for Unix tooling. This is default when not printing to a tty.
76+
77+
```
78+
ghostty +list-keybinds
79+
```
80+
81+
## list-themes
82+
The `list-themes` command is used to preview or list all the available
83+
themes for Ghostty.
84+
85+
If this command is run from a TTY, a TUI preview of the themes will be
86+
shown. While in the preview, `F1` will bring up a help screen and `ESC` will
87+
exit the preview. Other keys that can be used to navigate the preview are
88+
listed in the help screen.
89+
90+
If this command is not run from a TTY, or the output is piped to another
91+
command, a plain list of theme names will be printed to the screen. A plain
92+
list can be forced using the `--plain` CLI flag.
93+
94+
Two different directories will be searched for themes.
95+
96+
The first directory is the `themes` subdirectory of your Ghostty
97+
configuration directory. This is `$XDG_CONFIG_DIR/ghostty/themes` or
98+
`~/.config/ghostty/themes`.
99+
100+
The second directory is the `themes` subdirectory of the Ghostty resources
101+
directory. Ghostty ships with a multitude of themes that will be installed
102+
into this directory. On macOS, this directory is the
103+
`Ghostty.app/Contents/Resources/ghostty/themes`. On Linux, this directory
104+
is the `share/ghostty/themes` (wherever you installed the Ghostty "share"
105+
directory). If you're running Ghostty from the source, this is the
106+
`zig-out/share/ghostty/themes` directory.
107+
108+
You can also set the `GHOSTTY_RESOURCES_DIR` environment variable to point
109+
to the resources directory.
110+
111+
Flags:
112+
113+
* `--path`: Show the full path to the theme.
114+
115+
* `--plain`: Force a plain listing of themes.
116+
117+
```
118+
ghostty +list-themes
119+
```
120+
121+
## list-colors
122+
The `list-colors` command is used to list all the named RGB colors in
123+
Ghostty.
124+
125+
```
126+
ghostty +list-colors
127+
```
128+
129+
## list-actions
130+
The `list-actions` command is used to list all the available keybind
131+
actions for Ghostty. These are distinct from the CLI Actions which can
132+
be listed via `+help`
133+
134+
Flags:
135+
136+
* `--docs`: will print out the documentation for each action.
137+
138+
```
139+
ghostty +list-actions
140+
```
141+
142+
## show-config
143+
The `show-config` command shows the current configuration in a valid Ghostty
144+
configuration file format.
145+
146+
When executed without any arguments this will output the current
147+
configuration that is different from the default configuration. If you're
148+
using the default configuration this will output nothing.
149+
150+
If you are a new user and want to see all available options with
151+
documentation, run `ghostty +show-config --default --docs`.
152+
153+
The output is not in any specific order, but the order should be consistent
154+
between runs. The output is not guaranteed to be exactly match the input
155+
configuration files, but it will result in the same behavior. Comments,
156+
whitespace, and other formatting is not preserved from user configuration
157+
files.
158+
159+
Flags:
160+
161+
* `--default`: Show the default configuration instead of loading
162+
the user configuration.
163+
164+
* `--changes-only`: Only show the options that have been changed
165+
from the default. This has no effect if `--default` is specified.
166+
167+
* `--docs`: Print the documentation above each option as a comment,
168+
This is very noisy but is very useful to learn about available
169+
options, especially paired with `--default`.
170+
171+
```
172+
ghostty +show-config
173+
```
174+
175+
## validate-config
176+
The `validate-config` command is used to validate a Ghostty config file.
177+
178+
When executed without any arguments, this will load the config from the default
179+
location.
180+
181+
Flags:
182+
183+
* `--config-file`: can be passed to validate a specific target config file in
184+
a non-default location
185+
186+
```
187+
ghostty +validate-config
188+
```
189+
190+
## show-face
191+
The `show-face` command shows what font face Ghostty will use to render a
192+
specific codepoint. Note that this command does not take into consideration
193+
grapheme clustering or any other Unicode features that might modify the
194+
presentation of a codepoint, so this may show a different font face than
195+
Ghostty uses to render a codepoint in a terminal session.
196+
197+
Flags:
198+
199+
* `--cp`: Find the face for a single codepoint. The codepoint may be specified
200+
in decimal (`--cp=65`), hexadecimal (`--cp=0x41`), octal (`--cp=0o101`), or
201+
binary (`--cp=0b1000001`).
202+
203+
* `--string`: Find the face for all of the codepoints in a string. The
204+
string must be a valid UTF-8 sequence.
205+
206+
* `--style`: Search for a specific style. Valid options are `regular`, `bold`,
207+
`italic`, and `bold_italic`.
208+
209+
* `--presentation`: If set, force searching for a specific presentation
210+
style. Valid options are `text` and `emoji`. If unset, the presentation
211+
style of a codepoint will be inferred from the Unicode standard.
212+
213+
```
214+
ghostty +show-face
215+
```
216+
217+
## crash-report
218+
The `crash-report` command is used to inspect and send crash reports.
219+
220+
When executed without any arguments, this will list existing crash reports.
221+
222+
This command currently only supports listing crash reports. Viewing
223+
and sending crash reports is unimplemented and will be added in the future.
224+
225+
```
226+
ghostty +crash-report
227+
```
228+

‎docs/nav.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,11 @@
9393
"path": "/",
9494
"title": "Overview"
9595
},
96+
{
97+
"type": "link",
98+
"path": "/commands",
99+
"title": "CLI Actions"
100+
},
96101
{
97102
"type": "link",
98103
"path": "/theme",

0 commit comments

Comments
 (0)