2245 lines
102 KiB
HTML
2245 lines
102 KiB
HTML
|
<!DOCTYPE html>
|
|||
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
|
|||
|
|
<head>
|
|||
|
|
<meta charset="utf-8" />
|
|||
|
|
<meta name="generator" content="pandoc" />
|
|||
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
|
|||
|
|
<title>GHOSTTY(1) Version 0.1.0-main+dd6460bc | Ghostty terminal emulator</title>
|
|||
|
|
<style>
|
|||
|
|
html {
|
|||
|
|
color: #1a1a1a;
|
|||
|
|
background-color: #fdfdfd;
|
|||
|
|
}
|
|||
|
|
body {
|
|||
|
|
margin: 0 auto;
|
|||
|
|
max-width: 36em;
|
|||
|
|
padding-left: 50px;
|
|||
|
|
padding-right: 50px;
|
|||
|
|
padding-top: 50px;
|
|||
|
|
padding-bottom: 50px;
|
|||
|
|
hyphens: auto;
|
|||
|
|
overflow-wrap: break-word;
|
|||
|
|
text-rendering: optimizeLegibility;
|
|||
|
|
font-kerning: normal;
|
|||
|
|
}
|
|||
|
|
@media (max-width: 600px) {
|
|||
|
|
body {
|
|||
|
|
font-size: 0.9em;
|
|||
|
|
padding: 12px;
|
|||
|
|
}
|
|||
|
|
h1 {
|
|||
|
|
font-size: 1.8em;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
@media print {
|
|||
|
|
html {
|
|||
|
|
background-color: white;
|
|||
|
|
}
|
|||
|
|
body {
|
|||
|
|
background-color: transparent;
|
|||
|
|
color: black;
|
|||
|
|
font-size: 12pt;
|
|||
|
|
}
|
|||
|
|
p, h2, h3 {
|
|||
|
|
orphans: 3;
|
|||
|
|
widows: 3;
|
|||
|
|
}
|
|||
|
|
h2, h3, h4 {
|
|||
|
|
page-break-after: avoid;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
p {
|
|||
|
|
margin: 1em 0;
|
|||
|
|
}
|
|||
|
|
a {
|
|||
|
|
color: #1a1a1a;
|
|||
|
|
}
|
|||
|
|
a:visited {
|
|||
|
|
color: #1a1a1a;
|
|||
|
|
}
|
|||
|
|
img {
|
|||
|
|
max-width: 100%;
|
|||
|
|
}
|
|||
|
|
svg {
|
|||
|
|
height: auto;
|
|||
|
|
max-width: 100%;
|
|||
|
|
}
|
|||
|
|
h1, h2, h3, h4, h5, h6 {
|
|||
|
|
margin-top: 1.4em;
|
|||
|
|
}
|
|||
|
|
h5, h6 {
|
|||
|
|
font-size: 1em;
|
|||
|
|
font-style: italic;
|
|||
|
|
}
|
|||
|
|
h6 {
|
|||
|
|
font-weight: normal;
|
|||
|
|
}
|
|||
|
|
ol, ul {
|
|||
|
|
padding-left: 1.7em;
|
|||
|
|
margin-top: 1em;
|
|||
|
|
}
|
|||
|
|
li > ol, li > ul {
|
|||
|
|
margin-top: 0;
|
|||
|
|
}
|
|||
|
|
blockquote {
|
|||
|
|
margin: 1em 0 1em 1.7em;
|
|||
|
|
padding-left: 1em;
|
|||
|
|
border-left: 2px solid #e6e6e6;
|
|||
|
|
color: #606060;
|
|||
|
|
}
|
|||
|
|
code {
|
|||
|
|
font-family: Menlo, Monaco, Consolas, 'Lucida Console', monospace;
|
|||
|
|
font-size: 85%;
|
|||
|
|
margin: 0;
|
|||
|
|
hyphens: manual;
|
|||
|
|
}
|
|||
|
|
pre {
|
|||
|
|
margin: 1em 0;
|
|||
|
|
overflow: auto;
|
|||
|
|
}
|
|||
|
|
pre code {
|
|||
|
|
padding: 0;
|
|||
|
|
overflow: visible;
|
|||
|
|
overflow-wrap: normal;
|
|||
|
|
}
|
|||
|
|
.sourceCode {
|
|||
|
|
background-color: transparent;
|
|||
|
|
overflow: visible;
|
|||
|
|
}
|
|||
|
|
hr {
|
|||
|
|
background-color: #1a1a1a;
|
|||
|
|
border: none;
|
|||
|
|
height: 1px;
|
|||
|
|
margin: 1em 0;
|
|||
|
|
}
|
|||
|
|
table {
|
|||
|
|
margin: 1em 0;
|
|||
|
|
border-collapse: collapse;
|
|||
|
|
width: 100%;
|
|||
|
|
overflow-x: auto;
|
|||
|
|
display: block;
|
|||
|
|
font-variant-numeric: lining-nums tabular-nums;
|
|||
|
|
}
|
|||
|
|
table caption {
|
|||
|
|
margin-bottom: 0.75em;
|
|||
|
|
}
|
|||
|
|
tbody {
|
|||
|
|
margin-top: 0.5em;
|
|||
|
|
border-top: 1px solid #1a1a1a;
|
|||
|
|
border-bottom: 1px solid #1a1a1a;
|
|||
|
|
}
|
|||
|
|
th {
|
|||
|
|
border-top: 1px solid #1a1a1a;
|
|||
|
|
padding: 0.25em 0.5em 0.25em 0.5em;
|
|||
|
|
}
|
|||
|
|
td {
|
|||
|
|
padding: 0.125em 0.5em 0.25em 0.5em;
|
|||
|
|
}
|
|||
|
|
header {
|
|||
|
|
margin-bottom: 4em;
|
|||
|
|
text-align: center;
|
|||
|
|
}
|
|||
|
|
#TOC li {
|
|||
|
|
list-style: none;
|
|||
|
|
}
|
|||
|
|
#TOC ul {
|
|||
|
|
padding-left: 1.3em;
|
|||
|
|
}
|
|||
|
|
#TOC > ul {
|
|||
|
|
padding-left: 0;
|
|||
|
|
}
|
|||
|
|
#TOC a:not(:hover) {
|
|||
|
|
text-decoration: none;
|
|||
|
|
}
|
|||
|
|
code{white-space: pre-wrap;}
|
|||
|
|
span.smallcaps{font-variant: small-caps;}
|
|||
|
|
div.columns{display: flex; gap: min(4vw, 1.5em);}
|
|||
|
|
div.column{flex: auto; overflow-x: auto;}
|
|||
|
|
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
|
|||
|
|
/* The extra [class] is a hack that increases specificity enough to
|
|||
|
|
override a similar rule in reveal.js */
|
|||
|
|
ul.task-list[class]{list-style: none;}
|
|||
|
|
ul.task-list li input[type="checkbox"] {
|
|||
|
|
font-size: inherit;
|
|||
|
|
width: 0.8em;
|
|||
|
|
margin: 0 0.8em 0.2em -1.6em;
|
|||
|
|
vertical-align: middle;
|
|||
|
|
}
|
|||
|
|
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
|
|||
|
|
</style>
|
|||
|
|
</head>
|
|||
|
|
<body>
|
|||
|
|
<header id="title-block-header">
|
|||
|
|
<h1 class="title">GHOSTTY(1) Version 0.1.0-main+dd6460bc | Ghostty
|
|||
|
|
terminal emulator</h1>
|
|||
|
|
</header>
|
|||
|
|
<h1 id="name">NAME</h1>
|
|||
|
|
<p><strong>ghostty</strong> - Ghostty terminal emulator</p>
|
|||
|
|
<h1 id="description">DESCRIPTION</h1>
|
|||
|
|
<p>Ghostty is a cross-platform, GPU-accelerated terminal emulator that
|
|||
|
|
aims to push the boundaries of what is possible with a terminal emulator
|
|||
|
|
by exposing modern, opt-in features that enable CLI tool developers to
|
|||
|
|
build more feature rich, interactive applications.</p>
|
|||
|
|
<p>There are a number of excellent terminal emulator options that exist
|
|||
|
|
today. The unique goal of Ghostty is to have a platform for
|
|||
|
|
experimenting with modern, optional, non-standards-compliant features to
|
|||
|
|
enhance the capabilities of CLI applications. We aim to be the best in
|
|||
|
|
this category, and competitive in the rest.</p>
|
|||
|
|
<p>While aiming for this ambitious goal, Ghostty is a fully standards
|
|||
|
|
compliant terminal emulator that aims to remain compatible with all
|
|||
|
|
existing shells and software. You can use this as a drop-in replacement
|
|||
|
|
for your existing terminal emulator.</p>
|
|||
|
|
<h1 id="command-line-actions">COMMAND LINE ACTIONS</h1>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--version</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>version</code> command is used to display information about
|
|||
|
|
Ghostty.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--help</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>help</code> command shows general help about Ghostty. You
|
|||
|
|
can also specify <code>--help</code> or <code>-h</code> along with any
|
|||
|
|
action such as <code>+list-themes</code> to see help for a specific
|
|||
|
|
action.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+list-fonts</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>list-fonts</code> 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.</p>
|
|||
|
|
<p>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
|
|||
|
|
<code>--family</code>, the sorting will be disabled and the results
|
|||
|
|
instead will be shown in the same priority order Ghostty would use to
|
|||
|
|
pick a font.</p>
|
|||
|
|
<p>The <code>--family</code> argument can be used to filter results to a
|
|||
|
|
specific family. The family handling is identical to the
|
|||
|
|
<code>font-family</code> set of Ghostty configuration values, so this
|
|||
|
|
can be used to debug why your desired font may not be loading.</p>
|
|||
|
|
<p>The <code>--bold</code> and <code>--italic</code> arguments can be
|
|||
|
|
used to filter results to specific styles. It is not guaranteed that
|
|||
|
|
only those styles are returned, it will just prioritize fonts that match
|
|||
|
|
those styles.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+list-keybinds</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>list-keybinds</code> command is used to list all the
|
|||
|
|
available keybinds for Ghostty.</p>
|
|||
|
|
<p>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</p>
|
|||
|
|
<p>The <code>--default</code> argument will print out all the default
|
|||
|
|
keybinds configured for Ghostty</p>
|
|||
|
|
<p>The <code>--plain</code> flag will disable formatting and make the
|
|||
|
|
output more friendly for Unix tooling. This is default when not printing
|
|||
|
|
to a tty.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+list-themes</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>list-themes</code> command is used to preview or list all
|
|||
|
|
the available themes for Ghostty.</p>
|
|||
|
|
<p>If this command is run from a TTY, a TUI preview of the themes will
|
|||
|
|
be shown. While in the preview, <code>F1</code> will bring up a help
|
|||
|
|
screen and <code>ESC</code> will exit the preview. Other keys that can
|
|||
|
|
be used to navigate the preview are listed in the help screen.</p>
|
|||
|
|
<p>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 <code>--plain</code> CLI
|
|||
|
|
flag.</p>
|
|||
|
|
<p>Two different directories will be searched for themes.</p>
|
|||
|
|
<p>The first directory is the <code>themes</code> subdirectory of your
|
|||
|
|
Ghostty configuration directory. This is
|
|||
|
|
<code>$XDG_CONFIG_DIR/ghostty/themes</code> or
|
|||
|
|
<code>~/.config/ghostty/themes</code>.</p>
|
|||
|
|
<p>The second directory is the <code>themes</code> 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 <code>Ghostty.app/Contents/ Resources/ghostty/themes</code>. On
|
|||
|
|
Linux, this directory is the <code>share/ghostty/ themes</code>
|
|||
|
|
(wherever you installed the Ghostty “share” directory). If you’re
|
|||
|
|
running Ghostty from the source, this is the
|
|||
|
|
<code>zig-out/share/ghostty/themes</code> directory.</p>
|
|||
|
|
<p>You can also set the <code>GHOSTTY_RESOURCES_DIR</code> environment
|
|||
|
|
variable to point to the resources directory.</p>
|
|||
|
|
<p>Flags:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>--path</code>: Show the full path to the theme.</li>
|
|||
|
|
<li><code>--plain</code>: Force a plain listing of themes.</li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+list-colors</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>list-colors</code> command is used to list all the named
|
|||
|
|
RGB colors in Ghostty.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+list-actions</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>list-actions</code> command is used to list all the
|
|||
|
|
available keybind actions for Ghostty.</p>
|
|||
|
|
<p>The <code>--docs</code> argument will print out the documentation for
|
|||
|
|
each action.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+show-config</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>show-config</code> command shows the current configuration
|
|||
|
|
in a valid Ghostty configuration file format.</p>
|
|||
|
|
<p>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.</p>
|
|||
|
|
<p>If you are a new user and want to see all available options with
|
|||
|
|
documentation, run
|
|||
|
|
<code>ghostty +show-config --default --docs</code>.</p>
|
|||
|
|
<p>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.</p>
|
|||
|
|
<p>Flags:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>--default</code>: Show the default configuration instead of
|
|||
|
|
loading the user configuration.</p></li>
|
|||
|
|
<li><p><code>--changes-only</code>: Only show the options that have been
|
|||
|
|
changed from the default. This has no effect if <code>--default</code>
|
|||
|
|
is specified.</p></li>
|
|||
|
|
<li><p><code>--docs</code>: 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
|
|||
|
|
<code>--default</code>.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+validate-config</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>validate-config</code> command is used to validate a
|
|||
|
|
Ghostty config file.</p>
|
|||
|
|
<p>When executed without any arguments, this will load the config from
|
|||
|
|
the default location.</p>
|
|||
|
|
<p>The <code>--config-file</code> argument can be passed to validate a
|
|||
|
|
specific target config file in a non-default location.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>+crash-report</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The <code>crash-report</code> command is used to inspect and send
|
|||
|
|
crash reports.</p>
|
|||
|
|
<p>When executed without any arguments, this will list existing crash
|
|||
|
|
reports.</p>
|
|||
|
|
<p>This command currently only supports listing crash reports. Viewing
|
|||
|
|
and sending crash reports is unimplemented and will be added in the
|
|||
|
|
future.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<h1 id="configuration-options">CONFIGURATION OPTIONS</h1>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--font-family</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The font families to use.</p>
|
|||
|
|
<p>You can generate the list of valid values using the CLI:</p>
|
|||
|
|
<pre><code>ghostty +list-fonts</code></pre>
|
|||
|
|
<p>This configuration can be repeated multiple times to specify
|
|||
|
|
preferred fallback fonts when the requested codepoint is not available
|
|||
|
|
in the primary font. This is particularly useful for multiple languages,
|
|||
|
|
symbolic fonts, etc.</p>
|
|||
|
|
<p>Notes on emoji specifically: On macOS, Ghostty by default will always
|
|||
|
|
use Apple Color Emoji and on Linux will always use Noto Emoji. You can
|
|||
|
|
override this behavior by specifying a font family here that contains
|
|||
|
|
emoji glyphs.</p>
|
|||
|
|
<p>The specific styles (bold, italic, bold italic) do not need to be
|
|||
|
|
explicitly set. If a style is not set, then the regular style
|
|||
|
|
(font-family) will be searched for stylistic variants. If a stylistic
|
|||
|
|
variant is not found, Ghostty will use the regular style. This prevents
|
|||
|
|
falling back to a different font family just to get a style such as
|
|||
|
|
bold. This also applies if you explicitly specify a font family for a
|
|||
|
|
style. For example, if you set <code>font-family-bold = FooBar</code>
|
|||
|
|
and “FooBar” cannot be found, Ghostty will use whatever font is set for
|
|||
|
|
<code>font-family</code> for the bold style.</p>
|
|||
|
|
<p>Finally, some styles may be synthesized if they are not supported.
|
|||
|
|
For example, if a font does not have an italic style and no alternative
|
|||
|
|
italic font is specified, Ghostty will synthesize an italic style by
|
|||
|
|
applying a slant to the regular style. If you want to disable these
|
|||
|
|
synthesized styles then you can use the <code>font-style</code>
|
|||
|
|
configurations as documented below.</p>
|
|||
|
|
<p>You can disable styles completely by using the
|
|||
|
|
<code>font-style</code> set of configurations. See the documentation for
|
|||
|
|
<code>font-style</code> for more information.</p>
|
|||
|
|
<p>If you want to overwrite a previous set value rather than append a
|
|||
|
|
fallback, specify the value as <code>""</code> (empty string) to reset
|
|||
|
|
the list and then set the new values. For example:</p>
|
|||
|
|
<pre><code>font-family = ""
|
|||
|
|
font-family = "My Favorite Font"</code></pre>
|
|||
|
|
<p>Setting any of these as CLI arguments will automatically clear the
|
|||
|
|
values set in configuration files so you don’t need to specify
|
|||
|
|
<code>--font-family=""</code> before setting a new value. You only need
|
|||
|
|
to specify this within config files if you want to clear previously set
|
|||
|
|
values in configuration files or on the CLI if you want to clear values
|
|||
|
|
set on the CLI.</p>
|
|||
|
|
<p>Changing this configuration at runtime will only affect new
|
|||
|
|
terminals, i.e. new windows, tabs, etc.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--font-family-bold</code></strong></p>
|
|||
|
|
<p><strong><code>--font-family-italic</code></strong></p>
|
|||
|
|
<p><strong><code>--font-family-bold-italic</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--font-style</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The named font style to use for each of the requested terminal font
|
|||
|
|
styles. This looks up the style based on the font style string
|
|||
|
|
advertised by the font itself. For example, “Iosevka Heavy” has a style
|
|||
|
|
of “Heavy”.</p>
|
|||
|
|
<p>You can also use these fields to completely disable a font style. If
|
|||
|
|
you set the value of the configuration below to literal
|
|||
|
|
<code>false</code> then that font style will be disabled. If the running
|
|||
|
|
program in the terminal requests a disabled font style, the regular font
|
|||
|
|
style will be used instead.</p>
|
|||
|
|
<p>These are only valid if its corresponding font-family is also
|
|||
|
|
specified. If no font-family is specified, then the font-style is
|
|||
|
|
ignored unless you’re disabling the font style.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--font-style-bold</code></strong></p>
|
|||
|
|
<p><strong><code>--font-style-italic</code></strong></p>
|
|||
|
|
<p><strong><code>--font-style-bold-italic</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--font-synthetic-style</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Control whether Ghostty should synthesize a style if the requested
|
|||
|
|
style is not available in the specified font-family.</p>
|
|||
|
|
<p>Ghostty can synthesize bold, italic, and bold italic styles if the
|
|||
|
|
font does not have a specific style. For bold, this is done by drawing
|
|||
|
|
an outline around the glyph of varying thickness. For italic, this is
|
|||
|
|
done by applying a slant to the glyph. For bold italic, both of these
|
|||
|
|
are applied.</p>
|
|||
|
|
<p>Synthetic styles are not perfect and will generally not look as good
|
|||
|
|
as a font that has the style natively. However, they are useful to
|
|||
|
|
provide styled text when the font does not have the style.</p>
|
|||
|
|
<p>Set this to “false” or “true” to disable or enable synthetic styles
|
|||
|
|
completely. You can disable specific styles using “no-bold”,
|
|||
|
|
“no-italic”, and “no-bold-italic”. You can disable multiple styles by
|
|||
|
|
separating them with a comma. For example, “no-bold,no-italic”.</p>
|
|||
|
|
<p>Available style keys are: <code>bold</code>, <code>italic</code>,
|
|||
|
|
<code>bold-italic</code>.</p>
|
|||
|
|
<p>If synthetic styles are disabled, then the regular style will be used
|
|||
|
|
instead if the requested style is not available. If the font has the
|
|||
|
|
requested style, then the font will be used as-is since the style is not
|
|||
|
|
synthetic.</p>
|
|||
|
|
<p>Warning: An easy mistake is to disable <code>bold</code> or
|
|||
|
|
<code>italic</code> but not <code>bold-italic</code>. Disabling only
|
|||
|
|
<code>bold</code> or <code>italic</code> will NOT disable either in the
|
|||
|
|
<code>bold-italic</code> style. If you want to disable
|
|||
|
|
<code>bold-italic</code>, you must explicitly disable it. You cannot
|
|||
|
|
partially disable <code>bold-italic</code>.</p>
|
|||
|
|
<p>By default, synthetic styles are enabled.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--font-feature</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Apply a font feature. This can be repeated multiple times to enable
|
|||
|
|
multiple font features. You can NOT set multiple font features with a
|
|||
|
|
single value (yet).</p>
|
|||
|
|
<p>The font feature will apply to all fonts rendered by Ghostty. A
|
|||
|
|
future enhancement will allow targeting specific faces.</p>
|
|||
|
|
<p>A valid value is the name of a feature. Prefix the feature with a
|
|||
|
|
<code>-</code> to explicitly disable it. Example: <code>ss20</code> or
|
|||
|
|
<code>-ss20</code>.</p>
|
|||
|
|
<p>To disable programming ligatures, use <code>-calt</code> since this
|
|||
|
|
is the typical feature name for programming ligatures. To look into what
|
|||
|
|
font features your font has and what they do, use a font inspection tool
|
|||
|
|
such as <a href="https://fontdrop.info">fontdrop.info</a>.</p>
|
|||
|
|
<p>To generally disable most ligatures, use <code>-calt</code>,
|
|||
|
|
<code>-liga</code>, and <code>-dlig</code> (as separate repetitive
|
|||
|
|
entries in your config).</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--font-size</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Font size in points. This value can be a non-integer and the nearest
|
|||
|
|
integer pixel size will be selected. If you have a high dpi display
|
|||
|
|
where 1pt = 2px then you can get an odd numbered pixel size by
|
|||
|
|
specifying a half point.</p>
|
|||
|
|
<p>For example, 13.5pt @ 2px/pt = 27px</p>
|
|||
|
|
<p>Changing this configuration at runtime will only affect new
|
|||
|
|
terminals, i.e. new windows, tabs, etc. Note that you may still not see
|
|||
|
|
the change depending on your <code>window-inherit-font-size</code>
|
|||
|
|
setting. If that setting is true, only the first window will be affected
|
|||
|
|
by this change since all subsequent windows will inherit the font size
|
|||
|
|
of the previous window.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--font-variation</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>A repeatable configuration to set one or more font variations values
|
|||
|
|
for a variable font. A variable font is a single font, usually with a
|
|||
|
|
filename ending in <code>-VF.ttf</code> or <code>-VF.otf</code> that
|
|||
|
|
contains one or more configurable axes for things such as weight, slant,
|
|||
|
|
etc. Not all fonts support variations; only fonts that explicitly state
|
|||
|
|
they are variable fonts will work.</p>
|
|||
|
|
<p>The format of this is <code>id=value</code> where <code>id</code> is
|
|||
|
|
the axis identifier. An axis identifier is always a 4 character string,
|
|||
|
|
such as <code>wght</code>. To get the list of supported axes, look at
|
|||
|
|
your font documentation or use a font inspection tool.</p>
|
|||
|
|
<p>Invalid ids and values are usually ignored. For example, if a font
|
|||
|
|
only supports weights from 100 to 700, setting <code>wght=800</code>
|
|||
|
|
will do nothing (it will not be clamped to 700). You must consult your
|
|||
|
|
font’s documentation to see what values are supported.</p>
|
|||
|
|
<p>Common axes are: <code>wght</code> (weight), <code>slnt</code>
|
|||
|
|
(slant), <code>ital</code> (italic), <code>opsz</code> (optical size),
|
|||
|
|
<code>wdth</code> (width), <code>GRAD</code> (gradient), etc.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--font-variation-bold</code></strong></p>
|
|||
|
|
<p><strong><code>--font-variation-italic</code></strong></p>
|
|||
|
|
<p><strong><code>--font-variation-bold-italic</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--font-codepoint-map</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Force one or a range of Unicode codepoints to map to a specific named
|
|||
|
|
font. This is useful if you want to support special symbols or if you
|
|||
|
|
want to use specific glyphs that render better for your specific
|
|||
|
|
font.</p>
|
|||
|
|
<p>The syntax is <code>codepoint=fontname</code> where
|
|||
|
|
<code>codepoint</code> is either a single codepoint or a range.
|
|||
|
|
Codepoints must be specified as full Unicode hex values, such as
|
|||
|
|
<code>U+ABCD</code>. Codepoints ranges are specified as
|
|||
|
|
<code>U+ABCD-U+DEFG</code>. You can specify multiple ranges for the same
|
|||
|
|
font separated by commas, such as
|
|||
|
|
<code>U+ABCD-U+DEFG,U+1234-U+5678=fontname</code>. The font name is the
|
|||
|
|
same value as you would use for <code>font-family</code>.</p>
|
|||
|
|
<p>This configuration can be repeated multiple times to specify multiple
|
|||
|
|
codepoint mappings.</p>
|
|||
|
|
<p>Changing this configuration at runtime will only affect new
|
|||
|
|
terminals, i.e. new windows, tabs, etc.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--font-thicken</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Draw fonts with a thicker stroke, if supported. This is only
|
|||
|
|
supported currently on macOS.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-cell-width</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>All of the configurations behavior adjust various metrics determined
|
|||
|
|
by the font. The values can be integers (1, -1, etc.) or a percentage
|
|||
|
|
(20%, -15%, etc.). In each case, the values represent the amount to
|
|||
|
|
change the original value.</p>
|
|||
|
|
<p>For example, a value of <code>1</code> increases the value by 1; it
|
|||
|
|
does not set it to literally 1. A value of <code>20%</code> increases
|
|||
|
|
the value by 20%. And so on.</p>
|
|||
|
|
<p>There is little to no validation on these values so the wrong values
|
|||
|
|
(i.e. <code>-100%</code>) can cause the terminal to be unusable. Use
|
|||
|
|
with caution and reason.</p>
|
|||
|
|
<p>Some values are clamped to minimum or maximum values. This can make
|
|||
|
|
it appear that certain values are ignored. For example, the underline
|
|||
|
|
position is clamped to the height of a cell. If you set the underline
|
|||
|
|
position so high that it extends beyond the bottom of the cell size, it
|
|||
|
|
will be clamped to the bottom of the cell.</p>
|
|||
|
|
<p><code>adjust-cell-height</code> has some additional behaviors to
|
|||
|
|
describe:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p>The font will be centered vertically in the cell.</p></li>
|
|||
|
|
<li><p>The cursor will remain the same size as the font.</p></li>
|
|||
|
|
<li><p>Powerline glyphs will be adjusted along with the cell height so
|
|||
|
|
that things like status lines continue to look aligned.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--adjust-cell-height</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--adjust-font-baseline</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Distance in pixels from the bottom of the cell to the text baseline.
|
|||
|
|
Increase to move baseline UP, decrease to move baseline DOWN.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-underline-position</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Distance in pixels from the top of the cell to the top of the
|
|||
|
|
underline. Increase to move underline DOWN, decrease to move underline
|
|||
|
|
UP.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-underline-thickness</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Thickness in pixels of the underline.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-strikethrough-position</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Distance in pixels from the top of the cell to the top of the
|
|||
|
|
strikethrough. Increase to move strikethrough DOWN, decrease to move
|
|||
|
|
underline UP.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-strikethrough-thickness</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Thickness in pixels of the strikethrough.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-overline-position</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Distance in pixels from the top of the cell to the top of the
|
|||
|
|
overline. Increase to move overline DOWN, decrease to move underline
|
|||
|
|
UP.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-overline-thickness</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Thickness in pixels of the overline.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-cursor-thickness</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Thickness in pixels of the bar cursor and outlined rect cursor.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adjust-box-thickness</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Thickness in pixels of box drawing characters.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--grapheme-width-method</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The method to use for calculating the cell width of a grapheme
|
|||
|
|
cluster. The default value is <code>unicode</code> which uses the
|
|||
|
|
Unicode standard to determine grapheme width. This results in correct
|
|||
|
|
grapheme width but may result in cursor-desync issues with some programs
|
|||
|
|
(such as shells) that may use a legacy method such as
|
|||
|
|
<code>wcswidth</code>.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>legacy</code> - Use a legacy method to determine grapheme
|
|||
|
|
width, such as wcswidth This maximizes compatibility with legacy
|
|||
|
|
programs but may result in incorrect grapheme width for certain
|
|||
|
|
graphemes such as skin-tone emoji, non-English characters, etc.</p>
|
|||
|
|
<p>This is called “legacy” and not something more specific because the
|
|||
|
|
behavior is undefined and we want to retain the ability to modify it.
|
|||
|
|
For example, we may or may not use libc <code>wcswidth</code> now or in
|
|||
|
|
the future.</p></li>
|
|||
|
|
<li><p><code>unicode</code> - Use the Unicode standard to determine
|
|||
|
|
grapheme width.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>If a running program explicitly enables terminal mode 2027, then
|
|||
|
|
<code>unicode</code> width will be forced regardless of this
|
|||
|
|
configuration. When mode 2027 is reset, this configuration will be used
|
|||
|
|
again.</p>
|
|||
|
|
<p>This configuration can be changed at runtime but will not affect
|
|||
|
|
existing terminals. Only new terminals will use the new
|
|||
|
|
configuration.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--freetype-load-flags</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>FreeType load flags to enable. The format of this is a list of flags
|
|||
|
|
to enable separated by commas. If you prefix a flag with
|
|||
|
|
<code>no-</code> then it is disabled. If you omit a flag, it’s default
|
|||
|
|
value is used, so you must explicitly disable flags you don’t want. You
|
|||
|
|
can also use <code>true</code> or <code>false</code> to turn all flags
|
|||
|
|
on or off.</p>
|
|||
|
|
<p>This configuration only applies to Ghostty builds that use FreeType.
|
|||
|
|
This is usually the case only for Linux builds. macOS uses CoreText and
|
|||
|
|
does not have an equivalent configuration.</p>
|
|||
|
|
<p>Available flags:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>hinting</code> - Enable or disable hinting, enabled by
|
|||
|
|
default.</li>
|
|||
|
|
<li><code>force-autohint</code> - Use the freetype auto-hinter rather
|
|||
|
|
than the font’s native hinter. Enabled by default.</li>
|
|||
|
|
<li><code>monochrome</code> - Instructs renderer to use 1-bit monochrome
|
|||
|
|
rendering. This option doesn’t impact the hinter. Enabled by
|
|||
|
|
default.</li>
|
|||
|
|
<li><code>autohint</code> - Use the freetype auto-hinter. Enabled by
|
|||
|
|
default.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Example: <code>hinting</code>, <code>no-hinting</code>,
|
|||
|
|
<code>force-autohint</code>, <code>no-force-autohint</code></p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--theme</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>A theme to use. This can be a built-in theme name, a custom theme
|
|||
|
|
name, or an absolute path to a custom theme file. Ghostty also supports
|
|||
|
|
specifying a different theme to use for light and dark mode. Each option
|
|||
|
|
is documented below.</p>
|
|||
|
|
<p>If the theme is an absolute pathname, Ghostty will attempt to load
|
|||
|
|
that file as a theme. If that file does not exist or is inaccessible, an
|
|||
|
|
error will be logged and no other directories will be searched.</p>
|
|||
|
|
<p>If the theme is not an absolute pathname, two different directories
|
|||
|
|
will be searched for a file name that matches the theme. This is case
|
|||
|
|
sensitive on systems with case-sensitive filesystems. It is an error for
|
|||
|
|
a theme name to include path separators unless it is an absolute
|
|||
|
|
pathname.</p>
|
|||
|
|
<p>The first directory is the <code>themes</code> subdirectory of your
|
|||
|
|
Ghostty configuration directory. This is
|
|||
|
|
<code>$XDG_CONFIG_DIR/ghostty/themes</code> or
|
|||
|
|
<code>~/.config/ghostty/themes</code>.</p>
|
|||
|
|
<p>The second directory is the <code>themes</code> subdirectory of the
|
|||
|
|
Ghostty resources directory. Ghostty ships with a multitude of themes
|
|||
|
|
that will be installed into this directory. On macOS, this list is in
|
|||
|
|
the <code>Ghostty.app/Contents/ Resources/ghostty/themes</code>
|
|||
|
|
directory. On Linux, this list is in the
|
|||
|
|
<code>share/ ghostty/themes</code> directory (wherever you installed the
|
|||
|
|
Ghostty “share” directory.</p>
|
|||
|
|
<p>To see a list of available themes, run
|
|||
|
|
<code>ghostty +list-themes</code>.</p>
|
|||
|
|
<p>A theme file is simply another Ghostty configuration file. They share
|
|||
|
|
the same syntax and same configuration options. A theme can set any
|
|||
|
|
valid configuration option so please do not use a theme file from an
|
|||
|
|
untrusted source. The built-in themes are audited to only set safe
|
|||
|
|
configuration options.</p>
|
|||
|
|
<p>Some options cannot be set within theme files. The reason these are
|
|||
|
|
not supported should be self-evident. A theme file cannot set
|
|||
|
|
<code>theme</code> or <code>config-file</code>. At the time of writing
|
|||
|
|
this, Ghostty will not show any warnings or errors if you set these
|
|||
|
|
options in a theme file but they will be silently ignored.</p>
|
|||
|
|
<p>Any additional colors specified via background, foreground, palette,
|
|||
|
|
etc. will override the colors specified in the theme.</p>
|
|||
|
|
<p>To specify a different theme for light and dark mode, use the
|
|||
|
|
following syntax: <code>light:theme-name,dark:theme-name</code>. For
|
|||
|
|
example: <code>light:rose-pine-dawn,dark:rose-pine</code>. Whitespace
|
|||
|
|
around all values are trimmed and order of light and dark does not
|
|||
|
|
matter. Both light and dark must be specified in this form. In this
|
|||
|
|
form, the theme used will be based on the current desktop environment
|
|||
|
|
theme.</p>
|
|||
|
|
<p>There are some known bugs with light/dark mode theming. These will be
|
|||
|
|
fixed in a future update:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>macOS: titlebar tabs style is not updated when switching
|
|||
|
|
themes.</li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--background</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Background color for the window.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--foreground</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Foreground color for the window.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--selection-foreground</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The foreground and background color for selection. If this is not
|
|||
|
|
set, then the selection color is just the inverted window background and
|
|||
|
|
foreground (note: not to be confused with the cell bg/fg).</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--selection-background</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--selection-invert-fg-bg</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Swap the foreground and background colors of cells for selection.
|
|||
|
|
This option overrides the <code>selection-foreground</code> and
|
|||
|
|
<code>selection-background</code> options.</p>
|
|||
|
|
<p>If you select across cells with differing foregrounds and
|
|||
|
|
backgrounds, the selection color will vary across the selection.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--minimum-contrast</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The minimum contrast ratio between the foreground and background
|
|||
|
|
colors. The contrast ratio is a value between 1 and 21. A value of 1
|
|||
|
|
allows for no contrast (i.e. black on black). This value is the contrast
|
|||
|
|
ratio as defined by the <a href="https://www.w3.org/TR/WCAG20/">WCAG 2.0
|
|||
|
|
specification</a>.</p>
|
|||
|
|
<p>If you want to avoid invisible text (same color as background), a
|
|||
|
|
value of 1.1 is a good value. If you want to avoid text that is
|
|||
|
|
difficult to read, a value of 3 or higher is a good value. The higher
|
|||
|
|
the value, the more likely that text will become black or white.</p>
|
|||
|
|
<p>This value does not apply to Emoji or images.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--palette</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Color palette for the 256 color form that many terminal applications
|
|||
|
|
use. The syntax of this configuration is <code>N=HEXCODE</code> where
|
|||
|
|
<code>N</code> is 0 to 255 (for the 256 colors in the terminal color
|
|||
|
|
table) and <code>HEXCODE</code> is a typical RGB color code such as
|
|||
|
|
<code>#AABBCC</code>.</p>
|
|||
|
|
<p>For definitions on all the codes <a
|
|||
|
|
href="https://www.ditig.com/256-colors-cheat-sheet">see this cheat
|
|||
|
|
sheet</a>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--cursor-color</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The color of the cursor. If this is not set, a default will be
|
|||
|
|
chosen.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--cursor-invert-fg-bg</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Swap the foreground and background colors of the cell under the
|
|||
|
|
cursor. This option overrides the <code>cursor-color</code> and
|
|||
|
|
<code>cursor-text</code> options.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--cursor-opacity</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The opacity level (opposite of transparency) of the cursor. A value
|
|||
|
|
of 1 is fully opaque and a value of 0 is fully transparent. A value less
|
|||
|
|
than 0 or greater than 1 will be clamped to the nearest valid value.
|
|||
|
|
Note that a sufficiently small value such as 0.3 may be effectively
|
|||
|
|
invisible and may make it difficult to find the cursor.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--cursor-style</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The style of the cursor. This sets the default style. A running
|
|||
|
|
program can still request an explicit cursor style using escape
|
|||
|
|
sequences (such as <code>CSI q</code>). Shell configurations will often
|
|||
|
|
request specific cursor styles.</p>
|
|||
|
|
<p>Note that shell integration will automatically set the cursor to a
|
|||
|
|
bar at a prompt, regardless of this configuration. You can disable that
|
|||
|
|
behavior by specifying
|
|||
|
|
<code>shell-integration-features = no-cursor</code> or disabling shell
|
|||
|
|
integration entirely.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>block</code></li>
|
|||
|
|
<li><code>bar</code></li>
|
|||
|
|
<li><code>underline</code></li>
|
|||
|
|
<li><code>block_hollow</code></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--cursor-style-blink</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Sets the default blinking state of the cursor. This is just the
|
|||
|
|
default state; running programs may override the cursor style using
|
|||
|
|
<code>DECSCUSR</code> (<code>CSI q</code>).</p>
|
|||
|
|
<p>If this is not set, the cursor blinks by default. Note that this is
|
|||
|
|
not the same as a “true” value, as noted below.</p>
|
|||
|
|
<p>If this is not set at all (<code>null</code>), then Ghostty will
|
|||
|
|
respect DEC Mode 12 (AT&T cursor blink) as an alternate approach to
|
|||
|
|
turning blinking on/off. If this is set to any value other than null,
|
|||
|
|
DEC mode 12 will be ignored but <code>DECSCUSR</code> will still be
|
|||
|
|
respected.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>`` (blank)</li>
|
|||
|
|
<li><code>true</code></li>
|
|||
|
|
<li><code>false</code></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--cursor-text</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The color of the text under the cursor. If this is not set, a default
|
|||
|
|
will be chosen.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--cursor-click-to-move</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Enables the ability to move the cursor at prompts by using
|
|||
|
|
<code>alt+click</code> on Linux and <code>option+click</code> on
|
|||
|
|
macOS.</p>
|
|||
|
|
<p>This feature requires shell integration (specifically prompt marking
|
|||
|
|
via <code>OSC 133</code>) and only works in primary screen mode.
|
|||
|
|
Alternate screen applications like vim usually have their own version of
|
|||
|
|
this feature but this configuration doesn’t control that.</p>
|
|||
|
|
<p>It should be noted that this feature works by translating your
|
|||
|
|
desired position into a series of synthetic arrow key movements, so some
|
|||
|
|
weird behavior around edge cases are to be expected. This is
|
|||
|
|
unfortunately how this feature is implemented across terminals because
|
|||
|
|
there isn’t any other way to implement it.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--mouse-hide-while-typing</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Hide the mouse immediately when typing. The mouse becomes visible
|
|||
|
|
again when the mouse is used (button, movement, etc.). Platform-specific
|
|||
|
|
behavior may dictate other scenarios where the mouse is shown. For
|
|||
|
|
example on macOS, the mouse is shown again when a new window, tab, or
|
|||
|
|
split is created.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--mouse-shift-capture</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Determines whether running programs can detect the shift key pressed
|
|||
|
|
with a mouse click. Typically, the shift key is used to extend mouse
|
|||
|
|
selection.</p>
|
|||
|
|
<p>The default value of <code>false</code> means that the shift key is
|
|||
|
|
not sent with the mouse protocol and will extend the selection. This
|
|||
|
|
value can be conditionally overridden by the running program with the
|
|||
|
|
<code>XTSHIFTESCAPE</code> sequence.</p>
|
|||
|
|
<p>The value <code>true</code> means that the shift key is sent with the
|
|||
|
|
mouse protocol but the running program can override this behavior with
|
|||
|
|
<code>XTSHIFTESCAPE</code>.</p>
|
|||
|
|
<p>The value <code>never</code> is the same as <code>false</code> but
|
|||
|
|
the running program cannot override this behavior with
|
|||
|
|
<code>XTSHIFTESCAPE</code>. The value <code>always</code> is the same as
|
|||
|
|
<code>true</code> but the running program cannot override this behavior
|
|||
|
|
with <code>XTSHIFTESCAPE</code>.</p>
|
|||
|
|
<p>If you always want shift to extend mouse selection even if the
|
|||
|
|
program requests otherwise, set this to <code>never</code>.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>true</code></li>
|
|||
|
|
<li><code>false</code></li>
|
|||
|
|
<li><code>always</code></li>
|
|||
|
|
<li><code>never</code></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--mouse-scroll-multiplier</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Multiplier for scrolling distance with the mouse wheel. Any value
|
|||
|
|
less than 0.01 or greater than 10,000 will be clamped to the nearest
|
|||
|
|
valid value.</p>
|
|||
|
|
<p>A value of “1” (default) scrolls te default amount. A value of “2”
|
|||
|
|
scrolls double the default amount. A value of “0.5” scrolls half the
|
|||
|
|
default amount. Et cetera.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--background-opacity</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The opacity level (opposite of transparency) of the background. A
|
|||
|
|
value of 1 is fully opaque and a value of 0 is fully transparent. A
|
|||
|
|
value less than 0 or greater than 1 will be clamped to the nearest valid
|
|||
|
|
value.</p>
|
|||
|
|
<p>On macOS, background opacity is disabled when the terminal enters
|
|||
|
|
native fullscreen. This is because the background becomes gray and it
|
|||
|
|
can cause widgets to show through which isn’t generally desirable.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--background-blur-radius</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>A positive value enables blurring of the background when
|
|||
|
|
background-opacity is less than 1. The value is the blur radius to
|
|||
|
|
apply. A value of 20 is reasonable for a good looking blur. Higher
|
|||
|
|
values will cause strange rendering issues as well as performance
|
|||
|
|
issues.</p>
|
|||
|
|
<p>This is only supported on macOS.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--unfocused-split-opacity</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The opacity level (opposite of transparency) of an unfocused split.
|
|||
|
|
Unfocused splits by default are slightly faded out to make it easier to
|
|||
|
|
see which split is focused. To disable this feature, set this value to
|
|||
|
|
1.</p>
|
|||
|
|
<p>A value of 1 is fully opaque and a value of 0 is fully transparent.
|
|||
|
|
Because “0” is not useful (it makes the window look very weird), the
|
|||
|
|
minimum value is 0.15. This value still looks weird but you can at least
|
|||
|
|
see what’s going on. A value outside of the range 0.15 to 1 will be
|
|||
|
|
clamped to the nearest valid value.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--unfocused-split-fill</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The color to dim the unfocused split. Unfocused splits are dimmed by
|
|||
|
|
rendering a semi-transparent rectangle over the split. This sets the
|
|||
|
|
color of that rectangle and can be used to carefully control the dimming
|
|||
|
|
effect.</p>
|
|||
|
|
<p>This will default to the background color.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--command</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The command to run, usually a shell. If this is not an absolute path,
|
|||
|
|
it’ll be looked up in the <code>PATH</code>. If this is not set, a
|
|||
|
|
default will be looked up from your system. The rules for the default
|
|||
|
|
lookup are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>SHELL</code> environment variable</p></li>
|
|||
|
|
<li><p><code>passwd</code> entry (user information)</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>This can contain additional arguments to run the command with. If
|
|||
|
|
additional arguments are provided, the command will be executed using
|
|||
|
|
<code>/bin/sh -c</code>. Ghostty does not do any shell command
|
|||
|
|
parsing.</p>
|
|||
|
|
<p>This command will be used for all new terminal surfaces, i.e. new
|
|||
|
|
windows, tabs, etc. If you want to run a command only for the first
|
|||
|
|
terminal surface created when Ghostty starts, use the
|
|||
|
|
<code>initial-command</code> configuration.</p>
|
|||
|
|
<p>Ghostty supports the common <code>-e</code> flag for executing a
|
|||
|
|
command with arguments. For example,
|
|||
|
|
<code>ghostty -e fish --with --custom --args</code>. This flag sets the
|
|||
|
|
<code>initial-command</code> configuration, see that for more
|
|||
|
|
information.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--initial-command</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>This is the same as “command”, but only applies to the first terminal
|
|||
|
|
surface created when Ghostty starts. Subsequent terminal surfaces will
|
|||
|
|
use the <code>command</code> configuration.</p>
|
|||
|
|
<p>After the first terminal surface is created (or closed), there is no
|
|||
|
|
way to run this initial command again automatically. As such, setting
|
|||
|
|
this at runtime works but will only affect the next terminal surface if
|
|||
|
|
it is the first one ever created.</p>
|
|||
|
|
<p>If you’re using the <code>ghostty</code> CLI there is also a shortcut
|
|||
|
|
to set this with arguments directly: you can use the <code>-e</code>
|
|||
|
|
flag. For example: <code>ghostty -e fish --with --custom --args</code>.
|
|||
|
|
The <code>-e</code> flag automatically forces some other behaviors as
|
|||
|
|
well:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>gtk-single-instance=false</code> - This ensures that a new
|
|||
|
|
instance is launched and the CLI args are respected.</p></li>
|
|||
|
|
<li><p><code>quit-after-last-window-closed=true</code> - This ensures
|
|||
|
|
that the Ghostty process will exit when the command exits. Additionally,
|
|||
|
|
the <code>quit-after-last-window-closed-delay</code> is unset.</p></li>
|
|||
|
|
<li><p><code>shell-integration=detect</code> (if not <code>none</code>)
|
|||
|
|
- This prevents forcibly injecting any configured shell integration into
|
|||
|
|
the command’s environment. With <code>-e</code> its highly unlikely that
|
|||
|
|
you’re executing a shell and forced shell integration is likely to cause
|
|||
|
|
problems (i.e. by wrapping your command in a shell, setting env vars,
|
|||
|
|
etc.). This is a safety measure to prevent unexpected behavior. If you
|
|||
|
|
want shell integration with a <code>-e</code>-executed command, you must
|
|||
|
|
either name your binary appopriately or source the shell integration
|
|||
|
|
script manually.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--wait-after-command</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If true, keep the terminal open after the command exits. Normally,
|
|||
|
|
the terminal window closes when the running command (such as a shell)
|
|||
|
|
exits. With this true, the terminal window will stay open until any
|
|||
|
|
keypress is received.</p>
|
|||
|
|
<p>This is primarily useful for scripts or debugging.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--abnormal-command-exit-runtime</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The number of milliseconds of runtime below which we consider a
|
|||
|
|
process exit to be abnormal. This is used to show an error message when
|
|||
|
|
the process exits too quickly.</p>
|
|||
|
|
<p>On Linux, this must be paired with a non-zero exit code. On macOS, we
|
|||
|
|
allow any exit code because of the way shell processes are launched via
|
|||
|
|
the login command.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--scrollback-limit</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The size of the scrollback buffer in bytes. This also includes the
|
|||
|
|
active screen. No matter what this is set to, enough memory will always
|
|||
|
|
be allocated for the visible screen and anything leftover is the limit
|
|||
|
|
for the scrollback.</p>
|
|||
|
|
<p>When this limit is reached, the oldest lines are removed from the
|
|||
|
|
scrollback.</p>
|
|||
|
|
<p>Scrollback currently exists completely in memory. This means that the
|
|||
|
|
larger this value, the larger potential memory usage. Scrollback is
|
|||
|
|
allocated lazily up to this limit, so if you set this to a very large
|
|||
|
|
value, it will not immediately consume a lot of memory.</p>
|
|||
|
|
<p>This size is per terminal surface, not for the entire
|
|||
|
|
application.</p>
|
|||
|
|
<p>It is not currently possible to set an unlimited scrollback buffer.
|
|||
|
|
This is a future planned feature.</p>
|
|||
|
|
<p>This can be changed at runtime but will only affect new terminal
|
|||
|
|
surfaces.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--link</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Match a regular expression against the terminal text and associate
|
|||
|
|
clicking it with an action. This can be used to match URLs, file paths,
|
|||
|
|
etc. Actions can be opening using the system opener
|
|||
|
|
(i.e. <code>open</code> or <code>xdg-open</code>) or executing any
|
|||
|
|
arbitrary binding action.</p>
|
|||
|
|
<p>Links that are configured earlier take precedence over links that are
|
|||
|
|
configured later.</p>
|
|||
|
|
<p>A default link that matches a URL and opens it in the system opener
|
|||
|
|
always exists. This can be disabled using <code>link-url</code>.</p>
|
|||
|
|
<p>TODO: This can’t currently be set!</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--link-url</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Enable URL matching. URLs are matched on hover with control (Linux)
|
|||
|
|
or super (macOS) pressed and open using the default system application
|
|||
|
|
for the linked URL.</p>
|
|||
|
|
<p>The URL matcher is always lowest priority of any configured links
|
|||
|
|
(see <code>link</code>). If you want to customize URL matching, use
|
|||
|
|
<code>link</code> and disable this.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--fullscreen</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Start new windows in fullscreen. This setting applies to new windows
|
|||
|
|
and does not apply to tabs, splits, etc. However, this setting will
|
|||
|
|
apply to all new windows, not just the first one.</p>
|
|||
|
|
<p>On macOS, this setting does not work if window-decoration is set to
|
|||
|
|
“false”, because native fullscreen on macOS requires window decorations
|
|||
|
|
to be set.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--title</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The title Ghostty will use for the window. This will force the title
|
|||
|
|
of the window to be this title at all times and Ghostty will ignore any
|
|||
|
|
set title escape sequences programs (such as Neovim) may send.</p>
|
|||
|
|
<p>If you want a blank title, set this to one or more spaces by quoting
|
|||
|
|
the value. For example, <code>title = " "</code>. This effectively hides
|
|||
|
|
the title. This is necessary because setting a blank value resets the
|
|||
|
|
title to the default value of the running program.</p>
|
|||
|
|
<p>This configuration can be reloaded at runtime. If it is set, the
|
|||
|
|
title will update for all windows. If it is unset, the next title change
|
|||
|
|
escape sequence will be honored but previous changes will not
|
|||
|
|
retroactively be set. This latter case may require you restart programs
|
|||
|
|
such as neovim to get the new title.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--class</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The setting that will change the application class value.</p>
|
|||
|
|
<p>This controls the class field of the <code>WM_CLASS</code> X11
|
|||
|
|
property (when running under X11), and the Wayland application ID (when
|
|||
|
|
running under Wayland).</p>
|
|||
|
|
<p>Note that changing this value between invocations will create new,
|
|||
|
|
separate instances, of Ghostty when running with
|
|||
|
|
<code>gtk-single-instance=true</code>. See that option for more
|
|||
|
|
details.</p>
|
|||
|
|
<p>The class name must follow the requirements defined <a
|
|||
|
|
href="https://docs.gtk.org/gio/type_func.Application.id_is_valid.html">in
|
|||
|
|
the GTK documentation</a>.</p>
|
|||
|
|
<p>The default is <code>com.mitchellh.ghostty</code>.</p>
|
|||
|
|
<p>This only affects GTK builds.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--x11-instance-name</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>This controls the instance name field of the <code>WM_CLASS</code>
|
|||
|
|
X11 property when running under X11. It has no effect otherwise.</p>
|
|||
|
|
<p>The default is <code>ghostty</code>.</p>
|
|||
|
|
<p>This only affects GTK builds.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--working-directory</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The directory to change to after starting the command.</p>
|
|||
|
|
<p>This setting is secondary to the
|
|||
|
|
<code>window-inherit-working-directory</code> setting. If a previous
|
|||
|
|
Ghostty terminal exists in the same process,
|
|||
|
|
<code>window-inherit-working-directory</code> will take precedence.
|
|||
|
|
Otherwise, this setting will be used. Typically, this setting is used
|
|||
|
|
only for the first window.</p>
|
|||
|
|
<p>The default is <code>inherit</code> except in special scenarios
|
|||
|
|
listed next. On macOS, if Ghostty can detect it is launched from launchd
|
|||
|
|
(double-clicked) or <code>open</code>, then it defaults to
|
|||
|
|
<code>home</code>. On Linux with GTK, if Ghostty can detect it was
|
|||
|
|
launched from a desktop launcher, then it defaults to
|
|||
|
|
<code>home</code>.</p>
|
|||
|
|
<p>The value of this must be an absolute value or one of the special
|
|||
|
|
values below:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>home</code> - The home directory of the executing
|
|||
|
|
user.</p></li>
|
|||
|
|
<li><p><code>inherit</code> - The working directory of the launching
|
|||
|
|
process.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--keybind</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Key bindings. The format is <code>trigger=action</code>. Duplicate
|
|||
|
|
triggers will overwrite previously set values. The list of actions is
|
|||
|
|
available in the documentation or using the
|
|||
|
|
<code>ghostty +list-actions</code> command.</p>
|
|||
|
|
<p>Trigger: <code>+</code>-separated list of keys and modifiers.
|
|||
|
|
Example: <code>ctrl+a</code>, <code>ctrl+shift+b</code>,
|
|||
|
|
<code>up</code>. Some notes:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p>modifiers cannot repeat, <code>ctrl+ctrl+a</code> is
|
|||
|
|
invalid.</p></li>
|
|||
|
|
<li><p>modifiers and keys can be in any order, <code>shift+a+ctrl</code>
|
|||
|
|
is <em>weird</em>, but valid.</p></li>
|
|||
|
|
<li><p>only a single key input is allowed, <code>ctrl+a+b</code> is
|
|||
|
|
invalid.</p></li>
|
|||
|
|
<li><p>the key input can be prefixed with <code>physical:</code> to
|
|||
|
|
specify a physical key mapping rather than a logical one. A physical key
|
|||
|
|
mapping responds to the hardware keycode and not the keycode translated
|
|||
|
|
by any system keyboard layouts. Example: “ctrl+physical:a”</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Valid modifiers are <code>shift</code>, <code>ctrl</code> (alias:
|
|||
|
|
<code>control</code>), <code>alt</code> (alias: <code>opt</code>,
|
|||
|
|
<code>option</code>), and <code>super</code> (alias: <code>cmd</code>,
|
|||
|
|
<code>command</code>). You may use the modifier or the alias. When
|
|||
|
|
debugging keybinds, the non-aliased modifier will always be used in
|
|||
|
|
output.</p>
|
|||
|
|
<p>Note: The fn or “globe” key on keyboards are not supported as a
|
|||
|
|
modifier. This is a limitation of the operating systems and GUI toolkits
|
|||
|
|
that Ghostty uses.</p>
|
|||
|
|
<p>You may also specify multiple triggers separated by <code>></code>
|
|||
|
|
to require a sequence of triggers to activate the action. For example,
|
|||
|
|
<code>ctrl+a>n=new_window</code> will only trigger the
|
|||
|
|
<code>new_window</code> action if the user presses <code>ctrl+a</code>
|
|||
|
|
followed separately by <code>n</code>. In other software, this is
|
|||
|
|
sometimes called a leader key, a key chord, a key table, etc. There is
|
|||
|
|
no hardcoded limit on the number of parts in a sequence.</p>
|
|||
|
|
<p>Warning: If you define a sequence as a CLI argument to
|
|||
|
|
<code>ghostty</code>, you probably have to quote the keybind since
|
|||
|
|
<code>></code> is a special character in most shells. Example:
|
|||
|
|
ghostty –keybind=‘ctrl+a>n=new_window’</p>
|
|||
|
|
<p>A trigger sequence has some special handling:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p>Ghostty will wait an indefinite amount of time for the next key
|
|||
|
|
in the sequence. There is no way to specify a timeout. The only way to
|
|||
|
|
force the output of a prefix key is to assign another keybind to
|
|||
|
|
specifically output that key
|
|||
|
|
(i.e. <code>ctrl+a>ctrl+a=text:foo</code>) or press an unbound key
|
|||
|
|
which will send both keys to the program.</p></li>
|
|||
|
|
<li><p>If a prefix in a sequence is previously bound, the sequence will
|
|||
|
|
override the previous binding. For example, if <code>ctrl+a</code> is
|
|||
|
|
bound to <code>new_window</code> and <code>ctrl+a>n</code> is bound
|
|||
|
|
to <code>new_tab</code>, pressing <code>ctrl+a</code> will do
|
|||
|
|
nothing.</p></li>
|
|||
|
|
<li><p>Adding to the above, if a previously bound sequence prefix is
|
|||
|
|
used in a new, non-sequence binding, the entire previously bound
|
|||
|
|
sequence will be unbound. For example, if you bind
|
|||
|
|
<code>ctrl+a>n</code> and <code>ctrl+a>t</code>, and then bind
|
|||
|
|
<code>ctrl+a</code> directly, both <code>ctrl+a>n</code> and
|
|||
|
|
<code>ctrl+a>t</code> will become unbound.</p></li>
|
|||
|
|
<li><p>Trigger sequences are not allowed for <code>global:</code> or
|
|||
|
|
<code>all:</code>-prefixed triggers. This is a limitation we could
|
|||
|
|
remove in the future.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Action is the action to take when the trigger is satisfied. It takes
|
|||
|
|
the format <code>action</code> or <code>action:param</code>. The latter
|
|||
|
|
form is only valid if the action requires a parameter.</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>ignore</code> - Do nothing, ignore the key input. This can
|
|||
|
|
be used to black hole certain inputs to have no effect.</p></li>
|
|||
|
|
<li><p><code>unbind</code> - Remove the binding. This makes it so the
|
|||
|
|
previous action is removed, and the key will be sent through to the
|
|||
|
|
child command if it is printable.</p></li>
|
|||
|
|
<li><p><code>csi:text</code> - Send a CSI sequence.
|
|||
|
|
i.e. <code>csi:A</code> sends “cursor up”.</p></li>
|
|||
|
|
<li><p><code>esc:text</code> - Send an escape sequence.
|
|||
|
|
i.e. <code>esc:d</code> deletes to the end of the word to the
|
|||
|
|
right.</p></li>
|
|||
|
|
<li><p><code>text:text</code> - Send a string. Uses Zig string literal
|
|||
|
|
syntax. i.e. <code>text:\x15</code> sends Ctrl-U.</p></li>
|
|||
|
|
<li><p>All other actions can be found in the documentation or by using
|
|||
|
|
the <code>ghostty +list-actions</code> command.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Some notes for the action:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>The parameter is taken as-is after the <code>:</code>. Double quotes
|
|||
|
|
or other mechanisms are included and NOT parsed. If you want to send a
|
|||
|
|
string value that includes spaces, wrap the entire trigger/action in
|
|||
|
|
double quotes. Example: <code>--keybind="up=csi:A B"</code></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>There are some additional special values that can be specified for
|
|||
|
|
keybind:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>keybind=clear</code> will clear all set keybindings. Warning:
|
|||
|
|
this removes ALL keybindings up to this point, including the default
|
|||
|
|
keybindings.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The keybind trigger can be prefixed with some special values to
|
|||
|
|
change the behavior of the keybind. These are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>all:</code> - Make the keybind apply to all terminal
|
|||
|
|
surfaces. By default, keybinds only apply to the focused terminal
|
|||
|
|
surface. If this is true, then the keybind will be sent to all terminal
|
|||
|
|
surfaces. This only applies to actions that are surface-specific. For
|
|||
|
|
actions that are already global (i.e. <code>quit</code>), this prefix
|
|||
|
|
has no effect.</p></li>
|
|||
|
|
<li><p><code>global:</code> - Make the keybind global. By default,
|
|||
|
|
keybinds only work within Ghostty and under the right conditions
|
|||
|
|
(application focused, sometimes terminal focused, etc.). If you want a
|
|||
|
|
keybind to work globally across your system (i.e. even when Ghostty is
|
|||
|
|
not focused), specify this prefix. This prefix implies
|
|||
|
|
<code>all:</code>. Note: this does not work in all environments; see the
|
|||
|
|
additional notes below for more information.</p></li>
|
|||
|
|
<li><p><code>unconsumed:</code> - Do not consume the input. By default,
|
|||
|
|
a keybind will consume the input, meaning that the associated encoding
|
|||
|
|
(if any) will not be sent to the running program in the terminal. If you
|
|||
|
|
wish to send the encoded value to the program, specify the
|
|||
|
|
<code>unconsumed:</code> prefix before the entire keybind. For example:
|
|||
|
|
<code>unconsumed:ctrl+a=reload_config</code>. <code>global:</code> and
|
|||
|
|
<code>all:</code>-prefixed keybinds will always consume the input
|
|||
|
|
regardless of this setting. Since they are not associated with a
|
|||
|
|
specific terminal surface, they’re never encoded.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Keybind triggers are not unique per prefix combination. For example,
|
|||
|
|
<code>ctrl+a</code> and <code>global:ctrl+a</code> are not two separate
|
|||
|
|
keybinds. The keybind set later will overwrite the keybind set earlier.
|
|||
|
|
In this case, the <code>global:</code> keybind will be used.</p>
|
|||
|
|
<p>Multiple prefixes can be specified. For example,
|
|||
|
|
<code>global:unconsumed:ctrl+a=reload_config</code> will make the
|
|||
|
|
keybind global and not consume the input to reload the config.</p>
|
|||
|
|
<p>Note: <code>global:</code> is only supported on macOS. On macOS, this
|
|||
|
|
feature requires accessibility permissions to be granted to Ghostty.
|
|||
|
|
When a <code>global:</code> keybind is specified and Ghostty is launched
|
|||
|
|
or reloaded, Ghostty will attempt to request these permissions. If the
|
|||
|
|
permissions are not granted, the keybind will not work. On macOS, you
|
|||
|
|
can find these permissions in System Preferences -> Privacy &
|
|||
|
|
Security -> Accessibility.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-padding-x</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Horizontal window padding. This applies padding between the terminal
|
|||
|
|
cells and the left and right window borders. The value is in points,
|
|||
|
|
meaning that it will be scaled appropriately for screen DPI.</p>
|
|||
|
|
<p>If this value is set too large, the screen will render nothing,
|
|||
|
|
because the grid will be completely squished by the padding. It is up to
|
|||
|
|
you as the user to pick a reasonable value. If you pick an unreasonable
|
|||
|
|
value, a warning will appear in the logs.</p>
|
|||
|
|
<p>Changing this configuration at runtime will only affect new
|
|||
|
|
terminals, i.e. new windows, tabs, etc.</p>
|
|||
|
|
<p>To set a different left and right padding, specify two numerical
|
|||
|
|
values separated by a comma. For example,
|
|||
|
|
<code>window-padding-x = 2,4</code> will set the left padding to 2 and
|
|||
|
|
the right padding to 4. If you want to set both paddings to the same
|
|||
|
|
value, you can use a single value. For example,
|
|||
|
|
<code>window-padding-x = 2</code> will set both paddings to 2.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-padding-y</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Vertical window padding. This applies padding between the terminal
|
|||
|
|
cells and the top and bottom window borders. The value is in points,
|
|||
|
|
meaning that it will be scaled appropriately for screen DPI.</p>
|
|||
|
|
<p>If this value is set too large, the screen will render nothing,
|
|||
|
|
because the grid will be completely squished by the padding. It is up to
|
|||
|
|
you as the user to pick a reasonable value. If you pick an unreasonable
|
|||
|
|
value, a warning will appear in the logs.</p>
|
|||
|
|
<p>Changing this configuration at runtime will only affect new
|
|||
|
|
terminals, i.e. new windows, tabs, etc.</p>
|
|||
|
|
<p>To set a different top and bottom padding, specify two numerical
|
|||
|
|
values separated by a comma. For example,
|
|||
|
|
<code>window-padding-y = 2,4</code> will set the top padding to 2 and
|
|||
|
|
the bottom padding to 4. If you want to set both paddings to the same
|
|||
|
|
value, you can use a single value. For example,
|
|||
|
|
<code>window-padding-y = 2</code> will set both paddings to 2.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-padding-balance</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The viewport dimensions are usually not perfectly divisible by the
|
|||
|
|
cell size. In this case, some extra padding on the end of a column and
|
|||
|
|
the bottom of the final row may exist. If this is <code>true</code>,
|
|||
|
|
then this extra padding is automatically balanced between all four edges
|
|||
|
|
to minimize imbalance on one side. If this is <code>false</code>, the
|
|||
|
|
top left grid cell will always hug the edge with zero padding other than
|
|||
|
|
what may be specified with the other <code>window-padding</code>
|
|||
|
|
options.</p>
|
|||
|
|
<p>If other <code>window-padding</code> fields are set and this is
|
|||
|
|
<code>true</code>, this will still apply. The other padding is applied
|
|||
|
|
first and may affect how many grid cells actually exist, and this is
|
|||
|
|
applied last in order to balance the padding given a certain viewport
|
|||
|
|
size and grid cell size.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-padding-color</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The color of the padding area of the window. Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>background</code> - The background color specified in
|
|||
|
|
<code>background</code>.</li>
|
|||
|
|
<li><code>extend</code> - Extend the background color of the nearest
|
|||
|
|
grid cell.</li>
|
|||
|
|
<li><code>extend-always</code> - Same as “extend” but always extends
|
|||
|
|
without applying any of the heuristics that disable extending noted
|
|||
|
|
below.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The “extend” value will be disabled in certain scenarios. On primary
|
|||
|
|
screen applications (i.e. not something like Neovim), the color will not
|
|||
|
|
be extended vertically if any of the following are true:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>The nearest row has any cells that have the default background
|
|||
|
|
color. The thinking is that in this case, the default background color
|
|||
|
|
looks fine as a padding color.</li>
|
|||
|
|
<li>The nearest row is a prompt row (requires shell integration). The
|
|||
|
|
thinking here is that prompts often contain powerline glyphs that do not
|
|||
|
|
look good extended.</li>
|
|||
|
|
<li>The nearest row contains a perfect fit powerline character. These
|
|||
|
|
don’t look good extended.</li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-vsync</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Synchronize rendering with the screen refresh rate. If true, this
|
|||
|
|
will minimize tearing and align redraws with the screen but may cause
|
|||
|
|
input latency. If false, this will maximize redraw frequency but may
|
|||
|
|
cause tearing, and under heavy load may use more CPU and power.</p>
|
|||
|
|
<p>This defaults to true because out-of-sync rendering on macOS can
|
|||
|
|
cause kernel panics (macOS 14.4+) and performance issues for external
|
|||
|
|
displays over some hardware such as DisplayLink. If you want to minimize
|
|||
|
|
input latency, set this to false with the known aforementioned
|
|||
|
|
risks.</p>
|
|||
|
|
<p>Changing this value at runtime will only affect new terminals.</p>
|
|||
|
|
<p>This setting is only supported currently on macOS.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-inherit-working-directory</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If true, new windows and tabs will inherit the working directory of
|
|||
|
|
the previously focused window. If no window was previously focused, the
|
|||
|
|
default working directory will be used (the
|
|||
|
|
<code>working-directory</code> option).</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-inherit-font-size</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If true, new windows and tabs will inherit the font size of the
|
|||
|
|
previously focused window. If no window was previously focused, the
|
|||
|
|
default font size will be used. If this is false, the default font size
|
|||
|
|
specified in the configuration <code>font-size</code> will be used.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-decoration</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Valid values:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>true</code></li>
|
|||
|
|
<li><code>false</code> - windows won’t have native decorations,
|
|||
|
|
i.e. titlebar and borders. On macOS this also disables tabs and tab
|
|||
|
|
overview.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The “toggle_window_decorations” keybind action can be used to create
|
|||
|
|
a keybinding to toggle this setting at runtime.</p>
|
|||
|
|
<p>Changing this configuration in your configuration and reloading will
|
|||
|
|
only affect new windows. Existing windows will not be affected.</p>
|
|||
|
|
<p>macOS: To hide the titlebar without removing the native window
|
|||
|
|
borders or rounded corners, use
|
|||
|
|
<code>macos-titlebar-style = hidden</code> instead.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-title-font-family</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The font that will be used for the application’s window and tab
|
|||
|
|
titles.</p>
|
|||
|
|
<p>This is currently only supported on macOS.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-theme</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The theme to use for the windows. Valid values:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>auto</code> - Determine the theme based on the configured
|
|||
|
|
terminal background color. This has no effect if the “theme”
|
|||
|
|
configuration has separate light and dark themes. In that case, the
|
|||
|
|
behavior of “auto” is equivalent to “system”.</li>
|
|||
|
|
<li><code>system</code> - Use the system theme.</li>
|
|||
|
|
<li><code>light</code> - Use the light theme regardless of system
|
|||
|
|
theme.</li>
|
|||
|
|
<li><code>dark</code> - Use the dark theme regardless of system
|
|||
|
|
theme.</li>
|
|||
|
|
<li><code>ghostty</code> - Use the background and foreground colors
|
|||
|
|
specified in the Ghostty configuration. This is only supported on Linux
|
|||
|
|
builds with Adwaita and <code>gtk-adwaita</code> enabled.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>On macOS, if <code>macos-titlebar-style</code> is “tabs”, the window
|
|||
|
|
theme will be automatically set based on the luminosity of the terminal
|
|||
|
|
background color. This only applies to terminal windows. This setting
|
|||
|
|
will still apply to non-terminal windows within Ghostty.</p>
|
|||
|
|
<p>This is currently only supported on macOS and Linux.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-colorspace</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The colorspace to use for the terminal window. The default is
|
|||
|
|
<code>srgb</code> but this can also be set to <code>display-p3</code> to
|
|||
|
|
use the Display P3 colorspace.</p>
|
|||
|
|
<p>Changing this value at runtime will only affect new windows.</p>
|
|||
|
|
<p>This setting is only supported on macOS.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-height</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The initial window size. This size is in terminal grid cells by
|
|||
|
|
default. Both values must be set to take effect. If only one value is
|
|||
|
|
set, it is ignored.</p>
|
|||
|
|
<p>We don’t currently support specifying a size in pixels but a future
|
|||
|
|
change can enable that. If this isn’t specified, the app runtime will
|
|||
|
|
determine some default size.</p>
|
|||
|
|
<p>Note that the window manager may put limits on the size or override
|
|||
|
|
the size. For example, a tiling window manager may force the window to
|
|||
|
|
be a certain size to fit within the grid. There is nothing Ghostty will
|
|||
|
|
do about this, but it will make an effort.</p>
|
|||
|
|
<p>Sizes larger than the screen size will be clamped to the screen size.
|
|||
|
|
This can be used to create a maximized-by-default window size.</p>
|
|||
|
|
<p>This will not affect new tabs, splits, or other nested terminal
|
|||
|
|
elements. This only affects the initial window size of any new window.
|
|||
|
|
Changing this value will not affect the size of the window after it has
|
|||
|
|
been created. This is only used for the initial size.</p>
|
|||
|
|
<p>BUG: On Linux with GTK, the calculated window size will not properly
|
|||
|
|
take into account window decorations. As a result, the grid dimensions
|
|||
|
|
will not exactly match this configuration. If window decorations are
|
|||
|
|
disabled (see window-decorations), then this will work as expected.</p>
|
|||
|
|
<p>Windows smaller than 10 wide by 4 high are not allowed.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--window-width</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--window-save-state</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Whether to enable saving and restoring window state. Window state
|
|||
|
|
includes their position, size, tabs, splits, etc. Some window state
|
|||
|
|
requires shell integration, such as preserving working directories. See
|
|||
|
|
<code>shell-integration</code> for more information.</p>
|
|||
|
|
<p>There are three valid values for this configuration:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>default</code> will use the default system behavior. On
|
|||
|
|
macOS, this will only save state if the application is forcibly
|
|||
|
|
terminated or if it is configured systemwide via Settings.app.</p></li>
|
|||
|
|
<li><p><code>never</code> will never save window state.</p></li>
|
|||
|
|
<li><p><code>always</code> will always save window state whenever
|
|||
|
|
Ghostty is exited.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>If you change this value to <code>never</code> while Ghostty is not
|
|||
|
|
running, the next Ghostty launch will NOT restore the window state.</p>
|
|||
|
|
<p>If you change this value to <code>default</code> while Ghostty is not
|
|||
|
|
running and the previous exit saved state, the next Ghostty launch will
|
|||
|
|
still restore the window state. This is because Ghostty cannot know if
|
|||
|
|
the previous exit was due to a forced save or not (macOS doesn’t provide
|
|||
|
|
this information).</p>
|
|||
|
|
<p>If you change this value so that window state is saved while Ghostty
|
|||
|
|
is not running, the previous window state will not be restored because
|
|||
|
|
Ghostty only saves state on exit if this is enabled.</p>
|
|||
|
|
<p>The default value is <code>default</code>.</p>
|
|||
|
|
<p>This is currently only supported on macOS. This has no effect on
|
|||
|
|
Linux.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-step-resize</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Resize the window in discrete increments of the focused surface’s
|
|||
|
|
cell size. If this is disabled, surfaces are resized in pixel
|
|||
|
|
increments. Currently only supported on macOS.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--window-new-tab-position</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The position where new tabs are created. Valid values:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>current</code> - Insert the new tab after the currently
|
|||
|
|
focused tab, or at the end if there are no focused tabs.</p></li>
|
|||
|
|
<li><p><code>end</code> - Insert the new tab at the end of the tab
|
|||
|
|
list.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--resize-overlay</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>This controls when resize overlays are shown. Resize overlays are a
|
|||
|
|
transient popup that shows the size of the terminal while the surfaces
|
|||
|
|
are being resized. The possible options are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>always</code> - Always show resize overlays.</li>
|
|||
|
|
<li><code>never</code> - Never show resize overlays.</li>
|
|||
|
|
<li><code>after-first</code> - The resize overlay will not appear when
|
|||
|
|
the surface is first created, but will show up if the surface is
|
|||
|
|
subsequently resized.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The default is <code>after-first</code>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--resize-overlay-position</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If resize overlays are enabled, this controls the position of the
|
|||
|
|
overlay. The possible options are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>center</code></li>
|
|||
|
|
<li><code>top-left</code></li>
|
|||
|
|
<li><code>top-center</code></li>
|
|||
|
|
<li><code>top-right</code></li>
|
|||
|
|
<li><code>bottom-left</code></li>
|
|||
|
|
<li><code>bottom-center</code></li>
|
|||
|
|
<li><code>bottom-right</code></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The default is <code>center</code>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--resize-overlay-duration</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If resize overlays are enabled, this controls how long the overlay is
|
|||
|
|
visible on the screen before it is hidden. The default is ¾ of a second
|
|||
|
|
or 750 ms.</p>
|
|||
|
|
<p>The duration is specified as a series of numbers followed by time
|
|||
|
|
units. Whitespace is allowed between numbers and units. Each number and
|
|||
|
|
unit will be added together to form the total duration.</p>
|
|||
|
|
<p>The allowed time units are as follows:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>y</code> - 365 SI days, or 8760 hours, or 31536000 seconds. No
|
|||
|
|
adjustments are made for leap years or leap seconds.</li>
|
|||
|
|
<li><code>d</code> - one SI day, or 86400 seconds.</li>
|
|||
|
|
<li><code>h</code> - one hour, or 3600 seconds.</li>
|
|||
|
|
<li><code>m</code> - one minute, or 60 seconds.</li>
|
|||
|
|
<li><code>s</code> - one second.</li>
|
|||
|
|
<li><code>ms</code> - one millisecond, or 0.001 second.</li>
|
|||
|
|
<li><code>us</code> or <code>µs</code> - one microsecond, or 0.000001
|
|||
|
|
second.</li>
|
|||
|
|
<li><code>ns</code> - one nanosecond, or 0.000000001 second.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Examples: * <code>1h30m</code> * <code>45s</code></p>
|
|||
|
|
<p>Units can be repeated and will be added together. This means that
|
|||
|
|
<code>1h1h</code> is equivalent to <code>2h</code>. This is confusing
|
|||
|
|
and should be avoided. A future update may disallow this.</p>
|
|||
|
|
<p>The maximum value is
|
|||
|
|
<code>584y 49w 23h 34m 33s 709ms 551µs 615ns</code>. Any value larger
|
|||
|
|
than this will be clamped to the maximum value.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--focus-follows-mouse</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--clipboard-read</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Whether to allow programs running in the terminal to read/write to
|
|||
|
|
the system clipboard (OSC 52, for googling). The default is to allow
|
|||
|
|
clipboard reading after prompting the user and allow writing
|
|||
|
|
unconditionally.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>ask</code></li>
|
|||
|
|
<li><code>allow</code></li>
|
|||
|
|
<li><code>deny</code></li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<p><strong><code>--clipboard-write</code></strong></p>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong><code>--clipboard-trim-trailing-spaces</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Trims trailing whitespace on data that is copied to the clipboard.
|
|||
|
|
This does not affect data sent to the clipboard via
|
|||
|
|
<code>clipboard-write</code>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--clipboard-paste-protection</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Require confirmation before pasting text that appears unsafe. This
|
|||
|
|
helps prevent a “copy/paste attack” where a user may accidentally
|
|||
|
|
execute unsafe commands by pasting text with newlines.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--clipboard-paste-bracketed-safe</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If true, bracketed pastes will be considered safe. By default,
|
|||
|
|
bracketed pastes are considered safe. “Bracketed” pastes are pastes
|
|||
|
|
while the running program has bracketed paste mode enabled (a setting
|
|||
|
|
set by the running program, not the terminal emulator).</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--image-storage-limit</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The total amount of bytes that can be used for image data (i.e. the
|
|||
|
|
Kitty image protocol) per terminal screen. The maximum value is
|
|||
|
|
4,294,967,295 (4GiB). The default is 320MB. If this is set to zero, then
|
|||
|
|
all image protocols will be disabled.</p>
|
|||
|
|
<p>This value is separate for primary and alternate screens so the
|
|||
|
|
effective limit per surface is double.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--copy-on-select</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Whether to automatically copy selected text to the clipboard.
|
|||
|
|
<code>true</code> will prefer to copy to the selection clipboard if
|
|||
|
|
supported by the OS, otherwise it will copy to the system clipboard.</p>
|
|||
|
|
<p>The value <code>clipboard</code> will always copy text to the
|
|||
|
|
selection clipboard (for supported systems) as well as the system
|
|||
|
|
clipboard. This is sometimes a preferred behavior on Linux.</p>
|
|||
|
|
<p>Middle-click paste will always use the selection clipboard on Linux
|
|||
|
|
and the system clipboard on macOS. Middle-click paste is always enabled
|
|||
|
|
even if this is <code>false</code>.</p>
|
|||
|
|
<p>The default value is true on Linux and false on macOS. macOS copy on
|
|||
|
|
select behavior is not typical for applications so it is disabled by
|
|||
|
|
default. On Linux, this is a standard behavior so it is enabled by
|
|||
|
|
default.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--click-repeat-interval</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The time in milliseconds between clicks to consider a click a repeat
|
|||
|
|
(double, triple, etc.) or an entirely new single click. A value of zero
|
|||
|
|
will use a platform-specific default. The default on macOS is determined
|
|||
|
|
by the OS settings. On every other platform it is 500ms.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--config-file</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Additional configuration files to read. This configuration can be
|
|||
|
|
repeated to read multiple configuration files. Configuration files
|
|||
|
|
themselves can load more configuration files. Paths are relative to the
|
|||
|
|
file containing the <code>config-file</code> directive. For command-line
|
|||
|
|
arguments, paths are relative to the current working directory.</p>
|
|||
|
|
<p>Prepend a ? character to the file path to suppress errors if the file
|
|||
|
|
does not exist. If you want to include a file that begins with a literal
|
|||
|
|
? character, surround the file path in double quotes (“).</p>
|
|||
|
|
<p>Cycles are not allowed. If a cycle is detected, an error will be
|
|||
|
|
logged and the configuration file will be ignored.</p>
|
|||
|
|
<p>Configuration files are loaded after the configuration they’re
|
|||
|
|
defined within in the order they’re defined. <strong>THIS IS A VERY
|
|||
|
|
SUBTLE BUT IMPORTANT POINT.</strong> To put it another way:
|
|||
|
|
configuration files do not take effect until after the entire
|
|||
|
|
configuration is loaded. For example, in the configuration below:</p>
|
|||
|
|
<pre><code>config-file = "foo"
|
|||
|
|
a = 1</code></pre>
|
|||
|
|
<p>If “foo” contains <code>a = 2</code>, the final value of
|
|||
|
|
<code>a</code> will be 2, because <code>foo</code> is loaded after the
|
|||
|
|
configuration file that configures the nested <code>config-file</code>
|
|||
|
|
value.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--config-default-files</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>When this is true, the default configuration file paths will be
|
|||
|
|
loaded. The default configuration file paths are currently only the XDG
|
|||
|
|
config path ($XDG_CONFIG_HOME/ghostty/config).</p>
|
|||
|
|
<p>If this is false, the default configuration paths will not be loaded.
|
|||
|
|
This is targeted directly at using Ghostty from the CLI in a way that
|
|||
|
|
minimizes external effects.</p>
|
|||
|
|
<p>This is a CLI-only configuration. Setting this in a configuration
|
|||
|
|
file will have no effect. It is not an error, but it will not do
|
|||
|
|
anything. This configuration can only be set via CLI arguments.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--confirm-close-surface</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Confirms that a surface should be closed before closing it. This
|
|||
|
|
defaults to true. If set to false, surfaces will close without any
|
|||
|
|
confirmation.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--quit-after-last-window-closed</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Whether or not to quit after the last surface is closed.</p>
|
|||
|
|
<p>This defaults to <code>false</code> on macOS since that is standard
|
|||
|
|
behavior for a macOS application. On Linux, this defaults to
|
|||
|
|
<code>true</code> since that is generally expected behavior.</p>
|
|||
|
|
<p>On Linux, if this is <code>true</code>, Ghostty can delay quitting
|
|||
|
|
fully until a configurable amount of time has passed after the last
|
|||
|
|
window is closed. See the documentation of
|
|||
|
|
<code>quit-after-last-window-closed-delay</code>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--quit-after-last-window-closed-delay</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Controls how long Ghostty will stay running after the last open
|
|||
|
|
surface has been closed. This only has an effect if
|
|||
|
|
<code>quit-after-last-window-closed</code> is also set to
|
|||
|
|
<code>true</code>.</p>
|
|||
|
|
<p>The minimum value for this configuration is <code>1s</code>. Any
|
|||
|
|
values lower than this will be clamped to <code>1s</code>.</p>
|
|||
|
|
<p>The duration is specified as a series of numbers followed by time
|
|||
|
|
units. Whitespace is allowed between numbers and units. Each number and
|
|||
|
|
unit will be added together to form the total duration.</p>
|
|||
|
|
<p>The allowed time units are as follows:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>y</code> - 365 SI days, or 8760 hours, or 31536000 seconds. No
|
|||
|
|
adjustments are made for leap years or leap seconds.</li>
|
|||
|
|
<li><code>d</code> - one SI day, or 86400 seconds.</li>
|
|||
|
|
<li><code>h</code> - one hour, or 3600 seconds.</li>
|
|||
|
|
<li><code>m</code> - one minute, or 60 seconds.</li>
|
|||
|
|
<li><code>s</code> - one second.</li>
|
|||
|
|
<li><code>ms</code> - one millisecond, or 0.001 second.</li>
|
|||
|
|
<li><code>us</code> or <code>µs</code> - one microsecond, or 0.000001
|
|||
|
|
second.</li>
|
|||
|
|
<li><code>ns</code> - one nanosecond, or 0.000000001 second.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Examples: * <code>1h30m</code> * <code>45s</code></p>
|
|||
|
|
<p>Units can be repeated and will be added together. This means that
|
|||
|
|
<code>1h1h</code> is equivalent to <code>2h</code>. This is confusing
|
|||
|
|
and should be avoided. A future update may disallow this.</p>
|
|||
|
|
<p>The maximum value is
|
|||
|
|
<code>584y 49w 23h 34m 33s 709ms 551µs 615ns</code>. Any value larger
|
|||
|
|
than this will be clamped to the maximum value.</p>
|
|||
|
|
<p>By default <code>quit-after-last-window-closed-delay</code> is unset
|
|||
|
|
and Ghostty will quit immediately after the last window is closed if
|
|||
|
|
<code>quit-after-last-window-closed</code> is <code>true</code>.</p>
|
|||
|
|
<p>Only implemented on Linux.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--initial-window</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>This controls whether an initial window is created when Ghostty is
|
|||
|
|
run. Note that if <code>quit-after-last-window-closed</code> is
|
|||
|
|
<code>true</code> and <code>quit-after-last-window-closed-delay</code>
|
|||
|
|
is set, setting <code>initial-window</code> to <code>false</code> will
|
|||
|
|
mean that Ghostty will quit after the configured delay if no window is
|
|||
|
|
ever created. Only implemented on Linux and macOS.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--quick-terminal-position</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The position of the “quick” terminal window. To learn more about the
|
|||
|
|
quick terminal, see the documentation for the
|
|||
|
|
<code>toggle_quick_terminal</code> binding action.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>top</code> - Terminal appears at the top of the screen.</li>
|
|||
|
|
<li><code>bottom</code> - Terminal appears at the bottom of the
|
|||
|
|
screen.</li>
|
|||
|
|
<li><code>left</code> - Terminal appears at the left of the screen.</li>
|
|||
|
|
<li><code>right</code> - Terminal appears at the right of the
|
|||
|
|
screen.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Changing this configuration requires restarting Ghostty
|
|||
|
|
completely.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--quick-terminal-screen</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The screen where the quick terminal should show up.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>main</code> - The screen that the operating system
|
|||
|
|
recommends as the main screen. On macOS, this is the screen that is
|
|||
|
|
currently receiving keyboard input. This screen is defined by the
|
|||
|
|
operating system and not chosen by Ghostty.</p></li>
|
|||
|
|
<li><p><code>mouse</code> - The screen that the mouse is currently
|
|||
|
|
hovered over.</p></li>
|
|||
|
|
<li><p><code>macos-menu-bar</code> - The screen that contains the macOS
|
|||
|
|
menu bar as set in the display settings on macOS. This is a bit
|
|||
|
|
confusing because every screen on macOS has a menu bar, but this is the
|
|||
|
|
screen that contains the primary menu bar.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The default value is <code>main</code> because this is the
|
|||
|
|
recommended screen by the operating system.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--quick-terminal-animation-duration</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Duration (in seconds) of the quick terminal enter and exit animation.
|
|||
|
|
Set it to 0 to disable animation completely. This can be changed at
|
|||
|
|
runtime.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--shell-integration</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Whether to enable shell integration auto-injection or not. Shell
|
|||
|
|
integration greatly enhances the terminal experience by enabling a
|
|||
|
|
number of features:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p>Working directory reporting so new tabs, splits inherit the
|
|||
|
|
previous terminal’s working directory.</p></li>
|
|||
|
|
<li><p>Prompt marking that enables the “jump_to_prompt”
|
|||
|
|
keybinding.</p></li>
|
|||
|
|
<li><p>If you’re sitting at a prompt, closing a terminal will not ask
|
|||
|
|
for confirmation.</p></li>
|
|||
|
|
<li><p>Resizing the window with a complex prompt usually paints much
|
|||
|
|
better.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Allowable values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>none</code> - Do not do any automatic injection. You can
|
|||
|
|
still manually configure your shell to enable the integration.</p></li>
|
|||
|
|
<li><p><code>detect</code> - Detect the shell based on the
|
|||
|
|
filename.</p></li>
|
|||
|
|
<li><p><code>bash</code>, <code>elvish</code>, <code>fish</code>,
|
|||
|
|
<code>zsh</code> - Use this specific shell injection scheme.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The default value is <code>detect</code>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--shell-integration-features</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Shell integration features to enable if shell integration itself is
|
|||
|
|
enabled. The format of this is a list of features to enable separated by
|
|||
|
|
commas. If you prefix a feature with <code>no-</code> then it is
|
|||
|
|
disabled. If you omit a feature, its default value is used, so you must
|
|||
|
|
explicitly disable features you don’t want. You can also use
|
|||
|
|
<code>true</code> or <code>false</code> to turn all features on or
|
|||
|
|
off.</p>
|
|||
|
|
<p>Available features:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>cursor</code> - Set the cursor to a blinking bar at the
|
|||
|
|
prompt.</p></li>
|
|||
|
|
<li><p><code>sudo</code> - Set sudo wrapper to preserve
|
|||
|
|
terminfo.</p></li>
|
|||
|
|
<li><p><code>title</code> - Set the window title via shell
|
|||
|
|
integration.</p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Example: <code>cursor</code>, <code>no-cursor</code>,
|
|||
|
|
<code>sudo</code>, <code>no-sudo</code>, <code>title</code>,
|
|||
|
|
<code>no-title</code></p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--osc-color-report-format</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Sets the reporting format for OSC sequences that request color
|
|||
|
|
information. Ghostty currently supports OSC 10 (foreground), OSC 11
|
|||
|
|
(background), and OSC 4 (256 color palette) queries, and by default the
|
|||
|
|
reported values are scaled-up RGB values, where each component are 16
|
|||
|
|
bits. This is how most terminals report these values. However, some
|
|||
|
|
legacy applications may require 8-bit, unscaled, components. We also
|
|||
|
|
support turning off reporting altogether. The components are lowercase
|
|||
|
|
hex values.</p>
|
|||
|
|
<p>Allowable values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><p><code>none</code> - OSC 4/10/11 queries receive no reply</p></li>
|
|||
|
|
<li><p><code>8-bit</code> - Color components are return unscaled,
|
|||
|
|
i.e. <code>rr/gg/bb</code></p></li>
|
|||
|
|
<li><p><code>16-bit</code> - Color components are returned scaled,
|
|||
|
|
e.g. <code>rrrr/gggg/bbbb</code></p></li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The default value is <code>16-bit</code>.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--vt-kam-allowed</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If true, allows the “KAM” mode (ANSI mode 2) to be used within the
|
|||
|
|
terminal. KAM disables keyboard input at the request of the application.
|
|||
|
|
This is not a common feature and is not recommended to be enabled. This
|
|||
|
|
will not be documented further because if you know you need KAM, you
|
|||
|
|
know. If you don’t know if you need KAM, you don’t need it.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--custom-shader</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Custom shaders to run after the default shaders. This is a file path
|
|||
|
|
to a GLSL-syntax shader for all platforms.</p>
|
|||
|
|
<p>Warning: Invalid shaders can cause Ghostty to become unusable such as
|
|||
|
|
by causing the window to be completely black. If this happens, you can
|
|||
|
|
unset this configuration to disable the shader.</p>
|
|||
|
|
<p>On Linux, this requires OpenGL 4.2. Ghostty typically only requires
|
|||
|
|
OpenGL 3.3, but custom shaders push that requirement up to 4.2.</p>
|
|||
|
|
<p>The shader API is identical to the Shadertoy API: you specify a
|
|||
|
|
<code>mainImage</code> function and the available uniforms match
|
|||
|
|
Shadertoy. The iChannel0 uniform is a texture containing the rendered
|
|||
|
|
terminal screen.</p>
|
|||
|
|
<p>If the shader fails to compile, the shader will be ignored. Any
|
|||
|
|
errors related to shader compilation will not show up as configuration
|
|||
|
|
errors and only show up in the log, since shader compilation happens
|
|||
|
|
after configuration loading on the dedicated render thread. For
|
|||
|
|
interactive development, use <a
|
|||
|
|
href="https://shadertoy.com">shadertoy.com</a>.</p>
|
|||
|
|
<p>This can be repeated multiple times to load multiple shaders. The
|
|||
|
|
shaders will be run in the order they are specified.</p>
|
|||
|
|
<p>Changing this value at runtime and reloading the configuration will
|
|||
|
|
only affect new windows, tabs, and splits.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--custom-shader-animation</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If <code>true</code> (default), the focused terminal surface will run
|
|||
|
|
an animation loop when custom shaders are used. This uses slightly more
|
|||
|
|
CPU (generally less than 10%) but allows the shader to animate. This
|
|||
|
|
only runs if there are custom shaders and the terminal is focused.</p>
|
|||
|
|
<p>If this is set to <code>false</code>, the terminal and custom shader
|
|||
|
|
will only render when the terminal is updated. This is more efficient
|
|||
|
|
but the shader will not animate.</p>
|
|||
|
|
<p>This can also be set to <code>always</code>, which will always run
|
|||
|
|
the animation loop regardless of whether the terminal is focused or not.
|
|||
|
|
The animation loop will still only run when custom shaders are used.
|
|||
|
|
Note that this will use more CPU per terminal surface and can become
|
|||
|
|
quite expensive depending on the shader and your terminal usage.</p>
|
|||
|
|
<p>This value can be changed at runtime and will affect all currently
|
|||
|
|
open terminals.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--macos-non-native-fullscreen</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If anything other than false, fullscreen mode on macOS will not use
|
|||
|
|
the native fullscreen, but make the window fullscreen without animations
|
|||
|
|
and using a new space. It’s faster than the native fullscreen mode since
|
|||
|
|
it doesn’t use animations.</p>
|
|||
|
|
<p>Important: tabs DO NOT WORK in this mode. Non-native fullscreen
|
|||
|
|
removes the titlebar and macOS native tabs require the titlebar. If you
|
|||
|
|
use tabs, you should not use this mode.</p>
|
|||
|
|
<p>If you fullscreen a window with tabs, the currently focused tab will
|
|||
|
|
become fullscreen while the others will remain in a separate window in
|
|||
|
|
the background. You can switch to that window using normal
|
|||
|
|
window-switching keybindings such as command+tilde. When you exit
|
|||
|
|
fullscreen, the window will return to the tabbed state it was in
|
|||
|
|
before.</p>
|
|||
|
|
<p>Allowable values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>visible-menu</code> - Use non-native macOS fullscreen, keep
|
|||
|
|
the menu bar visible</li>
|
|||
|
|
<li><code>true</code> - Use non-native macOS fullscreen, hide the menu
|
|||
|
|
bar</li>
|
|||
|
|
<li><code>false</code> - Use native macOS fullscreen</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Changing this option at runtime works, but will only apply to the
|
|||
|
|
next time the window is made fullscreen. If a window is already
|
|||
|
|
fullscreen, it will retain the previous setting until fullscreen is
|
|||
|
|
exited.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--macos-titlebar-style</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The style of the macOS titlebar. Available values are: “native”,
|
|||
|
|
“transparent”, “tabs”, and “hidden”.</p>
|
|||
|
|
<p>The “native” style uses the native macOS titlebar with zero
|
|||
|
|
customization. The titlebar will match your window theme (see
|
|||
|
|
<code>window-theme</code>).</p>
|
|||
|
|
<p>The “transparent” style is the same as “native” but the titlebar will
|
|||
|
|
be transparent and allow your window background color to come through.
|
|||
|
|
This makes a more seamless window appearance but looks a little less
|
|||
|
|
typical for a macOS application and may not work well with all
|
|||
|
|
themes.</p>
|
|||
|
|
<p>The “transparent” style will also update in real-time to dynamic
|
|||
|
|
changes to the window background color, i.e. via OSC 11. To make this
|
|||
|
|
more aesthetically pleasing, this only happens if the terminal is a
|
|||
|
|
window, tab, or split that borders the top of the window. This avoids a
|
|||
|
|
disjointed appearance where the titlebar color changes but all the
|
|||
|
|
topmost terminals don’t match.</p>
|
|||
|
|
<p>The “tabs” style is a completely custom titlebar that integrates the
|
|||
|
|
tab bar into the titlebar. This titlebar always matches the background
|
|||
|
|
color of the terminal. There are some limitations to this style: On
|
|||
|
|
macOS 13 and below, saved window state will not restore tabs correctly.
|
|||
|
|
macOS 14 does not have this issue and any other macOS version has not
|
|||
|
|
been tested.</p>
|
|||
|
|
<p>The “hidden” style hides the titlebar. Unlike
|
|||
|
|
<code>window-decoration = false</code>, however, it does not remove the
|
|||
|
|
frame from the window or cause it to have squared corners. Changing to
|
|||
|
|
or from this option at run-time may affect existing windows in buggy
|
|||
|
|
ways. The top titlebar area of the window will continue to drag the
|
|||
|
|
window around and you will not be able to use the mouse for terminal
|
|||
|
|
events in this space.</p>
|
|||
|
|
<p>The default value is “transparent”. This is an opinionated choice but
|
|||
|
|
its one I think is the most aesthetically pleasing and works in most
|
|||
|
|
cases.</p>
|
|||
|
|
<p>Changing this option at runtime only applies to new windows.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--macos-titlebar-proxy-icon</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Whether the proxy icon in the macOS titlebar is visible. The proxy
|
|||
|
|
icon is the icon that represents the folder of the current working
|
|||
|
|
directory. You can see this very clearly in the macOS built-in
|
|||
|
|
Terminal.app titlebar.</p>
|
|||
|
|
<p>The proxy icon is only visible with the native macOS titlebar
|
|||
|
|
style.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>visible</code> - Show the proxy icon.</li>
|
|||
|
|
<li><code>hidden</code> - Hide the proxy icon.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The default value is <code>visible</code>.</p>
|
|||
|
|
<p>This setting can be changed at runtime and will affect all currently
|
|||
|
|
open windows but only after their working directory changes again.
|
|||
|
|
Therefore, to make this work after changing the setting, you must
|
|||
|
|
usually <code>cd</code> to a different directory, open a different file
|
|||
|
|
in an editor, etc.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--macos-option-as-alt</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>macOS doesn’t have a distinct “alt” key and instead has the “option”
|
|||
|
|
key which behaves slightly differently. On macOS by default, the option
|
|||
|
|
key plus a character will sometimes produces a Unicode character. For
|
|||
|
|
example, on US standard layouts option-b produces “∫”. This may be
|
|||
|
|
undesirable if you want to use “option” as an “alt” key for keybindings
|
|||
|
|
in terminal programs or shells.</p>
|
|||
|
|
<p>This configuration lets you change the behavior so that option is
|
|||
|
|
treated as alt.</p>
|
|||
|
|
<p>The default behavior (unset) will depend on your active keyboard
|
|||
|
|
layout. If your keyboard layout is one of the keyboard layouts listed
|
|||
|
|
below, then the default value is “true”. Otherwise, the default value is
|
|||
|
|
“false”. Keyboard layouts with a default value of “true” are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li>U.S. Standard</li>
|
|||
|
|
<li>U.S. International</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Note that if an <em>Option</em>-sequence doesn’t produce a printable
|
|||
|
|
character, it will be treated as <em>Alt</em> regardless of this
|
|||
|
|
setting. (i.e. <code>alt+ctrl+a</code>).</p>
|
|||
|
|
<p>Explicit values that can be set:</p>
|
|||
|
|
<p>If <code>true</code>, the <em>Option</em> key will be treated as
|
|||
|
|
<em>Alt</em>. This makes terminal sequences expecting <em>Alt</em> to
|
|||
|
|
work properly, but will break Unicode input sequences on macOS if you
|
|||
|
|
use them via the <em>Alt</em> key.</p>
|
|||
|
|
<p>You may set this to <code>false</code> to restore the macOS
|
|||
|
|
<em>Alt</em> key unicode sequences but this will break terminal
|
|||
|
|
sequences expecting <em>Alt</em> to work.</p>
|
|||
|
|
<p>The values <code>left</code> or <code>right</code> enable this for
|
|||
|
|
the left or right <em>Option</em> key, respectively.</p>
|
|||
|
|
<p>This does not work with GLFW builds.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--macos-window-shadow</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Whether to enable the macOS window shadow. The default value is true.
|
|||
|
|
With some window managers and window transparency settings, you may find
|
|||
|
|
false more visually appealing.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--macos-auto-secure-input</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If true, Ghostty on macOS will automatically enable the “Secure
|
|||
|
|
Input” feature when it detects that a password prompt is being
|
|||
|
|
displayed.</p>
|
|||
|
|
<p>“Secure Input” is a macOS security feature that prevents applications
|
|||
|
|
from reading keyboard events. This can always be enabled manually using
|
|||
|
|
the <code>Ghostty > Secure Keyboard Entry</code> menu item.</p>
|
|||
|
|
<p>Note that automatic password prompt detection is based on heuristics
|
|||
|
|
and may not always work as expected. Specifically, it does not work over
|
|||
|
|
SSH connections, but there may be other cases where it also doesn’t
|
|||
|
|
work.</p>
|
|||
|
|
<p>A reason to disable this feature is if you find that it is
|
|||
|
|
interfering with legitimate accessibility software (or software that
|
|||
|
|
uses the accessibility APIs), since secure input prevents any
|
|||
|
|
application from reading keyboard events.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--macos-secure-input-indication</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If true, Ghostty will show a graphical indication when secure input
|
|||
|
|
is enabled. This indication is generally recommended to know when secure
|
|||
|
|
input is enabled.</p>
|
|||
|
|
<p>Normally, secure input is only active when a password prompt is
|
|||
|
|
displayed or it is manually (and typically temporarily) enabled.
|
|||
|
|
However, if you always have secure input enabled, the indication can be
|
|||
|
|
distracting and you may want to disable it.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--linux-cgroup</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Put every surface (tab, split, window) into a dedicated Linux
|
|||
|
|
cgroup.</p>
|
|||
|
|
<p>This makes it so that resource management can be done on a
|
|||
|
|
per-surface granularity. For example, if a shell program is using too
|
|||
|
|
much memory, only that shell will be killed by the oom monitor instead
|
|||
|
|
of the entire Ghostty process. Similarly, if a shell program is using
|
|||
|
|
too much CPU, only that surface will be CPU-throttled.</p>
|
|||
|
|
<p>This will cause startup times to be slower (a hundred milliseconds or
|
|||
|
|
so), so the default value is “single-instance.” In single-instance mode,
|
|||
|
|
only one instance of Ghostty is running (see gtk-single-instance) so the
|
|||
|
|
startup time is a one-time cost. Additionally, single instance Ghostty
|
|||
|
|
is much more likely to have many windows, tabs, etc. so cgroup isolation
|
|||
|
|
is a big benefit.</p>
|
|||
|
|
<p>This feature requires systemd. If systemd is unavailable, cgroup
|
|||
|
|
initialization will fail. By default, this will not prevent Ghostty from
|
|||
|
|
working (see linux-cgroup-hard-fail).</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>never</code> - Never use cgroups.</li>
|
|||
|
|
<li><code>always</code> - Always use cgroups.</li>
|
|||
|
|
<li><code>single-instance</code> - Enable cgroups only for Ghostty
|
|||
|
|
instances launched as single-instance applications (see
|
|||
|
|
gtk-single-instance).</li>
|
|||
|
|
</ul>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--linux-cgroup-memory-limit</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Memory limit for any individual terminal process (tab, split, window,
|
|||
|
|
etc.) in bytes. If this is unset then no memory limit will be set.</p>
|
|||
|
|
<p>Note that this sets the “memory.high” configuration for the memory
|
|||
|
|
controller, which is a soft limit. You should configure something like
|
|||
|
|
systemd-oom to handle killing processes that have too much memory
|
|||
|
|
pressure.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--linux-cgroup-processes-limit</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Number of processes limit for any individual terminal process (tab,
|
|||
|
|
split, window, etc.). If this is unset then no limit will be set.</p>
|
|||
|
|
<p>Note that this sets the “pids.max” configuration for the process
|
|||
|
|
number controller, which is a hard limit.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--linux-cgroup-hard-fail</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If this is false, then any cgroup initialization (for linux-cgroup)
|
|||
|
|
will be allowed to fail and the failure is ignored. This is useful if
|
|||
|
|
you view cgroup isolation as a “nice to have” and not a critical
|
|||
|
|
resource management feature, because Ghostty startup will not fail if
|
|||
|
|
cgroup APIs fail.</p>
|
|||
|
|
<p>If this is true, then any cgroup initialization failure will cause
|
|||
|
|
Ghostty to exit or new surfaces to not be created.</p>
|
|||
|
|
<p>Note: This currently only affects cgroup initialization. Subprocesses
|
|||
|
|
must always be able to move themselves into an isolated cgroup.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--gtk-single-instance</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If <code>true</code>, the Ghostty GTK application will run in
|
|||
|
|
single-instance mode: each new <code>ghostty</code> process launched
|
|||
|
|
will result in a new window if there is already a running process.</p>
|
|||
|
|
<p>If <code>false</code>, each new ghostty process will launch a
|
|||
|
|
separate application.</p>
|
|||
|
|
<p>The default value is <code>detect</code> which will default to
|
|||
|
|
<code>true</code> if Ghostty detects that it was launched from the
|
|||
|
|
<code>.desktop</code> file such as an app launcher (like Gnome Shell) or
|
|||
|
|
by D-Bus activation. If Ghostty is launched from the command line, it
|
|||
|
|
will default to <code>false</code>.</p>
|
|||
|
|
<p>Note that debug builds of Ghostty have a separate single-instance ID
|
|||
|
|
so you can test single instance without conflicting with release
|
|||
|
|
builds.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--gtk-titlebar</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>When enabled, the full GTK titlebar is displayed instead of your
|
|||
|
|
window manager’s simple titlebar. The behavior of this option will vary
|
|||
|
|
with your window manager.</p>
|
|||
|
|
<p>This option does nothing when <code>window-decoration</code> is false
|
|||
|
|
or when running under macOS.</p>
|
|||
|
|
<p>Changing this value at runtime and reloading the configuration will
|
|||
|
|
only affect new windows.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--gtk-tabs-location</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Determines the side of the screen that the GTK tab bar will stick to.
|
|||
|
|
Top, bottom, left, right, and hidden are supported. The default is
|
|||
|
|
top.</p>
|
|||
|
|
<p>If this option has value <code>left</code> or <code>right</code> when
|
|||
|
|
using Adwaita, it falls back to <code>top</code>. <code>hidden</code>,
|
|||
|
|
meaning that tabs don’t exist, is not supported without using Adwaita,
|
|||
|
|
falling back to <code>top</code>.</p>
|
|||
|
|
<p>When <code>hidden</code> is set and Adwaita is enabled, a tab button
|
|||
|
|
displaying the number of tabs will appear in the title bar. It has the
|
|||
|
|
ability to open a tab overview for displaying tabs. Alternatively, you
|
|||
|
|
can use the <code>toggle_tab_overview</code> action in a keybind if your
|
|||
|
|
window doesn’t have a title bar, or you can switch tabs with
|
|||
|
|
keybinds.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--adw-toolbar-style</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Determines the appearance of the top and bottom bars when using the
|
|||
|
|
Adwaita tab bar. This requires <code>gtk-adwaita</code> to be enabled
|
|||
|
|
(it is by default).</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>flat</code> - Top and bottom bars are flat with the terminal
|
|||
|
|
window.</li>
|
|||
|
|
<li><code>raised</code> - Top and bottom bars cast a shadow on the
|
|||
|
|
terminal area.</li>
|
|||
|
|
<li><code>raised-border</code> - Similar to <code>raised</code> but the
|
|||
|
|
shadow is replaced with a more subtle border.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Changing this value at runtime will only affect new windows.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--gtk-wide-tabs</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If <code>true</code> (default), then the Ghostty GTK tabs will be
|
|||
|
|
“wide.” Wide tabs are the new typical Gnome style where tabs fill their
|
|||
|
|
available space. If you set this to <code>false</code> then tabs will
|
|||
|
|
only take up space they need, which is the old style.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--gtk-adwaita</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If <code>true</code> (default), Ghostty will enable Adwaita theme
|
|||
|
|
support. This will make <code>window-theme</code> work properly and will
|
|||
|
|
also allow Ghostty to properly respond to system theme changes,
|
|||
|
|
light/dark mode changing, etc. This requires a GTK4 desktop with a GTK4
|
|||
|
|
theme.</p>
|
|||
|
|
<p>If you are running GTK3 or have a GTK3 theme, you may have to set
|
|||
|
|
this to false to get your theme picked up properly. Having this set to
|
|||
|
|
true with GTK3 should not cause any problems, but it may not work
|
|||
|
|
exactly as expected.</p>
|
|||
|
|
<p>This configuration only has an effect if Ghostty was built with
|
|||
|
|
Adwaita support.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--desktop-notifications</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If <code>true</code> (default), applications running in the terminal
|
|||
|
|
can show desktop notifications using certain escape sequences such as
|
|||
|
|
OSC 9 or OSC 777.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--bold-is-bright</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>If <code>true</code>, the bold text will use the bright color
|
|||
|
|
palette.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--term</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>This will be used to set the <code>TERM</code> environment variable.
|
|||
|
|
HACK: We set this with an <code>xterm</code> prefix because vim uses
|
|||
|
|
that to enable key protocols (specifically this will enable
|
|||
|
|
<code>modifyOtherKeys</code>), among other features. An option exists in
|
|||
|
|
vim to modify this: <code>:set keyprotocol=ghostty:kitty</code>, however
|
|||
|
|
a bug in the implementation prevents it from working properly.
|
|||
|
|
https://github.com/vim/vim/pull/13211 fixes this.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--enquiry-response</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>String to send when we receive <code>ENQ</code> (<code>0x05</code>)
|
|||
|
|
from the command that we are running. Defaults to an empty string if not
|
|||
|
|
set.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--auto-update</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Control the auto-update functionality of Ghostty. This is only
|
|||
|
|
supported on macOS currently, since Linux builds are distributed via
|
|||
|
|
package managers that are not centrally controlled by Ghostty.</p>
|
|||
|
|
<p>Checking or downloading an update does not send any information to
|
|||
|
|
the project beyond standard network information mandated by the
|
|||
|
|
underlying protocols. To put it another way: Ghostty doesn’t explicitly
|
|||
|
|
add any tracking to the update process. The update process works by
|
|||
|
|
downloading information about the latest version and comparing it
|
|||
|
|
client-side to the current version.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>off</code> - Disable auto-updates.</li>
|
|||
|
|
<li><code>check</code> - Check for updates and notify the user if an
|
|||
|
|
update is available, but do not automatically download or install the
|
|||
|
|
update.</li>
|
|||
|
|
<li><code>download</code> - Check for updates, automatically download
|
|||
|
|
the update, notify the user, but do not automatically install the
|
|||
|
|
update.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>The default value is <code>check</code>.</p>
|
|||
|
|
<p>Changing this value at runtime works after a small delay.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong><code>--auto-update-channel</code></strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>The release channel to use for auto-updates.</p>
|
|||
|
|
<p>The default value of this matches the release channel of the
|
|||
|
|
currently running Ghostty version. If you download a pre-release version
|
|||
|
|
of Ghostty then this will be set to <code>tip</code> and you will
|
|||
|
|
receive pre-release updates. If you download a stable version of Ghostty
|
|||
|
|
then this will be set to <code>stable</code> and you will receive stable
|
|||
|
|
updates.</p>
|
|||
|
|
<p>Valid values are:</p>
|
|||
|
|
<ul>
|
|||
|
|
<li><code>stable</code> - Stable, tagged releases such as “1.0.0”.</li>
|
|||
|
|
<li><code>tip</code> - Pre-release versions generated from each commit
|
|||
|
|
to the main branch. This is the version that was in use during private
|
|||
|
|
beta testing by thousands of people. It is generally stable but will
|
|||
|
|
likely have more bugs than the stable channel.</li>
|
|||
|
|
</ul>
|
|||
|
|
<p>Changing this configuration requires a full restart of Ghostty to
|
|||
|
|
take effect.</p>
|
|||
|
|
<p>This only works on macOS since only macOS has an auto-update
|
|||
|
|
feature.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<h1 id="files">FILES</h1>
|
|||
|
|
<dl>
|
|||
|
|
<dt><em>$XDG_CONFIG_HOME/ghostty/config</em></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Location of the default configuration file.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><em>$LOCALAPPDATA/ghostty/config</em></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p><strong>On Windows</strong>, if <em>$XDG_CONFIG_HOME</em> is not set,
|
|||
|
|
<em>$LOCALAPPDATA</em> will be searched for configuration files.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<h1 id="environment">ENVIRONMENT</h1>
|
|||
|
|
<dl>
|
|||
|
|
<dt><strong>TERM</strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Defaults to <code>xterm-ghostty</code>. Can be configured with the
|
|||
|
|
<code>term</code> configuration option.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong>GHOSTTY_RESOURCES_DIR</strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Where the Ghostty resources can be found.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong>XDG_CONFIG_HOME</strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p>Default location for configuration files.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><strong>LOCALAPPDATA</strong></dt>
|
|||
|
|
<dd>
|
|||
|
|
<p><strong>WINDOWS ONLY:</strong> alternate location to search for
|
|||
|
|
configuration files.</p>
|
|||
|
|
</dd>
|
|||
|
|
</dl>
|
|||
|
|
<h1 id="bugs">BUGS</h1>
|
|||
|
|
<p>See GitHub issues: <a
|
|||
|
|
href="https://github.com/ghostty-org/ghostty/issues"
|
|||
|
|
class="uri">https://github.com/ghostty-org/ghostty/issues</a></p>
|
|||
|
|
<h1 id="author">AUTHOR</h1>
|
|||
|
|
<p>Mitchell Hashimoto <a href="mailto:m@mitchellh.com"
|
|||
|
|
class="email">m@mitchellh.com</a></p>
|
|||
|
|
<h1 id="see-also">SEE ALSO</h1>
|
|||
|
|
<p><strong>ghostty(5)</strong></p>
|
|||
|
|
</body>
|
|||
|
|
</html>
|