marcus.hinz
ce173ebbdf
War durch .gitignore-Regel *.app/ ausgeschlossen; make-ghostty-app.sh braucht es aber als Basis. Explizit per git add -f aufgenommen.
4227 lines
199 KiB
HTML
4227 lines
199 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 1.3.1 | 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 {
|
||
border: none;
|
||
border-top: 1px solid #1a1a1a;
|
||
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;}
|
||
/* CSS for syntax highlighting */
|
||
html { -webkit-text-size-adjust: 100%; }
|
||
pre > code.sourceCode { white-space: pre; position: relative; }
|
||
pre > code.sourceCode > span { display: inline-block; line-height: 1.25; }
|
||
pre > code.sourceCode > span:empty { height: 1.2em; }
|
||
.sourceCode { overflow: visible; }
|
||
code.sourceCode > span { color: inherit; text-decoration: inherit; }
|
||
div.sourceCode { margin: 1em 0; }
|
||
pre.sourceCode { margin: 0; }
|
||
@media screen {
|
||
div.sourceCode { overflow: auto; }
|
||
}
|
||
@media print {
|
||
pre > code.sourceCode { white-space: pre-wrap; }
|
||
pre > code.sourceCode > span { text-indent: -5em; padding-left: 5em; }
|
||
}
|
||
pre.numberSource code
|
||
{ counter-reset: source-line 0; }
|
||
pre.numberSource code > span
|
||
{ position: relative; left: -4em; counter-increment: source-line; }
|
||
pre.numberSource code > span > a:first-child::before
|
||
{ content: counter(source-line);
|
||
position: relative; left: -1em; text-align: right; vertical-align: baseline;
|
||
border: none; display: inline-block;
|
||
-webkit-touch-callout: none; -webkit-user-select: none;
|
||
-khtml-user-select: none; -moz-user-select: none;
|
||
-ms-user-select: none; user-select: none;
|
||
padding: 0 4px; width: 4em;
|
||
color: #aaaaaa;
|
||
}
|
||
pre.numberSource { margin-left: 3em; border-left: 1px solid #aaaaaa; padding-left: 4px; }
|
||
div.sourceCode
|
||
{ }
|
||
@media screen {
|
||
pre > code.sourceCode > span > a:first-child::before { text-decoration: underline; }
|
||
}
|
||
code span.al { color: #ff0000; font-weight: bold; } /* Alert */
|
||
code span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
|
||
code span.at { color: #7d9029; } /* Attribute */
|
||
code span.bn { color: #40a070; } /* BaseN */
|
||
code span.bu { color: #008000; } /* BuiltIn */
|
||
code span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
|
||
code span.ch { color: #4070a0; } /* Char */
|
||
code span.cn { color: #880000; } /* Constant */
|
||
code span.co { color: #60a0b0; font-style: italic; } /* Comment */
|
||
code span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
|
||
code span.do { color: #ba2121; font-style: italic; } /* Documentation */
|
||
code span.dt { color: #902000; } /* DataType */
|
||
code span.dv { color: #40a070; } /* DecVal */
|
||
code span.er { color: #ff0000; font-weight: bold; } /* Error */
|
||
code span.ex { } /* Extension */
|
||
code span.fl { color: #40a070; } /* Float */
|
||
code span.fu { color: #06287e; } /* Function */
|
||
code span.im { color: #008000; font-weight: bold; } /* Import */
|
||
code span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
|
||
code span.kw { color: #007020; font-weight: bold; } /* Keyword */
|
||
code span.op { color: #666666; } /* Operator */
|
||
code span.ot { color: #007020; } /* Other */
|
||
code span.pp { color: #bc7a00; } /* Preprocessor */
|
||
code span.sc { color: #4070a0; } /* SpecialChar */
|
||
code span.ss { color: #bb6688; } /* SpecialString */
|
||
code span.st { color: #4070a0; } /* String */
|
||
code span.va { color: #19177c; } /* Variable */
|
||
code span.vs { color: #4070a0; } /* VerbatimString */
|
||
code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
|
||
</style>
|
||
</head>
|
||
<body>
|
||
<header id="title-block-header">
|
||
<h1 class="title">GHOSTTY(1) Version 1.3.1 | 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. Recognized as either <code>+version</code> or
|
||
<code>--version</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--help</code></strong></dt>
|
||
<dd>
|
||
<p>The <code>help</code> command shows general help about Ghostty.
|
||
Recognized as either
|
||
<code>-h,</code>–help<code>, or like other actions</code>+help`.</p>
|
||
<p>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>Flags:</p>
|
||
<ul>
|
||
<li><p><code>--bold</code>: Filter results to specific bold styles. It
|
||
is not guaranteed that only those styles are returned. They are only
|
||
prioritized.</p></li>
|
||
<li><p><code>--italic</code>: Filter results to specific italic styles.
|
||
It is not guaranteed that only those styles are returned. They are only
|
||
prioritized.</p></li>
|
||
<li><p><code>--style</code>: Filter results based on the style string
|
||
advertised by a font. It is not guaranteed that only those styles are
|
||
returned. They are only prioritized.</p></li>
|
||
<li><p><code>--family</code>: Filter results to a specific font 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></li>
|
||
</ul>
|
||
</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>Flags:</p>
|
||
<ul>
|
||
<li><p><code>--default</code>: will print out all the default
|
||
keybinds</p></li>
|
||
<li><p><code>--docs</code>: currently does nothing, intended to print
|
||
out documentation about the action associated with the keybinds</p></li>
|
||
<li><p><code>--plain</code>: will disable formatting and make the output
|
||
more friendly for Unix tooling. This is default when not printing to a
|
||
tty.</p></li>
|
||
</ul>
|
||
</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_HOME/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><p><code>--path</code>: Show the full path to the theme.</p></li>
|
||
<li><p><code>--plain</code>: Force a plain listing of themes.</p></li>
|
||
<li><p><code>--color</code>: Specify the color scheme of the themes
|
||
included in the list. This can be <code>dark</code>, <code>light</code>,
|
||
or <code>all</code>. The default is <code>all</code>.</p></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>
|
||
<p>Flags:</p>
|
||
<ul>
|
||
<li><code>--plain</code>: will disable formatting and make the output
|
||
more friendly for Unix tooling. This is default when not printing to a
|
||
tty.</li>
|
||
</ul>
|
||
</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. These are distinct from the CLI
|
||
Actions which can be listed via <code>+help</code></p>
|
||
<p>Flags:</p>
|
||
<ul>
|
||
<li><code>--docs</code>: will print out the documentation for each
|
||
action.</li>
|
||
</ul>
|
||
</dd>
|
||
<dt><strong><code>+ssh-cache</code></strong></dt>
|
||
<dd>
|
||
<p>Manage the SSH terminfo cache for automatic remote host setup.</p>
|
||
<p>When SSH integration is enabled with
|
||
<code>shell-integration-features = ssh-terminfo</code>, Ghostty
|
||
automatically installs its terminfo on remote hosts. This command
|
||
manages the cache of successful installations to avoid redundant
|
||
uploads.</p>
|
||
<p>The cache stores hostnames (or user@hostname combinations) along with
|
||
timestamps. Entries older than the expiration period are automatically
|
||
removed during cache operations. By default, entries never expire.</p>
|
||
<p>Only one of <code>--clear</code>, <code>--add</code>,
|
||
<code>--remove</code>, or <code>--host</code> can be specified. If
|
||
multiple are specified, one of the actions will be executed but it isn’t
|
||
guaranteed which one. This is entirely unsafe so you should split
|
||
multiple actions into separate commands.</p>
|
||
<p>Examples: ghostty +ssh-cache # List all cached hosts ghostty
|
||
+ssh-cache –host=example.com # Check if host is cached ghostty
|
||
+ssh-cache –add=example.com # Manually add host to cache ghostty
|
||
+ssh-cache –add=user@example.com # Add user@host combination ghostty
|
||
+ssh-cache –remove=example.com # Remove host from cache ghostty
|
||
+ssh-cache –clear # Clear entire cache ghostty +ssh-cache
|
||
–expire-days=30 # Set custom expiration period</p>
|
||
</dd>
|
||
<dt><strong><code>+edit-config</code></strong></dt>
|
||
<dd>
|
||
<p>The <code>edit-config</code> command opens the Ghostty configuration
|
||
file in the editor specified by the <code>$VISUAL</code> or
|
||
<code>$EDITOR</code> environment variables.</p>
|
||
<p>IMPORTANT: This command will not reload the configuration after
|
||
editing. You will need to manually reload the configuration using the
|
||
application menu, configured keybind, or by restarting Ghostty. We plan
|
||
to auto-reload in the future, but Ghostty isn’t capable of this yet.</p>
|
||
<p>The filepath opened is the default user-specific configuration file,
|
||
which is typically located at
|
||
<code>$XDG_CONFIG_HOME/ghostty/config.ghostty</code>. On macOS, this may
|
||
also be located at
|
||
<code>~/Library/Application Support/com.mitchellh.ghostty/config.ghostty</code>.
|
||
On macOS, whichever path exists and is non-empty will be prioritized,
|
||
prioritizing the Application Support directory if neither are
|
||
non-empty.</p>
|
||
<p>This command prefers the <code>$VISUAL</code> environment variable
|
||
over <code>$EDITOR</code>, if both are set. If neither are set, it will
|
||
print an error and exit.</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>Flags:</p>
|
||
<ul>
|
||
<li><code>--config-file</code>: can be passed to validate a specific
|
||
target config file in a non-default location</li>
|
||
</ul>
|
||
</dd>
|
||
<dt><strong><code>+show-face</code></strong></dt>
|
||
<dd>
|
||
<p>The <code>show-face</code> command shows what font face Ghostty will
|
||
use to render a specific codepoint. Note that this command does not take
|
||
into consideration grapheme clustering or any other Unicode features
|
||
that might modify the presentation of a codepoint, so this may show a
|
||
different font face than Ghostty uses to render a codepoint in a
|
||
terminal session.</p>
|
||
<p>Flags:</p>
|
||
<ul>
|
||
<li><p><code>--cp</code>: Find the face for a single codepoint. The
|
||
codepoint may be specified in decimal (<code>--cp=65</code>),
|
||
hexadecimal (<code>--cp=0x41</code>), octal (<code>--cp=0o101</code>),
|
||
or binary (<code>--cp=0b1000001</code>).</p></li>
|
||
<li><p><code>--string</code>: Find the face for all of the codepoints in
|
||
a string. The string must be a valid UTF-8 sequence.</p></li>
|
||
<li><p><code>--style</code>: Search for a specific style. Valid options
|
||
are <code>regular</code>, <code>bold</code>, <code>italic</code>, and
|
||
<code>bold_italic</code>.</p></li>
|
||
<li><p><code>--presentation</code>: If set, force searching for a
|
||
specific presentation style. Valid options are <code>text</code> and
|
||
<code>emoji</code>. If unset, the presentation style of a codepoint will
|
||
be inferred from the Unicode standard.</p></li>
|
||
</ul>
|
||
</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>
|
||
<dt><strong><code>+boo</code></strong></dt>
|
||
<dd>
|
||
<p>The <code>boo</code> command is used to display the animation from
|
||
the Ghostty website in the terminal</p>
|
||
</dd>
|
||
<dt><strong><code>+new-window</code></strong></dt>
|
||
<dd>
|
||
<p>The <code>new-window</code> will use native platform IPC to open up a
|
||
new window in a running instance of Ghostty.</p>
|
||
<p>If the <code>--class</code> flag is not set, the
|
||
<code>new-window</code> command will try and connect to a running
|
||
instance of Ghostty based on what optimizations the Ghostty CLI was
|
||
compiled with. Otherwise the <code>new-window</code> command will try
|
||
and contact a running Ghostty instance that was configured with the same
|
||
<code>class</code> as was given on the command line.</p>
|
||
<p>All of the arguments after the <code>+new-window</code> argument
|
||
(except for the <code>--class</code> flag) will be sent to the remote
|
||
Ghostty instance and will be parsed as command line flags. These flags
|
||
will override certain settings when creating the first surface in the
|
||
new window. Currently, only <code>--working-directory</code>,
|
||
<code>--command</code>, and <code>--title</code> are supported.
|
||
<code>-e</code> will also work as an alias for <code>--command</code>,
|
||
except that if <code>-e</code> is found on the command line all
|
||
following arguments will become part of the command and no more
|
||
arguments will be parsed for configuration settings.</p>
|
||
<p>If <code>--working-directory</code> is found on the command line and
|
||
is a relative path (i.e. doesn’t start with <code>/</code>) it will be
|
||
resolved to an absolute path relative to the current working directory
|
||
that the <code>ghostty +new-window</code> command is run from.
|
||
<code>~/</code> prefixes will also be expanded to the user’s home
|
||
directory.</p>
|
||
<p>If <code>--working-directory</code> is <em>not</em> found on the
|
||
command line, the working directory that
|
||
<code>ghostty +new-window</code> is run from will be passed to
|
||
Ghostty.</p>
|
||
<p>GTK uses an application ID to identify instances of applications. If
|
||
Ghostty is compiled with release optimizations, the default application
|
||
ID will be <code>com.mitchellh.ghostty</code>. If Ghostty is compiled
|
||
with debug optimizations, the default application ID will be
|
||
<code>com.mitchellh.ghostty-debug</code>. The <code>class</code>
|
||
configuration entry can be used to set up a custom application ID. 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> or it will be ignored and Ghostty will use the
|
||
default as defined above.</p>
|
||
<p>On GTK, D-Bus activation must be properly configured. Ghostty does
|
||
not need to be running for this to open a new window, making it suitable
|
||
for binding to keys in your window manager (if other methods for
|
||
configuring global shortcuts are unavailable). D-Bus will handle
|
||
launching a new instance of Ghostty if it is not already running. See
|
||
the Ghostty website for information on properly configuring D-Bus
|
||
activation.</p>
|
||
<p>Only supported on GTK.</p>
|
||
<p>Flags:</p>
|
||
<ul>
|
||
<li><p><code>--class=<class></code>: If set, open up a new window
|
||
in a custom instance of Ghostty. The class must be a valid GTK
|
||
application ID.</p></li>
|
||
<li><p><code>--command</code>: The command to be executed in the first
|
||
surface of the new window.</p></li>
|
||
<li><p><code>--working-directory=<directory></code>: The working
|
||
directory to pass to Ghostty.</p></li>
|
||
<li><p><code>--title</code>: A title that will override the title of the
|
||
first surface in the new window. The title override may be edited or
|
||
removed later.</p></li>
|
||
<li><p><code>-e</code>: Any arguments after this will be interpreted as
|
||
a command to execute inside the first surface of the new window instead
|
||
of the default command.</p></li>
|
||
</ul>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
</dl>
|
||
<h1 id="configuration-options">CONFIGURATION OPTIONS</h1>
|
||
<dl>
|
||
<dt><strong><code>--language</code></strong></dt>
|
||
<dd>
|
||
<p>Set Ghostty’s graphical user interface language to a language other
|
||
than the system default language. For example:</p>
|
||
<pre><code>language = de</code></pre>
|
||
<p>will force the strings in Ghostty’s graphical user interface to be in
|
||
German rather than the system default.</p>
|
||
<p>This will not affect the language used by programs run
|
||
<em>within</em> Ghostty. Those will continue to use the default system
|
||
language. There are also many non-GUI elements in Ghostty that are not
|
||
translated - this setting will have no effect on those.</p>
|
||
<p>Warning: This setting cannot be reloaded at runtime. To change the
|
||
language you must fully restart Ghostty.</p>
|
||
<p>GTK only. Available since 1.3.0.</p>
|
||
</dd>
|
||
<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>
|
||
</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. To enable multiple font features you can repeat
|
||
this multiple times or use a comma-separated list of feature
|
||
settings.</p>
|
||
<p>The syntax for feature settings is as follows, where
|
||
<code>feat</code> is a feature:</p>
|
||
<ul>
|
||
<li>Enable features with e.g. <code>feat</code>, <code>+feat</code>,
|
||
<code>feat on</code>, <code>feat=1</code>.</li>
|
||
<li>Disabled features with e.g. <code>-feat</code>,
|
||
<code>feat off</code>, <code>feat=0</code>.</li>
|
||
<li>Set a feature value with e.g. <code>feat=2</code>,
|
||
<code>feat = 3</code>, <code>feat 4</code>.</li>
|
||
<li>Feature names may be wrapped in quotes, meaning this config should
|
||
be syntactically compatible with the <code>font-feature-settings</code>
|
||
CSS property.</li>
|
||
</ul>
|
||
<p>The syntax is fairly loose, but invalid settings will be silently
|
||
ignored.</p>
|
||
<p>The font feature will apply to all fonts rendered by Ghostty. A
|
||
future enhancement will allow targeting specific faces.</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, -liga, -dlig</code>.</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 existing
|
||
terminals that have NOT manually adjusted their font size in some way
|
||
(e.g. increased or decreased the font size). Terminals that have
|
||
manually adjusted their font size will retain their manually adjusted
|
||
size. Otherwise, the font size of existing terminals will be updated on
|
||
reload.</p>
|
||
<p>On Linux with GTK, font size is scaled according to both display-wide
|
||
and text-specific scaling factors, which are often managed by your
|
||
desktop environment (e.g. the GNOME display scale and large text
|
||
settings).</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>--clipboard-codepoint-map</code></strong></dt>
|
||
<dd>
|
||
<p>Map specific Unicode codepoints to replacement values when copying
|
||
text to clipboard.</p>
|
||
<p>This configuration allows you to replace specific Unicode characters
|
||
with other characters or strings when copying terminal content to the
|
||
clipboard. This is useful for converting special terminal symbols to
|
||
more compatible characters for pasting into other applications.</p>
|
||
<p>The syntax is similar to <code>font-codepoint-map</code>: - Single
|
||
codepoint: <code>U+1234=U+ABCD</code> or
|
||
<code>U+1234=replacement_text</code> - Codepoint range:
|
||
<code>U+1234-U+5678=U+ABCD</code></p>
|
||
<p>Examples: - <code>clipboard-codepoint-map = U+2500=U+002D</code> (box
|
||
drawing horizontal → hyphen) -
|
||
<code>clipboard-codepoint-map = U+2502=U+007C</code> (box drawing
|
||
vertical → pipe) - <code>clipboard-codepoint-map = U+03A3=SUM</code>
|
||
(Greek sigma → “SUM”)</p>
|
||
<p>This configuration can be repeated multiple times to specify multiple
|
||
mappings. Later entries take priority over earlier ones for overlapping
|
||
ranges.</p>
|
||
<p>Note: This only applies to text copying operations, not URL
|
||
copying.</p>
|
||
</dd>
|
||
<dt><strong><code>--font-thicken</code></strong></dt>
|
||
<dd>
|
||
<p>Draw fonts with a thicker stroke, if supported. This is currently
|
||
only supported on macOS.</p>
|
||
</dd>
|
||
<dt><strong><code>--font-thicken-strength</code></strong></dt>
|
||
<dd>
|
||
<p>Strength of thickening when <code>font-thicken</code> is enabled.</p>
|
||
<p>Valid values are integers between <code>0</code> and
|
||
<code>255</code>. <code>0</code> does not correspond to <em>no</em>
|
||
thickening, rather it corresponds to the lightest available
|
||
thickening.</p>
|
||
<p>Has no effect when <code>font-thicken</code> is set to
|
||
<code>false</code>.</p>
|
||
<p>This is currently only supported on macOS.</p>
|
||
</dd>
|
||
<dt><strong><code>--font-shaping-break</code></strong></dt>
|
||
<dd>
|
||
<p>Locations to break font shaping into multiple runs.</p>
|
||
<p>A “run” is a contiguous segment of text that is shaped together.
|
||
“Shaping” is the process of converting text (codepoints) into glyphs
|
||
(renderable characters). This is how ligatures are formed, among other
|
||
things. For example, if a coding font turns “!=” into a single glyph,
|
||
then it must see “!” and “=” next to each other in a single run. When a
|
||
run is broken, the text is shaped separately. To continue our example,
|
||
if “!” is at the end of one run and “=” is at the start of the next run,
|
||
then the ligature will not be formed.</p>
|
||
<p>Ghostty breaks runs at certain points to improve readability or
|
||
usability. For example, Ghostty by default will break runs under the
|
||
cursor so that text editing can see the individual characters rather
|
||
than a ligature. This configuration lets you configure this
|
||
behavior.</p>
|
||
<p>Combine values with a comma to set multiple options. Prefix an option
|
||
with “no-” to disable it. Enabling and disabling options can be done at
|
||
the same time.</p>
|
||
<p>Available options:</p>
|
||
<ul>
|
||
<li><code>cursor</code> - Break runs under the cursor.</li>
|
||
</ul>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--alpha-blending</code></strong></dt>
|
||
<dd>
|
||
<p>What color space to use when performing alpha blending.</p>
|
||
<p>This affects the appearance of text and of any images with
|
||
transparency. Additionally, custom shaders will receive colors in the
|
||
configured space.</p>
|
||
<p>On macOS the default is <code>native</code>, on all other platforms
|
||
the default is <code>linear-corrected</code>.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li><p><code>native</code> - Perform alpha blending in the native color
|
||
space for the OS. On macOS this corresponds to Display P3, and on Linux
|
||
it’s sRGB.</p></li>
|
||
<li><p><code>linear</code> - Perform alpha blending in linear space.
|
||
This will eliminate the darkening artifacts around the edges of text
|
||
that are very visible when certain color combinations are used (e.g. red
|
||
/ green), but makes dark text look much thinner than normal and light
|
||
text much thicker. This is also sometimes known as “gamma
|
||
correction”.</p></li>
|
||
<li><p><code>linear-corrected</code> - Same as <code>linear</code>, but
|
||
with a correction step applied for text that makes it look nearly or
|
||
completely identical to <code>native</code>, but without any of the
|
||
darkening artifacts.</p></li>
|
||
</ul>
|
||
<p>Available since: 1.1.0</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
|
||
(e.g. <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, many
|
||
<code>*-thickness</code> adjustments cannot go below 1px.</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, but may be
|
||
adjusted separately with <code>adjust-cursor-height</code>.</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 or percentage adjustment from the bottom of the
|
||
cell to the text baseline. Increase to move baseline UP, decrease to
|
||
move baseline DOWN. See the notes about adjustments in
|
||
<code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-underline-position</code></strong></dt>
|
||
<dd>
|
||
<p>Distance in pixels or percentage adjustment from the top of the cell
|
||
to the top of the underline. Increase to move underline DOWN, decrease
|
||
to move underline UP. See the notes about adjustments in
|
||
<code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-underline-thickness</code></strong></dt>
|
||
<dd>
|
||
<p>Thickness in pixels of the underline. See the notes about adjustments
|
||
in <code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-strikethrough-position</code></strong></dt>
|
||
<dd>
|
||
<p>Distance in pixels or percentage adjustment from the top of the cell
|
||
to the top of the strikethrough. Increase to move strikethrough DOWN,
|
||
decrease to move strikethrough UP. See the notes about adjustments in
|
||
<code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-strikethrough-thickness</code></strong></dt>
|
||
<dd>
|
||
<p>Thickness in pixels or percentage adjustment of the strikethrough.
|
||
See the notes about adjustments in <code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-overline-position</code></strong></dt>
|
||
<dd>
|
||
<p>Distance in pixels or percentage adjustment from the top of the cell
|
||
to the top of the overline. Increase to move overline DOWN, decrease to
|
||
move overline UP. See the notes about adjustments in
|
||
<code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-overline-thickness</code></strong></dt>
|
||
<dd>
|
||
<p>Thickness in pixels or percentage adjustment of the overline. See the
|
||
notes about adjustments in <code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-cursor-thickness</code></strong></dt>
|
||
<dd>
|
||
<p>Thickness in pixels or percentage adjustment of the bar cursor and
|
||
outlined rect cursor. See the notes about adjustments in
|
||
<code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-cursor-height</code></strong></dt>
|
||
<dd>
|
||
<p>Height in pixels or percentage adjustment of the cursor. Currently
|
||
applies to all cursor types: bar, rect, and outlined rect. See the notes
|
||
about adjustments in <code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-box-thickness</code></strong></dt>
|
||
<dd>
|
||
<p>Thickness in pixels or percentage adjustment of box drawing
|
||
characters. See the notes about adjustments in
|
||
<code>adjust-cell-width</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--adjust-icon-height</code></strong></dt>
|
||
<dd>
|
||
<p>Height in pixels or percentage adjustment of maximum height for nerd
|
||
font icons.</p>
|
||
<p>A positive (negative) value will increase (decrease) the maximum icon
|
||
height. This may not affect all icons equally: the effect depends on
|
||
whether the default size of the icon is height-constrained, which in
|
||
turn depends on the aspect ratio of both the icon and your primary
|
||
font.</p>
|
||
<p>Certain icons designed for box drawing and terminal graphics, such as
|
||
Powerline symbols, are not affected by this option.</p>
|
||
<p>See the notes about adjustments in
|
||
<code>adjust-cell-width</code>.</p>
|
||
<p>Available in: 1.2.0</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, its 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><p><code>hinting</code> - Enable or disable hinting. Enabled by
|
||
default.</p></li>
|
||
<li><p><code>force-autohint</code> - Always use the freetype auto-hinter
|
||
instead of the font’s native hinter. Disabled by default.</p></li>
|
||
<li><p><code>monochrome</code> - Instructs renderer to use 1-bit
|
||
monochrome rendering. This will disable anti-aliasing, and probably not
|
||
look very good unless you’re using a pixel font. Disabled by
|
||
default.</p></li>
|
||
<li><p><code>autohint</code> - Enable the freetype auto-hinter. Enabled
|
||
by default.</p></li>
|
||
<li><p><code>light</code> - Use a light hinting style, better preserving
|
||
glyph shapes. This is the most common setting in GTK apps and therefore
|
||
also Ghostty’s default. This has no effect if <code>monochrome</code> is
|
||
enabled. Enabled by default.</p></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_HOME/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. Specified as either hex
|
||
(<code>#RRGGBB</code> or <code>RRGGBB</code>) or a named X11 color.</p>
|
||
</dd>
|
||
<dt><strong><code>--foreground</code></strong></dt>
|
||
<dd>
|
||
<p>Foreground color for the window. Specified as either hex
|
||
(<code>#RRGGBB</code> or <code>RRGGBB</code>) or a named X11 color.</p>
|
||
</dd>
|
||
<dt><strong><code>--background-image</code></strong></dt>
|
||
<dd>
|
||
<p>Background image for the terminal.</p>
|
||
<p>This should be a path to a PNG or JPEG file, other image formats are
|
||
not yet supported.</p>
|
||
<p>The background image is currently per-terminal, not per-window. If
|
||
you are a heavy split user, the background image will be repeated across
|
||
splits. A future improvement to Ghostty will address this.</p>
|
||
<p>WARNING: Background images are currently duplicated in VRAM
|
||
per-terminal. For sufficiently large images, this could lead to a large
|
||
increase in memory usage (specifically VRAM usage). A future Ghostty
|
||
improvement will resolve this by sharing image textures across
|
||
terminals.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--background-image-opacity</code></strong></dt>
|
||
<dd>
|
||
<p>Background image opacity.</p>
|
||
<p>This is relative to the value of <code>background-opacity</code>.</p>
|
||
<p>A value of <code>1.0</code> (the default) will result in the
|
||
background image being placed on top of the general background color,
|
||
and then the combined result will be adjusted to the opacity specified
|
||
by <code>background-opacity</code>.</p>
|
||
<p>A value less than <code>1.0</code> will result in the background
|
||
image being mixed with the general background color before the combined
|
||
result is adjusted to the configured
|
||
<code>background-opacity</code>.</p>
|
||
<p>A value greater than <code>1.0</code> will result in the background
|
||
image having a higher opacity than the general background color. For
|
||
instance, if the configured <code>background-opacity</code> is
|
||
<code>0.5</code> and <code>background-image-opacity</code> is set to
|
||
<code>1.5</code>, then the final opacity of the background image will be
|
||
<code>0.5 * 1.5 = 0.75</code>.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--background-image-position</code></strong></dt>
|
||
<dd>
|
||
<p>Background image position.</p>
|
||
<p>Valid values are: * <code>top-left</code> * <code>top-center</code> *
|
||
<code>top-right</code> * <code>center-left</code> * <code>center</code>
|
||
* <code>center-right</code> * <code>bottom-left</code> *
|
||
<code>bottom-center</code> * <code>bottom-right</code></p>
|
||
<p>The default value is <code>center</code>.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--background-image-fit</code></strong></dt>
|
||
<dd>
|
||
<p>Background image fit.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><p><code>contain</code></p>
|
||
<p>Preserving the aspect ratio, scale the background image to the
|
||
largest size that can still be contained within the terminal, so that
|
||
the whole image is visible.</p></li>
|
||
<li><p><code>cover</code></p>
|
||
<p>Preserving the aspect ratio, scale the background image to the
|
||
smallest size that can completely cover the terminal. This may result in
|
||
one or more edges of the image being clipped by the edge of the
|
||
terminal.</p></li>
|
||
<li><p><code>stretch</code></p>
|
||
<p>Stretch the background image to the full size of the terminal,
|
||
without preserving the aspect ratio.</p></li>
|
||
<li><p><code>none</code></p>
|
||
<p>Don’t scale the background image.</p></li>
|
||
</ul>
|
||
<p>The default value is <code>contain</code>.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--background-image-repeat</code></strong></dt>
|
||
<dd>
|
||
<p>Whether to repeat the background image or not.</p>
|
||
<p>If this is set to true, the background image will be repeated if
|
||
there would otherwise be blank space around it because it doesn’t
|
||
completely fill the terminal area.</p>
|
||
<p>The default value is <code>false</code>.</p>
|
||
<p>Available since: 1.2.0</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). Specified as
|
||
either hex (<code>#RRGGBB</code> or <code>RRGGBB</code>) or a named X11
|
||
color. Since version 1.2.0, this can also be set to
|
||
<code>cell-foreground</code> to match the cell foreground color, or
|
||
<code>cell-background</code> to match the cell background color.</p>
|
||
</dd>
|
||
</dl>
|
||
<p><strong><code>--selection-background</code></strong></p>
|
||
<dl>
|
||
<dt><strong><code>--selection-clear-on-typing</code></strong></dt>
|
||
<dd>
|
||
<p>Whether to clear selected text when typing. This defaults to
|
||
<code>true</code>. This is typical behavior for most terminal emulators
|
||
as well as text input fields. If you set this to <code>false</code>,
|
||
then the selected text will not be cleared when typing.</p>
|
||
<p>“Typing” is specifically defined as any non-modifier (shift, control,
|
||
alt, etc.) keypress that produces data to be sent to the application
|
||
running within the terminal (e.g. the shell). Additionally, selection is
|
||
cleared when any preedit or composition state is started (e.g. when
|
||
typing languages such as Japanese).</p>
|
||
<p>If this is <code>false</code>, then the selection can still be
|
||
manually cleared by clicking once or by pressing
|
||
<code>escape</code>.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--selection-clear-on-copy</code></strong></dt>
|
||
<dd>
|
||
<p>Whether to clear selected text after copying. This defaults to
|
||
<code>false</code>.</p>
|
||
<p>When set to <code>true</code>, the selection will be automatically
|
||
cleared after any copy operation that invokes the
|
||
<code>copy_to_clipboard</code> keyboard binding. Importantly, this will
|
||
not clear the selection if the copy operation was invoked via
|
||
<code>copy-on-select</code>.</p>
|
||
<p>When set to <code>false</code>, the selection remains visible after
|
||
copying, allowing to see what was copied and potentially perform
|
||
additional operations on the same selection.</p>
|
||
</dd>
|
||
<dt><strong><code>--selection-word-chars</code></strong></dt>
|
||
<dd>
|
||
<p>Characters that mark word boundaries during text selection operations
|
||
such as double-clicking. When selecting a word, the selection will stop
|
||
at any of these characters.</p>
|
||
<p>This is similar to the <code>WORDCHARS</code> environment variable in
|
||
zsh, except this specifies the boundary characters rather than the word
|
||
characters. The default includes common delimiters and punctuation that
|
||
typically separate words in code and prose.</p>
|
||
<p>Each character in this string becomes a word boundary. Multi-byte
|
||
UTF-8 characters are supported, but only single codepoints can be
|
||
specified. Multi-codepoint sequences (e.g. emoji) are not supported.</p>
|
||
<p>The null character (U+0000) is always treated as a boundary and does
|
||
not need to be included in this configuration.</p>
|
||
<p>Default: <code>\t'"│`|:;,()[]{}<>$</code></p>
|
||
<p>To add or remove specific characters, you can set this to a custom
|
||
value. For example, to treat semicolons as part of words:</p>
|
||
<pre><code>selection-word-chars = " \t'\"│`|:,()[]{}<>$"</code></pre>
|
||
<p>Available since: 1.3.0</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 (e.g. 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=COLOR</code> where
|
||
<code>N</code> is 0 to 255 (for the 256 colors in the terminal color
|
||
table) and <code>COLOR</code> is a typical RGB color code such as
|
||
<code>#AABBCC</code> or <code>AABBCC</code>, or a named X11 color. For
|
||
example, <code>palette = 5=#BB78D9</code> will set the ‘purple’
|
||
color.</p>
|
||
<p>The palette index can be in decimal, binary, octal, or hexadecimal.
|
||
Decimal is assumed unless a prefix is used: <code>0b</code> for binary,
|
||
<code>0o</code> for octal, and <code>0x</code> for hexadecimal.</p>
|
||
<p>For definitions on the color indices and what they canonically map
|
||
to, <a href="https://www.ditig.com/256-colors-cheat-sheet">see this
|
||
cheat sheet</a>.</p>
|
||
<p>For most themes, you only need to set the first 16 colors (0–15)
|
||
since the rest of the palette (16–255) will be automatically generated
|
||
by default (see <code>palette-generate</code> for more details).</p>
|
||
</dd>
|
||
<dt><strong><code>--palette-generate</code></strong></dt>
|
||
<dd>
|
||
<p>Whether to automatically generate the extended 256 color palette
|
||
(indices 16–255) from the base 16 ANSI colors.</p>
|
||
<p>This lets theme authors specify only the base 16 colors and have the
|
||
rest of the palette be automatically generated in a consistent and
|
||
aesthetic way.</p>
|
||
<p>When enabled, the 6×6×6 color cube and 24-step grayscale ramp are
|
||
derived from interpolations of the base palette, giving a more cohesive
|
||
look. Colors that have been explicitly set via <code>palette</code> are
|
||
never overwritten.</p>
|
||
<p>The default value is false (disabled), because many legacy programs
|
||
using the 256-color palette hardcode assumptions about what these colors
|
||
are (mostly assuming the xterm 256 color palette). However, this is
|
||
still a very useful tool for theme authors and users who want to
|
||
customize their palette without having to specify all 256 colors.</p>
|
||
<p>For more information on how the generation works, see here:
|
||
https://gist.github.com/jake-stewart/0a8ea46159a7da2c808e5be2177e1783</p>
|
||
<p>Available since: 1.3.0</p>
|
||
</dd>
|
||
<dt><strong><code>--palette-harmonious</code></strong></dt>
|
||
<dd>
|
||
<p>Invert the palette colors generated when
|
||
<code>palette-generate</code> is enabled, so that the colors go in
|
||
reverse order. This allows palette-based applications to work well in
|
||
both light and dark mode since the palettes are always relatively good
|
||
colors.</p>
|
||
<p>This defaults to off because some legacy terminal applications
|
||
hardcode the assumption that palette indices 16–231 are ordered from
|
||
darkest to lightest, so enabling this would make them unreadable. This
|
||
is not a generally good assumption and we encourage modern terminal
|
||
applications to use the indices in a more semantic way.</p>
|
||
<p>This has no effect if <code>palette-generate</code> is disabled.</p>
|
||
<p>For more information see <code>palette-generate</code>.</p>
|
||
<p>Available since: 1.3.0</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>
|
||
<p>Direct colors can be specified as either hex (<code>#RRGGBB</code> or
|
||
<code>RRGGBB</code>) or a named X11 color.</p>
|
||
<p>Additionally, special values can be used to set the color to match
|
||
other colors at runtime:</p>
|
||
<ul>
|
||
<li><p><code>cell-foreground</code> - Match the cell foreground color.
|
||
(Available since: 1.2.0)</p></li>
|
||
<li><p><code>cell-background</code> - Match the cell background color.
|
||
(Available since: 1.2.0)</p></li>
|
||
</ul>
|
||
</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><code></code> (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. Specified as either hex (<code>#RRGGBB</code> or
|
||
<code>RRGGBB</code>) or a named X11 color. Since version 1.2.0, this can
|
||
also be set to <code>cell-foreground</code> to match the cell foreground
|
||
color, or <code>cell-background</code> to match the cell background
|
||
color.</p>
|
||
</dd>
|
||
<dt><strong><code>--cursor-click-to-move</code></strong></dt>
|
||
<dd>
|
||
<p>Enables the ability to move the cursor at prompts by clicking on a
|
||
location in the prompt text.</p>
|
||
<p>This feature requires shell integration, specifically prompt marking
|
||
via <code>OSC 133</code>. Some shells like Fish (v4) and Nu (0.111+)
|
||
natively support this while others may require additional configuration
|
||
or Ghostty’s shell integration features to be enabled.</p>
|
||
<p>Depending on the shell, this works either by translating your click
|
||
position into a series of synthetic arrow key movements or by sending a
|
||
click event directly to the shell. In either case, some unexpected
|
||
behavior around edge cases is possible.</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>--scroll-to-bottom</code></strong></dt>
|
||
<dd>
|
||
<p>When to scroll the surface to the bottom. The format of this is a
|
||
list of options to enable separated by commas. If you prefix an option
|
||
with <code>no-</code> then it is disabled. If you omit an option, its
|
||
default value is used.</p>
|
||
<p>Available options:</p>
|
||
<ul>
|
||
<li><p><code>keystroke</code> If set, scroll the surface to the bottom
|
||
when the user presses a key that results in data being sent to the PTY
|
||
(basically anything but modifiers or keybinds that are processed by
|
||
Ghostty).</p></li>
|
||
<li><p><code>output</code> If set, scroll the surface to the bottom if
|
||
there is new data to display (e.g., when new lines are printed to the
|
||
terminal).</p></li>
|
||
</ul>
|
||
<p>The default is <code>keystroke, no-output</code>.</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-reporting</code></strong></dt>
|
||
<dd>
|
||
<p>Enable or disable mouse reporting. When set to <code>false</code>,
|
||
mouse events will not be reported to terminal applications even if they
|
||
request it. This allows you to always use the mouse for selection and
|
||
other terminal UI interactions without applications capturing mouse
|
||
input.</p>
|
||
<p>When set to <code>true</code> (the default), terminal applications
|
||
can request mouse reporting and will receive mouse events according to
|
||
their requested mode.</p>
|
||
<p>This can be toggled at runtime using the
|
||
<code>toggle_mouse_reporting</code> keybind action.</p>
|
||
</dd>
|
||
<dt><strong><code>--mouse-scroll-multiplier</code></strong></dt>
|
||
<dd>
|
||
<p>Multiplier for scrolling distance with the mouse wheel.</p>
|
||
<p>A prefix of <code>precision:</code> or <code>discrete:</code> can be
|
||
used to set the multiplier only for scrolling with the specific type of
|
||
devices. These can be comma-separated to set both types of multipliers
|
||
at the same time, e.g. <code>precision:0.1,discrete:3</code>. If no
|
||
prefix is used, the multiplier applies to all scrolling devices.
|
||
Specifying a prefix was introduced in Ghostty 1.2.1.</p>
|
||
<p>The value will be clamped to [0.01, 10,000]. Both of these are
|
||
extreme and you’re likely to have a bad experience if you set either
|
||
extreme.</p>
|
||
<p>The default value is “3” for discrete devices and “1” for precision
|
||
devices.</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>
|
||
<p>On macOS, changing this configuration requires restarting Ghostty
|
||
completely.</p>
|
||
</dd>
|
||
<dt><strong><code>--background-opacity-cells</code></strong></dt>
|
||
<dd>
|
||
<p>Applies background opacity to cells with an explicit background color
|
||
set.</p>
|
||
<p>Normally, <code>background-opacity</code> is only applied to the
|
||
window background. If a cell has an explicit background color set, such
|
||
as red, then that background color will be fully opaque. An effect of
|
||
this is that some terminal applications that repaint the background
|
||
color of the terminal such as a Neovim and Tmux may not respect the
|
||
<code>background-opacity</code> (by design).</p>
|
||
<p>Setting this to <code>true</code> will apply the
|
||
<code>background-opacity</code> to all cells regardless of whether they
|
||
have an explicit background color set or not.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--background-blur</code></strong></dt>
|
||
<dd>
|
||
<p>Whether to blur the background when <code>background-opacity</code>
|
||
is less than 1.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li>a nonnegative integer specifying the <em>blur intensity</em></li>
|
||
<li><code>false</code>, equivalent to a blur intensity of 0</li>
|
||
<li><code>true</code>, equivalent to the default blur intensity of 20,
|
||
which is reasonable for a good looking blur. Higher blur intensities may
|
||
cause strange rendering and performance issues.</li>
|
||
</ul>
|
||
<p>On macOS 26.0 and later, there are additional special values that can
|
||
be set to use the native macOS glass effects:</p>
|
||
<ul>
|
||
<li><code>macos-glass-regular</code> - Standard glass effect with some
|
||
opacity</li>
|
||
<li><code>macos-glass-clear</code> - Highly transparent glass
|
||
effect</li>
|
||
</ul>
|
||
<p>If the macOS values are set, then this implies
|
||
<code>background-blur = true</code> on non-macOS platforms.</p>
|
||
<p>Supported on macOS and on some Linux desktop environments,
|
||
including:</p>
|
||
<ul>
|
||
<li>KDE Plasma (Wayland and X11)</li>
|
||
</ul>
|
||
<p>Warning: the exact blur intensity is <em>ignored</em> under KDE
|
||
Plasma, and setting this setting to either <code>true</code> or any
|
||
positive blur intensity value would achieve the same effect. The reason
|
||
is that KWin, the window compositor powering Plasma, only has one global
|
||
blur setting and does not allow applications to specify individual blur
|
||
settings.</p>
|
||
<p>To configure KWin’s global blur setting, open System Settings and go
|
||
to “Apps & Windows” > “Window Management” > “Desktop Effects”
|
||
and select the “Blur” plugin. If disabled, enable it by ticking the
|
||
checkbox to the left. Then click on the “Configure” button and there
|
||
will be two sliders that allow you to set background blur and noise
|
||
intensities for all apps, including Ghostty.</p>
|
||
<p>All other Linux desktop environments are as of now unsupported. Users
|
||
may need to set environment-specific settings and/or install third-party
|
||
plugins in order to support background blur, as there isn’t a unified
|
||
interface for doing so.</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>
|
||
<p>Specified as either hex (<code>#RRGGBB</code> or <code>RRGGBB</code>)
|
||
or a named X11 color.</p>
|
||
</dd>
|
||
<dt><strong><code>--split-divider-color</code></strong></dt>
|
||
<dd>
|
||
<p>The color of the split divider. If this is not set, a default will be
|
||
chosen. Specified as either hex (<code>#RRGGBB</code> or
|
||
<code>RRGGBB</code>) or a named X11 color.</p>
|
||
<p>Available since: 1.1.0</p>
|
||
</dd>
|
||
<dt><strong><code>--split-preserve-zoom</code></strong></dt>
|
||
<dd>
|
||
<p>Control when Ghostty preserves a zoomed split. Under normal
|
||
circumstances, any operation that changes focus or layout of the split
|
||
tree in a window will unzoom any zoomed split. This configuration allows
|
||
you to control this behavior.</p>
|
||
<p>This can be set to <code>navigation</code> to preserve the zoomed
|
||
split state when navigating to another split (e.g. via
|
||
<code>goto_split</code>). This will change the zoomed split to the newly
|
||
focused split instead of unzooming.</p>
|
||
<p>Any options can also be prefixed with <code>no-</code> to disable
|
||
that option.</p>
|
||
<p>Example: <code>split-preserve-zoom = navigation</code></p>
|
||
<p>Available since: 1.3.0</p>
|
||
</dd>
|
||
<dt><strong><code>--search-foreground</code></strong></dt>
|
||
<dd>
|
||
<p>The foreground and background color for search matches. This only
|
||
applies to non-focused search matches, also known as candidate
|
||
matches.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li>Hex (<code>#RRGGBB</code> or <code>RRGGBB</code>)</li>
|
||
<li>Named X11 color</li>
|
||
<li>“cell-foreground” to match the cell foreground color</li>
|
||
<li>“cell-background” to match the cell background color</li>
|
||
</ul>
|
||
<p>The default value is black text on a golden yellow background.</p>
|
||
</dd>
|
||
</dl>
|
||
<p><strong><code>--search-background</code></strong></p>
|
||
<dl>
|
||
<dt><strong><code>--search-selected-foreground</code></strong></dt>
|
||
<dd>
|
||
<p>The foreground and background color for the currently selected search
|
||
match. This is the focused match that will be jumped to when using
|
||
next/previous search navigation.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li>Hex (<code>#RRGGBB</code> or <code>RRGGBB</code>)</li>
|
||
<li>Named X11 color</li>
|
||
<li>“cell-foreground” to match the cell foreground color</li>
|
||
<li>“cell-background” to match the cell background color</li>
|
||
</ul>
|
||
<p>The default value is black text on a soft peach background.</p>
|
||
</dd>
|
||
</dl>
|
||
<p><strong><code>--search-selected-background</code></strong></p>
|
||
<dl>
|
||
<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> to offload shell argument expansion.</p>
|
||
<p>To avoid shell expansion altogether, prefix the command with
|
||
<code>direct:</code>, e.g. <code>direct:nvim foo</code>. This will avoid
|
||
the roundtrip to <code>/bin/sh</code> but will also not support any
|
||
shell parsing such as arguments with spaces, filepaths with
|
||
<code>~</code>, globs, etc. (Available since: 1.2.0)</p>
|
||
<p>You can also explicitly prefix the command with <code>shell:</code>
|
||
to always wrap the command in a shell. This can be used to ensure our
|
||
heuristics to choose the right mode are not used in case they are wrong.
|
||
(Available since: 1.2.0)</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>Disables shell expansion since the input is expected to already
|
||
be shell-expanded by the upstream (e.g. the shell used to type in the
|
||
<code>ghostty -e</code> command).</p></li>
|
||
<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 (e.g. 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 appropriately or source the shell integration
|
||
script manually.</p></li>
|
||
</ul>
|
||
</dd>
|
||
<dt><strong><code>--notify-on-command-finish</code></strong></dt>
|
||
<dd>
|
||
<p>Controls when command finished notifications are sent. There are
|
||
three options:</p>
|
||
<ul>
|
||
<li><code>never</code> - Never send notifications (the default).</li>
|
||
<li><code>unfocused</code> - Only send notifications if the surface that
|
||
the command is running in is not focused.</li>
|
||
<li><code>always</code> - Always send notifications.</li>
|
||
</ul>
|
||
<p>Command finished notifications requires that either shell integration
|
||
is enabled, or that your shell sends OSC 133 escape sequences to mark
|
||
the start and end of commands.</p>
|
||
<p>On GTK, there is a context menu item that will enable command
|
||
finished notifications for a single command, overriding the
|
||
<code>never</code> and <code>unfocused</code> options.</p>
|
||
<p>Available since 1.3.0.</p>
|
||
</dd>
|
||
<dt><strong><code>--notify-on-command-finish-action</code></strong></dt>
|
||
<dd>
|
||
<p>If command finished notifications are enabled, this controls how the
|
||
user is notified.</p>
|
||
<p>Available options:</p>
|
||
<ul>
|
||
<li><code>bell</code> - enabled by default</li>
|
||
<li><code>notify</code> - disabled by default</li>
|
||
</ul>
|
||
<p>Options can be combined by listing them as a comma separated list.
|
||
Options can be negated by prefixing them with <code>no-</code>. For
|
||
example <code>no-bell,notify</code>.</p>
|
||
<p>Available since 1.3.0.</p>
|
||
</dd>
|
||
<dt><strong><code>--notify-on-command-finish-after</code></strong></dt>
|
||
<dd>
|
||
<p>If command finished notifications are enabled, this controls how long
|
||
a command must have been running before a notification will be sent. The
|
||
default is five seconds.</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>Available since 1.3.0</p>
|
||
</dd>
|
||
<dt><strong><code>--env</code></strong></dt>
|
||
<dd>
|
||
<p>Extra environment variables to pass to commands launched in a
|
||
terminal surface. The format is <code>env=KEY=VALUE</code>.</p>
|
||
<p><code>env = foo=bar</code> <code>env = bar=baz</code></p>
|
||
<p>Setting <code>env</code> to an empty string will reset the entire map
|
||
to default (empty).</p>
|
||
<p><code>env =</code></p>
|
||
<p>Setting a key to an empty string will remove that particular key and
|
||
corresponding value from the map.</p>
|
||
<p><code>env = foo=bar</code> <code>env = foo=</code></p>
|
||
<p>will result in <code>foo</code> not being passed to the launched
|
||
commands.</p>
|
||
<p>Setting a key multiple times will overwrite previous entries.</p>
|
||
<p><code>env = foo=bar</code> <code>env = foo=baz</code></p>
|
||
<p>will result in <code>foo=baz</code> being passed to the launched
|
||
commands.</p>
|
||
<p>These environment variables will override any existing environment
|
||
variables set by Ghostty. For example, if you set
|
||
<code>GHOSTTY_RESOURCES_DIR</code> then the value you set here will
|
||
override the value Ghostty typically automatically injects.</p>
|
||
<p>These environment variables <em>will not</em> be passed to commands
|
||
run by Ghostty for other purposes, like <code>open</code> or
|
||
<code>xdg-open</code> used to open URLs in your browser.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--input</code></strong></dt>
|
||
<dd>
|
||
<p>Data to send as input to the command on startup.</p>
|
||
<p>The configured <code>command</code> will be launched using the
|
||
typical rules, then the data specified as this input will be written to
|
||
the pty before any other input can be provided.</p>
|
||
<p>The bytes are sent as-is with no additional encoding. Therefore, be
|
||
cautious about input that can contain control characters, because this
|
||
can be used to execute programs in a shell.</p>
|
||
<p>The format of this value is:</p>
|
||
<ul>
|
||
<li><p><code>raw:<string></code> - Send raw text as-is. This uses
|
||
Zig string literal syntax so you can specify control characters and
|
||
other standard escapes.</p></li>
|
||
<li><p><code>path:<path></code> - Read a filepath and send the
|
||
contents. The path must be to a file with finite length. e.g. don’t use
|
||
a device such as <code>/dev/stdin</code> or <code>/dev/urandom</code> as
|
||
these will block terminal startup indefinitely. Files are limited to
|
||
10MB in size to prevent excessive memory usage. If you have files larger
|
||
than this you should write a script to read the file and send it to the
|
||
terminal.</p></li>
|
||
</ul>
|
||
<p>If no valid prefix is found, it is assumed to be a <code>raw:</code>
|
||
input. This is an ergonomic choice to allow you to simply write
|
||
<code>input = "Hello, world!"</code> (a common case) without needing to
|
||
prefix every value with <code>raw:</code>.</p>
|
||
<p>This can be repeated multiple times to send more data. The data is
|
||
concatenated directly with no separator characters in between (e.g. no
|
||
newline).</p>
|
||
<p>If any of the input sources do not exist, then none of the input will
|
||
be sent. Input sources are not verified until the terminal is starting,
|
||
so missing paths will not show up in config validation.</p>
|
||
<p>Changing this configuration at runtime will only affect new
|
||
terminals.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</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>--scrollbar</code></strong></dt>
|
||
<dd>
|
||
<p>Control when the scrollbar is shown to scroll the scrollback
|
||
buffer.</p>
|
||
<p>The default value is <code>system</code>.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li><p><code>system</code> - Respect the system settings for when to
|
||
show scrollbars. For example, on macOS, this will respect the “Scrollbar
|
||
behavior” system setting which by default usually only shows scrollbars
|
||
while actively scrolling or hovering the gutter.</p></li>
|
||
<li><p><code>never</code> - Never show a scrollbar. You can still scroll
|
||
using the mouse, keybind actions, etc. but you will not have a visual UI
|
||
widget showing a scrollbar.</p></li>
|
||
</ul>
|
||
</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
|
||
(e.g. <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 command (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>--link-previews</code></strong></dt>
|
||
<dd>
|
||
<p>Show link previews for a matched URL.</p>
|
||
<p>When true, link previews are shown for all matched URLs. When false,
|
||
link previews are never shown. When set to “osc8”, link previews are
|
||
only shown for hyperlinks created with the OSC 8 sequence (in this case,
|
||
the link text can differ from the link destination).</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--maximize</code></strong></dt>
|
||
<dd>
|
||
<p>Whether to start the window in a maximized state. 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>Available since: 1.1.0</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>Allowable values are:</p>
|
||
<ul>
|
||
<li><code>false</code> - Don’t start in fullscreen (default)</li>
|
||
<li><code>true</code> - Start in native fullscreen</li>
|
||
<li><code>non-native</code> - (macOS only) Start in non-native
|
||
fullscreen, hiding the menu bar. This is faster than native fullscreen
|
||
since it doesn’t use animations. On non-macOS platforms, this behaves
|
||
the same as <code>true</code>.</li>
|
||
<li><code>non-native-visible-menu</code> - (macOS only) Start in
|
||
non-native fullscreen, keeping the menu bar visible. On non-macOS
|
||
platforms, behaves like <code>true</code>.</li>
|
||
<li><code>non-native-padded-notch</code> - (macOS only) Start in
|
||
non-native fullscreen, hiding the menu bar but padding for the notch on
|
||
applicable devices. On non-macOS platforms, behaves like
|
||
<code>true</code>.</li>
|
||
</ul>
|
||
<p>Important: tabs DO NOT WORK with non-native fullscreen modes.
|
||
Non-native fullscreen removes the titlebar and macOS native tabs require
|
||
the titlebar. If you use tabs, use <code>true</code> (native)
|
||
instead.</p>
|
||
<p>On macOS, <code>true</code> (native fullscreen) does not work if
|
||
<code>window-decoration</code> is set to <code>false</code>, because
|
||
native fullscreen on macOS requires window decorations.</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 to 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), the Wayland application ID (when
|
||
running under Wayland), and the bus name that Ghostty uses to connect to
|
||
DBus.</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>Changing this value may break launching Ghostty from
|
||
<code>.desktop</code> files, via DBus activation, or systemd user
|
||
services as the system is expecting Ghostty to connect to DBus using the
|
||
default <code>class</code> when it is launched.</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 path, a path prefixed with
|
||
<code>~/</code> (the tilde will be expanded to the user’s home
|
||
directory), 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>.</p>
|
||
<p>If the key is a single Unicode codepoint, the trigger will match any
|
||
presses that produce that codepoint. These are impacted by keyboard
|
||
layouts. For example, <code>a</code> will match the <code>a</code> key
|
||
on a QWERTY keyboard, but will match the <code>q</code> key on a AZERTY
|
||
keyboard (assuming US physical layout).</p>
|
||
<p>For Unicode codepoints, matching is done by comparing the set of
|
||
modifiers with the unmodified codepoint. The unmodified codepoint is
|
||
sometimes called an “unshifted character” in other software, but all
|
||
modifiers are considered, not only shift. For example,
|
||
<code>ctrl+a</code> will match <code>a</code> but not
|
||
<code>ctrl+shift+a</code> (which is <code>A</code> on a US
|
||
keyboard).</p>
|
||
<p>Further, codepoint matching is case-insensitive and the unmodified
|
||
codepoint is always case folded for comparison. As a result,
|
||
<code>ctrl+A</code> configured will match when <code>ctrl+a</code> is
|
||
pressed. Note that this means some key combinations are impossible
|
||
depending on keyboard layout. For example, <code>ctrl+_</code> is
|
||
impossible on a US keyboard because <code>_</code> is
|
||
<code>shift+-</code> and <code>ctrl+shift+-</code> is not equal to
|
||
<code>ctrl+_</code> (because the modifiers don’t match!). More details
|
||
on impossible key combinations can be found at this excellent source
|
||
written by Qt developers:
|
||
https://doc.qt.io/qt-6/qkeysequence.html#keyboard-layout-issues</p>
|
||
<p>Physical key codes can be specified by using any of the key codes as
|
||
specified by the <a href="https://www.w3.org/TR/uievents-code/">W3C
|
||
specification</a>. For example, <code>KeyA</code> will match the
|
||
physical <code>a</code> key on a US standard keyboard regardless of the
|
||
keyboard layout. These are case-sensitive.</p>
|
||
<p>For aesthetic reasons, the w3c codes also support snake case. For
|
||
example, <code>key_a</code> is equivalent to <code>KeyA</code>. The only
|
||
exceptions are function keys, e.g. <code>F1</code> is <code>f1</code>
|
||
(no underscore). This is a consequence of our internal code using snake
|
||
case but is purposely supported and tested so it is safe to use. It
|
||
allows an all-lowercase binding which I find more aesthetically
|
||
pleasing.</p>
|
||
<p>Function keys such as <code>insert</code>, <code>up</code>,
|
||
<code>f5</code>, etc. are also specified using the keys as specified by
|
||
the previously linked W3C specification.</p>
|
||
<p>Physical keys always match with a higher priority than Unicode
|
||
codepoints, so if you specify both <code>a</code> and <code>KeyA</code>,
|
||
the physical key will always be used regardless of what order they are
|
||
configured.</p>
|
||
<p>The special key <code>catch_all</code> can be used to match any key
|
||
that is not otherwise bound. This can be combined with modifiers, for
|
||
example <code>ctrl+catch_all</code> will match any key pressed with
|
||
<code>ctrl</code> that is not otherwise bound. When looking up a
|
||
binding, Ghostty first tries to match <code>catch_all</code> with
|
||
modifiers. If no match is found and the event has modifiers, it falls
|
||
back to <code>catch_all</code> without modifiers.</p>
|
||
<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>Some additional notes for triggers:</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>
|
||
</ul>
|
||
<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
|
||
(e.g. <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 an unbound key is pressed during a sequence and a
|
||
<code>catch_all</code> binding exists that would <code>ignore</code> the
|
||
input, the entire sequence is dropped and nothing happens. Otherwise,
|
||
the entire sequence is encoded and sent to the running program as if no
|
||
keybind existed.</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. Unbind will remove any matching
|
||
trigger, including <code>physical:</code>-prefixed triggers without
|
||
specifying the prefix.</p></li>
|
||
<li><p><code>csi:text</code> - Send a CSI sequence.
|
||
e.g. <code>csi:A</code> sends “cursor up”.</p></li>
|
||
<li><p><code>esc:text</code> - Send an escape sequence.
|
||
e.g. <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. e.g. <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></p>
|
||
<p>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
|
||
(e.g. <code>quit</code>), this prefix has no effect.</p>
|
||
<p>Available since: 1.0.0</p></li>
|
||
<li><p><code>global:</code></p>
|
||
<p>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 (e.g. even when Ghostty is not focused), specify this
|
||
prefix. This prefix implies <code>all:</code>.</p>
|
||
<p>Note: this does not work in all environments; see the additional
|
||
notes below for more information.</p>
|
||
<p>Available since: 1.0.0 on macOS, 1.2.0 on GTK</p></li>
|
||
<li><p><code>unconsumed:</code></p>
|
||
<p>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>
|
||
<p>Available since: 1.0.0</p></li>
|
||
<li><p><code>performable:</code></p>
|
||
<p>Only consume the input if the action is able to be performed. For
|
||
example, the <code>copy_to_clipboard</code> action will only consume the
|
||
input if there is a selection to copy. If there is no selection, Ghostty
|
||
behaves as if the keybind was not set. This has no effect with
|
||
<code>global:</code> or <code>all:</code>-prefixed keybinds. For key
|
||
sequences, this will reset the sequence if the action is not performable
|
||
(acting identically to not having a keybind set at all).</p>
|
||
<p>Performable keybinds will not appear as menu shortcuts in the
|
||
application menu. This is because the menu shortcuts force the action to
|
||
be performed regardless of the state of the terminal. Performable
|
||
keybinds will still work, they just won’t appear as a shortcut label in
|
||
the menu.</p>
|
||
<p>Available since: 1.1.0</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 and certain
|
||
Linux platforms.</p>
|
||
<p>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>
|
||
<p>On Linux, you need a desktop environment that implements the <a
|
||
href="https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.GlobalShortcuts.html">Global
|
||
Shortcuts</a> protocol as a part of its XDG desktop protocol
|
||
implementation. Desktop environments that are known to support (or not
|
||
support) global shortcuts include:</p>
|
||
<ul>
|
||
<li><p>Users using KDE Plasma (since <a
|
||
href="https://kde.org/announcements/plasma/5/5.27.0/#wayland">5.27</a>)
|
||
and GNOME (since <a
|
||
href="https://release.gnome.org/48/#and-thats-not-all">48</a>) should be
|
||
able to use global shortcuts with little to no configuration.</p></li>
|
||
<li><p>Some manual configuration is required on Hyprland. Consult the
|
||
steps outlined on the <a
|
||
href="https://wiki.hyprland.org/Configuring/Binds/#dbus-global-shortcuts">Hyprland
|
||
Wiki</a> to set up global shortcuts correctly. (Important: <a
|
||
href="https://wiki.hyprland.org/Hypr-Ecosystem/xdg-desktop-portal-hyprland/"><code>xdg-desktop-portal-hyprland</code></a>
|
||
must also be installed!)</p></li>
|
||
<li><p>Notably, global shortcuts have not been implemented on
|
||
wlroots-based compositors like Sway (see <a
|
||
href="https://github.com/emersion/xdg-desktop-portal-wlr/issues/240">upstream
|
||
issue</a>).</p></li>
|
||
</ul>
|
||
<h2 id="chained-actions">Chained Actions</h2>
|
||
<p>A keybind can have multiple actions by using the <code>chain</code>
|
||
keyword for subsequent actions. When a keybind is activated, all chained
|
||
actions are executed in order. The syntax is:</p>
|
||
<div class="sourceCode" id="cb5"><pre
|
||
class="sourceCode ini"><code class="sourceCode ini"><span id="cb5-1"><a href="#cb5-1" aria-hidden="true" tabindex="-1"></a><span class="dt">keybind </span><span class="ot">=</span><span class="st"> ctrl+a=new_window</span></span>
|
||
<span id="cb5-2"><a href="#cb5-2" aria-hidden="true" tabindex="-1"></a><span class="dt">keybind </span><span class="ot">=</span><span class="st"> chain=goto_split:left</span></span></code></pre></div>
|
||
<p>This binds <code>ctrl+a</code> to first open a new window, then move
|
||
focus to the left split. Each <code>chain</code> entry appends an action
|
||
to the most recently defined keybind. You can chain as many actions as
|
||
you want:</p>
|
||
<div class="sourceCode" id="cb6"><pre
|
||
class="sourceCode ini"><code class="sourceCode ini"><span id="cb6-1"><a href="#cb6-1" aria-hidden="true" tabindex="-1"></a><span class="dt">keybind </span><span class="ot">=</span><span class="st"> ctrl+a=new_window</span></span>
|
||
<span id="cb6-2"><a href="#cb6-2" aria-hidden="true" tabindex="-1"></a><span class="dt">keybind </span><span class="ot">=</span><span class="st"> chain=goto_split:left</span></span>
|
||
<span id="cb6-3"><a href="#cb6-3" aria-hidden="true" tabindex="-1"></a><span class="dt">keybind </span><span class="ot">=</span><span class="st"> chain=toggle_fullscreen</span></span></code></pre></div>
|
||
<p>Chained actions cannot have prefixes like <code>global:</code> or
|
||
<code>unconsumed:</code>. The flags from the original keybind apply to
|
||
the entire chain.</p>
|
||
<p>Chained actions work with key sequences as well. For example:</p>
|
||
<div class="sourceCode" id="cb7"><pre
|
||
class="sourceCode ini"><code class="sourceCode ini"><span id="cb7-1"><a href="#cb7-1" aria-hidden="true" tabindex="-1"></a><span class="dt">keybind </span><span class="ot">=</span><span class="st"> ctrl+a>n=new_window</span></span>
|
||
<span id="cb7-2"><a href="#cb7-2" aria-hidden="true" tabindex="-1"></a><span class="dt">keybind </span><span class="ot">=</span><span class="st"> chain=goto_split:left</span></span></code></pre></div>
|
||
<p>Chains with key sequences apply to the most recent binding in the
|
||
sequence.</p>
|
||
<p>Chained keybinds are available since Ghostty 1.3.0.</p>
|
||
<h2 id="key-tables">Key Tables</h2>
|
||
<p>You may also create a named set of keybindings known as a “key
|
||
table.” A key table must be explicitly activated for the bindings to
|
||
become available. This can be used to implement features such as a “copy
|
||
mode”, “vim mode”, etc. Generically, this can implement modal keyboard
|
||
input.</p>
|
||
<p>Key tables are defined using the syntax
|
||
<code><table>/<binding></code>. The
|
||
<code><binding></code> value is everything documented above for
|
||
keybinds. The <code><table></code> value is the name of the key
|
||
table. Table names can contain anything except <code>/</code>,
|
||
<code>=</code>, <code>+</code>, and <code>></code>. The characters
|
||
<code>+</code> and <code>></code> are reserved for keybind syntax
|
||
(modifier combinations and key sequences). For example
|
||
<code>foo/ctrl+a=new_window</code> defines a binding within a table
|
||
named <code>foo</code>.</p>
|
||
<p>Tables are activated and deactivated using the binding actions
|
||
<code>activate_key_table:<name></code> and
|
||
<code>deactivate_key_table</code>. Other table related binding actions
|
||
also exist; see the documentation for a full list. These are the primary
|
||
way to interact with key tables.</p>
|
||
<p>Binding lookup proceeds from the innermost table outward, so keybinds
|
||
in the default table remain available unless explicitly unbound in an
|
||
inner table.</p>
|
||
<p>A key table has some special syntax and handling:</p>
|
||
<ul>
|
||
<li><p><code><name>/</code> (with no binding) defines and clears a
|
||
table, resetting all of its keybinds and settings.</p></li>
|
||
<li><p>You cannot activate a table that is already the innermost table;
|
||
such attempts are ignored. However, the same table can appear multiple
|
||
times in the stack as long as it is not innermost (e.g.,
|
||
<code>A -> B -> A -> B</code> is valid, but
|
||
<code>A -> B -> B</code> is not).</p></li>
|
||
<li><p>A table can be activated in one-shot mode using
|
||
<code>activate_key_table_once:<name></code>. A one-shot table is
|
||
automatically deactivated when any non-catch-all binding is
|
||
invoked.</p></li>
|
||
<li><p>Key sequences work within tables:
|
||
<code>foo/ctrl+a>ctrl+b=new_window</code>. If an invalid key is
|
||
pressed, the sequence ends but the table remains active.</p></li>
|
||
<li><p>Chain actions work within tables, the <code>chain</code> keyword
|
||
applies to the most recently defined binding in the table. e.g. if you
|
||
set <code>table/ctrl+a=new_window</code> you can chain by using
|
||
<code>chain=text:hello</code>. Important: chain itself doesn’t get
|
||
prefixed with the table name, since it applies to the most recent
|
||
binding in any table.</p></li>
|
||
<li><p>Prefixes like <code>global:</code> work within tables:
|
||
<code>foo/global:ctrl+a=new_window</code>.</p></li>
|
||
</ul>
|
||
<p>Key tables are available since Ghostty 1.3.0.</p>
|
||
</dd>
|
||
<dt><strong><code>--key-remap</code></strong></dt>
|
||
<dd>
|
||
<p>Remap modifier keys within Ghostty. This allows you to swap or
|
||
reassign modifier keys at the application level without affecting
|
||
system-wide settings.</p>
|
||
<p>The format is <code>from=to</code> where both <code>from</code> and
|
||
<code>to</code> are modifier key names. You can use generic names like
|
||
<code>ctrl</code>, <code>alt</code>, <code>shift</code>,
|
||
<code>super</code> (macOS: <code>cmd</code>/<code>command</code>) or
|
||
sided names like <code>left_ctrl</code>, <code>right_alt</code>,
|
||
etc.</p>
|
||
<p>This will NOT change keyboard layout or key encodings outside of
|
||
Ghostty. For example, on macOS, <code>option+a</code> may still produce
|
||
<code>å</code> even if <code>option</code> is remapped to
|
||
<code>ctrl</code>. Desktop environments usually handle key layout long
|
||
before Ghostty receives the key events.</p>
|
||
<p>Example:</p>
|
||
<pre><code>key-remap = ctrl=super
|
||
key-remap = left_control=right_alt</code></pre>
|
||
<p>Important notes:</p>
|
||
<ul>
|
||
<li><p>This is a one-way remap. If you remap <code>ctrl=super</code>,
|
||
then the physical Ctrl key acts as Super, but the Super key remains
|
||
Super.</p></li>
|
||
<li><p>Remaps are not transitive. If you remap <code>ctrl=super</code>
|
||
and <code>alt=ctrl</code>, pressing Alt will produce Ctrl, NOT
|
||
Super.</p></li>
|
||
<li><p>This affects both keybind matching and terminal input encoding.
|
||
This does NOT impact keyboard layout or how keys are interpreted prior
|
||
to Ghostty receiving them. For example, <code>option+a</code> on macOS
|
||
may still produce <code>å</code> even if <code>option</code> is remapped
|
||
to <code>ctrl</code>.</p></li>
|
||
<li><p>Generic modifiers (e.g. <code>ctrl</code>) match both left and
|
||
right physical keys. Use sided names (e.g. <code>left_ctrl</code>) to
|
||
remap only one side.</p></li>
|
||
</ul>
|
||
<p>There are other edge case scenarios that may not behave as expected
|
||
but are working as intended the way this feature is designed:</p>
|
||
<ul>
|
||
<li>On macOS, bindings in the main menu will trigger before any
|
||
remapping is done. This is because macOS itself handles menu activation
|
||
and this happens before Ghostty receives the key event. To workaround
|
||
this, you should unbind the menu items and rebind them using your
|
||
desired modifier.</li>
|
||
</ul>
|
||
<p>This configuration can be repeated to specify multiple remaps.</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 (e.g. 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 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>--tab-inherit-working-directory</code></strong></dt>
|
||
<dd>
|
||
<p>If true, new tabs will inherit the working directory of the
|
||
previously focused tab. If no tab was previously focused, the default
|
||
working directory will be used (the <code>working-directory</code>
|
||
option).</p>
|
||
</dd>
|
||
<dt><strong><code>--split-inherit-working-directory</code></strong></dt>
|
||
<dd>
|
||
<p>If true, new split panes will inherit the working directory of the
|
||
previously focused split. If no split 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>Configure a preference for window decorations. This setting specifies
|
||
a <em>preference</em>; the actual OS, desktop environment, window
|
||
manager, etc. may override this preference. Ghostty will do its best to
|
||
respect this preference but it may not always be possible.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li><p><code>none</code></p>
|
||
<p>All window decorations will be disabled. Titlebar, borders, etc. will
|
||
not be shown. On macOS, this will also disable tabs (enforced by the
|
||
system).</p></li>
|
||
<li><p><code>auto</code></p>
|
||
<p>Automatically decide to use either client-side or server-side
|
||
decorations based on the detected preferences of the current OS and
|
||
desktop environment. This option usually makes Ghostty look the most
|
||
“native” for your desktop.</p></li>
|
||
<li><p><code>client</code></p>
|
||
<p>Prefer client-side decorations.</p>
|
||
<p>Available since: 1.1.0</p></li>
|
||
<li><p><code>server</code></p>
|
||
<p>Prefer server-side decorations. This is only relevant on Linux with
|
||
GTK, either on X11, or Wayland on a compositor that supports the
|
||
<code>org_kde_kwin_server_decoration</code> protocol (e.g. KDE Plasma,
|
||
but almost any non-GNOME desktop supports this protocol).</p>
|
||
<p>If <code>server</code> is set but the environment doesn’t support
|
||
server-side decorations, client-side decorations will be used
|
||
instead.</p>
|
||
<p>Available since: 1.1.0</p></li>
|
||
</ul>
|
||
<p>The default value is <code>auto</code>.</p>
|
||
<p>For the sake of backwards compatibility and convenience, this setting
|
||
also accepts boolean true and false values. If set to <code>true</code>,
|
||
this is equivalent to <code>auto</code>. If set to <code>false</code>,
|
||
this is equivalent to <code>none</code>. This is convenient for users
|
||
who live primarily on systems that don’t differentiate between client
|
||
and server-side decorations (e.g. macOS and Windows).</p>
|
||
<p>The “toggle_window_decorations” keybind action can be used to create
|
||
a keybinding to toggle this setting at runtime.</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>If this setting is left unset, the system default font will be
|
||
used.</p>
|
||
<p>Note: any font available on the system may be used, this font is not
|
||
required to be a fixed-width font.</p>
|
||
<p>Available since: 1.0.0 on macOS, 1.1.0 on GTK</p>
|
||
</dd>
|
||
<dt><strong><code>--window-subtitle</code></strong></dt>
|
||
<dd>
|
||
<p>The text that will be displayed in the subtitle of the window. Valid
|
||
values:</p>
|
||
<ul>
|
||
<li><code>false</code> - Disable the subtitle.</li>
|
||
<li><code>working-directory</code> - Set the subtitle to the working
|
||
directory of the surface.</li>
|
||
</ul>
|
||
<p>This feature is only supported on GTK.</p>
|
||
<p>Available since: 1.1.0</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.</li>
|
||
</ul>
|
||
<p>On macOS, if <code>macos-titlebar-style</code> is <code>tabs</code>
|
||
or <code>transparent</code>, 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 color space to use when interpreting terminal colors. “Terminal
|
||
colors” refers to colors specified in your configuration and colors
|
||
produced by direct-color SGR sequences.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li><code>srgb</code> - Interpret colors in the sRGB color space. This
|
||
is the default.</li>
|
||
<li><code>display-p3</code> - Interpret colors in the Display P3 color
|
||
space.</li>
|
||
</ul>
|
||
<p>This setting is currently 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 <code>window-decoration</code>), 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-position-x</code></strong></dt>
|
||
<dd>
|
||
<p>The starting window position. This position is in pixels and is
|
||
relative to the top-left corner of the primary monitor. Both values must
|
||
be set to take effect. If only one value is set, it is ignored.</p>
|
||
<p>Note that the window manager may put limits on the position or
|
||
override the position. For example, a tiling window manager may force
|
||
the window to be a certain position to fit within the grid. There is
|
||
nothing Ghostty will do about this, but it will make an effort.</p>
|
||
<p>Also note that negative values are also up to the operating system
|
||
and window manager. Some window managers may not allow windows to be
|
||
placed off-screen.</p>
|
||
<p>Invalid positions are runtime-specific, but generally the positions
|
||
are clamped to the nearest valid position.</p>
|
||
<p>On macOS, the window position is relative to the top-left corner of
|
||
the visible screen area. This means that if the menu bar is visible, the
|
||
window will be placed below the menu bar.</p>
|
||
<p>Note: this is only supported on macOS. The GTK runtime does not
|
||
support setting the window position, as windows are only allowed
|
||
position themselves in X11 and not Wayland.</p>
|
||
</dd>
|
||
</dl>
|
||
<p><strong><code>--window-position-y</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>--window-show-tab-bar</code></strong></dt>
|
||
<dd>
|
||
<p>Whether to show the tab bar.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li><p><code>always</code></p>
|
||
<p>Always display the tab bar, even when there’s only one tab.</p>
|
||
<p>Available since: 1.2.0</p></li>
|
||
<li><p><code>auto</code> <em>(default)</em></p>
|
||
<p>Automatically show and hide the tab bar. The tab bar is only shown
|
||
when there are two or more tabs present.</p></li>
|
||
<li><p><code>never</code></p>
|
||
<p>Never show the tab bar. Tabs are only accessible via the tab overview
|
||
or by keybind actions.</p></li>
|
||
</ul>
|
||
<p>Currently only supported on Linux (GTK).</p>
|
||
</dd>
|
||
<dt><strong><code>--window-titlebar-background</code></strong></dt>
|
||
<dd>
|
||
<p>Background color for the window titlebar. This only takes effect if
|
||
window-theme is set to ghostty. Currently only supported in the GTK app
|
||
runtime.</p>
|
||
<p>Specified as either hex (<code>#RRGGBB</code> or <code>RRGGBB</code>)
|
||
or a named X11 color.</p>
|
||
</dd>
|
||
<dt><strong><code>--window-titlebar-foreground</code></strong></dt>
|
||
<dd>
|
||
<p>Foreground color for the window titlebar. This only takes effect if
|
||
window-theme is set to ghostty. Currently only supported in the GTK app
|
||
runtime.</p>
|
||
<p>Specified as either hex (<code>#RRGGBB</code> or <code>RRGGBB</code>)
|
||
or a named X11 color.</p>
|
||
</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>
|
||
<p>Available since 1.0.0</p>
|
||
</dd>
|
||
<dt><strong><code>--focus-follows-mouse</code></strong></dt>
|
||
<dd>
|
||
<p>If true, when there are multiple split panes, the mouse selects the
|
||
pane that is focused. This only applies to the currently focused window;
|
||
e.g. mousing over a split in an unfocused window will not focus that
|
||
split and bring the window to front.</p>
|
||
<p>Default is false.</p>
|
||
</dd>
|
||
<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>. This only applies to trailing whitespace
|
||
on lines that have other characters. Completely blank lines always have
|
||
their whitespace trimmed.</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>--title-report</code></strong></dt>
|
||
<dd>
|
||
<p>Enables or disabled title reporting (CSI 21 t). This escape sequence
|
||
allows the running program to query the terminal title. This is a common
|
||
security issue and is disabled by default.</p>
|
||
<p>Warning: This can expose sensitive information at best and enable
|
||
arbitrary code execution at worst (with a maliciously crafted title and
|
||
a minor amount of user interaction).</p>
|
||
<p>Available since: 1.0.1</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 (e.g. 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,
|
||
otherwise it will copy to the system clipboard.</p>
|
||
<p>The value <code>clipboard</code> will always copy text to the
|
||
selection clipboard as well as the system clipboard.</p>
|
||
<p>Middle-click paste will always use the selection clipboard.
|
||
Middle-click paste is always enabled even if this is
|
||
<code>false</code>.</p>
|
||
<p>The default value is true on Linux and macOS.</p>
|
||
</dd>
|
||
<dt><strong><code>--right-click-action</code></strong></dt>
|
||
<dd>
|
||
<p>The action to take when the user right-clicks on the terminal
|
||
surface.</p>
|
||
<p>Valid values: * <code>context-menu</code> - Show the context menu. *
|
||
<code>paste</code> - Paste the contents of the clipboard. *
|
||
<code>copy</code> - Copy the selected text to the clipboard. *
|
||
<code>copy-or-paste</code> - If there is a selection, copy the selected
|
||
text to the clipboard; otherwise, paste the contents of the clipboard. *
|
||
<code>ignore</code> - Do nothing, ignore the right-click.</p>
|
||
<p>The default value is <code>context-menu</code>.</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.ghostty).</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.</p>
|
||
<p>This defaults to <code>true</code>. If set to <code>false</code>,
|
||
surfaces will close without any confirmation. This can also be set to
|
||
<code>always</code>, which will always confirm closing a surface, even
|
||
if shell integration says a process isn’t running.</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>--undo-timeout</code></strong></dt>
|
||
<dd>
|
||
<p>The duration that undo operations remain available. After this time,
|
||
the operation will be removed from the undo stack and cannot be
|
||
undone.</p>
|
||
<p>The default value is 5 seconds.</p>
|
||
<p>This timeout applies per operation, meaning that if you perform
|
||
multiple operations, each operation will have its own timeout. New
|
||
operations do not reset the timeout of previous operations.</p>
|
||
<p>A timeout of zero will effectively disable undo operations. It is not
|
||
possible to set an infinite timeout, but you can set a very large
|
||
timeout to effectively disable the timeout (on the order of years). This
|
||
is highly discouraged, as it will cause the undo stack to grow
|
||
indefinitely, memory usage to grow unbounded, and terminal sessions to
|
||
never actually quit.</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>This configuration is only supported on macOS. Linux doesn’t support
|
||
undo operations at all so this configuration has no effect.</p>
|
||
<p>Available since: 1.2.0</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>
|
||
<li><code>center</code> - Terminal appears at the center of the
|
||
screen.</li>
|
||
</ul>
|
||
<p>On macOS, changing this configuration requires restarting Ghostty
|
||
completely.</p>
|
||
<p>Note: There is no default keybind for toggling the quick terminal. To
|
||
enable this feature, bind the <code>toggle_quick_terminal</code> action
|
||
to a key.</p>
|
||
</dd>
|
||
<dt><strong><code>--quick-terminal-size</code></strong></dt>
|
||
<dd>
|
||
<p>The size of the quick terminal.</p>
|
||
<p>The size can be specified either as a percentage of the screen
|
||
dimensions (height/width), or as an absolute size in pixels. Percentage
|
||
values are suffixed with <code>%</code> (e.g. <code>20%</code>) while
|
||
pixel values are suffixed with <code>px</code>
|
||
(e.g. <code>300px</code>). A bare value without a suffix is a config
|
||
error.</p>
|
||
<p>When only one size is specified, the size parameter affects the size
|
||
of the quick terminal on its <em>primary axis</em>, which depends on its
|
||
position: height for quick terminals placed on the top or bottom, and
|
||
width for left or right. The primary axis of a centered quick terminal
|
||
depends on the monitor’s orientation: height when on a landscape
|
||
monitor, and width when on a portrait monitor.</p>
|
||
<p>The <em>secondary axis</em> would be maximized for non-center
|
||
positioned quick terminals unless another size parameter is specified,
|
||
separated from the first by a comma (<code>,</code>). Percentage and
|
||
pixel sizes can be mixed together: for instance, a size of
|
||
<code>50%,500px</code> for a top-positioned quick terminal would be half
|
||
a screen tall, and 500 pixels wide.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--gtk-quick-terminal-layer</code></strong></dt>
|
||
<dd>
|
||
<p>The layer of the quick terminal window. The higher the layer, the
|
||
more windows the quick terminal may conceal.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><p><code>overlay</code></p>
|
||
<p>The quick terminal appears in front of all windows.</p></li>
|
||
<li><p><code>top</code> (default)</p>
|
||
<p>The quick terminal appears in front of normal windows but behind
|
||
fullscreen overlays like lock screens.</p></li>
|
||
<li><p><code>bottom</code></p>
|
||
<p>The quick terminal appears behind normal windows but in front of
|
||
wallpapers and other windows in the background layer.</p></li>
|
||
<li><p><code>background</code></p>
|
||
<p>The quick terminal appears behind all windows.</p></li>
|
||
</ul>
|
||
<p>GTK Wayland only.</p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--gtk-quick-terminal-namespace</code></strong></dt>
|
||
<dd>
|
||
<p>The namespace for the quick terminal window.</p>
|
||
<p>This is an identifier that is used by the Wayland compositor and/or
|
||
scripts to determine the type of layer surfaces and to possibly apply
|
||
unique effects.</p>
|
||
<p>GTK Wayland only.</p>
|
||
<p>Available since: 1.2.0</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>
|
||
<p>Only implemented on macOS.</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>
|
||
<p>Only implemented on macOS.</p>
|
||
</dd>
|
||
<dt><strong><code>--quick-terminal-autohide</code></strong></dt>
|
||
<dd>
|
||
<p>Automatically hide the quick terminal when focus shifts to another
|
||
window. Set it to false for the quick terminal to remain open even when
|
||
it loses focus.</p>
|
||
<p>Defaults to true on macOS and on false on Linux/BSD. This is because
|
||
global shortcuts on Linux require system configuration and are
|
||
considerably less accessible than on macOS, meaning that it is more
|
||
preferable to keep the quick terminal open until the user has completed
|
||
their task. This default may change in the future.</p>
|
||
</dd>
|
||
<dt><strong><code>--quick-terminal-space-behavior</code></strong></dt>
|
||
<dd>
|
||
<p>This configuration option determines the behavior of the quick
|
||
terminal when switching between macOS spaces. macOS spaces are virtual
|
||
desktops that can be manually created or are automatically created when
|
||
an application is in full-screen mode.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><p><code>move</code> - When switching to another space, the quick
|
||
terminal will also moved to the current space.</p></li>
|
||
<li><p><code>remain</code> - The quick terminal will stay only in the
|
||
space where it was originally opened and will not follow when switching
|
||
to another space.</p></li>
|
||
</ul>
|
||
<p>The default value is <code>move</code>.</p>
|
||
<p>Only implemented on macOS. On Linux the behavior is always equivalent
|
||
to <code>move</code>.</p>
|
||
<p>Available since: 1.1.0</p>
|
||
</dd>
|
||
<dt><strong><code>--quick-terminal-keyboard-interactivity</code></strong></dt>
|
||
<dd>
|
||
<p>Determines under which circumstances that the quick terminal should
|
||
receive keyboard input. See the corresponding <a
|
||
href="https://wayland.app/protocols/wlr-layer-shell-unstable-v1#zwlr_layer_surface_v1:enum:keyboard_interactivity">Wayland
|
||
documentation</a> for a more detailed explanation of the behavior of
|
||
each option.</p>
|
||
<blockquote>
|
||
<p>[!NOTE] The exact behavior of each option may differ significantly
|
||
across compositors – experiment with them on your system to find one
|
||
that suits your liking!</p>
|
||
</blockquote>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><p><code>none</code></p>
|
||
<p>The quick terminal will not receive any keyboard input.</p></li>
|
||
<li><p><code>on-demand</code> (default)</p>
|
||
<p>The quick terminal would only receive keyboard input when it is
|
||
focused.</p></li>
|
||
<li><p><code>exclusive</code></p>
|
||
<p>The quick terminal will always receive keyboard input, even when
|
||
another window is currently focused.</p></li>
|
||
</ul>
|
||
<p>Only has an effect on Linux Wayland. On macOS the behavior is always
|
||
equivalent to <code>on-demand</code>.</p>
|
||
<p>Available since: 1.2.0</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>nushell</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. These require our shell
|
||
integration to be loaded, either automatically via shell-integration or
|
||
manually.</p>
|
||
<p>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>Example: <code>cursor</code>, <code>no-cursor</code>,
|
||
<code>sudo</code>, <code>no-sudo</code>, <code>title</code>,
|
||
<code>no-title</code></p>
|
||
<p>Available features:</p>
|
||
<ul>
|
||
<li><p><code>cursor</code> - Set the cursor to a 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>
|
||
<li><p><code>ssh-env</code> - Enable SSH environment variable
|
||
compatibility. Automatically converts TERM from
|
||
<code>xterm-ghostty</code> to <code>xterm-256color</code> when
|
||
connecting to remote hosts and propagates COLORTERM, TERM_PROGRAM, and
|
||
TERM_PROGRAM_VERSION. Whether or not these variables will be accepted by
|
||
the remote host(s) will depend on whether or not the variables are
|
||
allowed in their sshd_config. (Available since: 1.2.0)</p></li>
|
||
<li><p><code>ssh-terminfo</code> - Enable automatic terminfo
|
||
installation on remote hosts. Attempts to install Ghostty’s terminfo
|
||
entry using <code>infocmp</code> and <code>tic</code> when connecting to
|
||
hosts that lack it. Requires <code>infocmp</code> to be available
|
||
locally and <code>tic</code> to be available on remote hosts. Once
|
||
terminfo is installed on a remote host, it will be automatically
|
||
“cached” to avoid repeat installations. If desired, the
|
||
<code>+ssh-cache</code> CLI action can be used to manage the
|
||
installation cache manually using various arguments. (Available since:
|
||
1.2.0)</p></li>
|
||
<li><p><code>path</code> - Add Ghostty’s binary directory to PATH. This
|
||
ensures the <code>ghostty</code> command is available in the shell even
|
||
if shell init scripts reset PATH. This is particularly useful on macOS
|
||
where PATH is often overridden by system scripts. The directory is only
|
||
added if not already present.</p></li>
|
||
</ul>
|
||
<p>SSH features work independently and can be combined for optimal
|
||
experience: when both <code>ssh-env</code> and <code>ssh-terminfo</code>
|
||
are enabled, Ghostty will install its terminfo on remote hosts and use
|
||
<code>xterm-ghostty</code> as TERM, falling back to
|
||
<code>xterm-256color</code> with environment variables if terminfo
|
||
installation fails.</p>
|
||
</dd>
|
||
<dt><strong><code>--command-palette-entry</code></strong></dt>
|
||
<dd>
|
||
<p>Custom entries into the command palette.</p>
|
||
<p>Each entry requires the title, the corresponding action, and an
|
||
optional description. Each field should be prefixed with the field name,
|
||
a colon (<code>:</code>), and then the specified value. The syntax for
|
||
actions is identical to the one for keybind actions. Whitespace in
|
||
between fields is ignored.</p>
|
||
<p>If you need to embed commas or any other special characters in the
|
||
values, enclose the value in double quotes and it will be interpreted as
|
||
a Zig string literal. This is also useful for including whitespace at
|
||
the beginning or the end of a value. See the <a
|
||
href="https://ziglang.org/documentation/master/#Escape-Sequences">Zig
|
||
documentation</a> for more information on string literals. Note that
|
||
multiline string literals are not supported.</p>
|
||
<p>Double quotes can not be used around the field names.</p>
|
||
<div class="sourceCode" id="cb10"><pre
|
||
class="sourceCode ini"><code class="sourceCode ini"><span id="cb10-1"><a href="#cb10-1" aria-hidden="true" tabindex="-1"></a><span class="dt">command-palette-entry </span><span class="ot">=</span><span class="st"> title:Reset Font Style, action:csi:0m</span></span>
|
||
<span id="cb10-2"><a href="#cb10-2" aria-hidden="true" tabindex="-1"></a><span class="dt">command-palette-entry </span><span class="ot">=</span><span class="st"> title:Crash on Main Thread,description:Causes a crash on the main (UI) thread.,action:crash:main</span></span>
|
||
<span id="cb10-3"><a href="#cb10-3" aria-hidden="true" tabindex="-1"></a><span class="dt">command-palette-entry </span><span class="ot">=</span><span class="st"> title:Focus Split: Right,description:"Focus the split to the right, if it exists.",action:goto_split:right</span></span>
|
||
<span id="cb10-4"><a href="#cb10-4" aria-hidden="true" tabindex="-1"></a><span class="dt">command-palette-entry </span><span class="ot">=</span><span class="st"> title:"Ghostty",description:"Add a little Ghostty to your terminal.",action:"text:\xf0\x9f\x91\xbb"</span></span></code></pre></div>
|
||
<p>By default, the command palette is preloaded with most actions that
|
||
might be useful in an interactive setting yet do not have easily
|
||
accessible or memorizable shortcuts. The default entries can be cleared
|
||
by setting this setting to an empty value:</p>
|
||
<div class="sourceCode" id="cb11"><pre
|
||
class="sourceCode ini"><code class="sourceCode ini"><span id="cb11-1"><a href="#cb11-1" aria-hidden="true" tabindex="-1"></a><span class="dt">command-palette-entry </span><span class="ot">=</span></span></code></pre></div>
|
||
<p>Available since: 1.2.0</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,
|
||
e.g. <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>Custom shader support is based on and compatible with the Shadertoy
|
||
shaders. Shaders should specify a <code>mainImage</code> function and
|
||
the available uniforms largely match Shadertoy, with some caveats and
|
||
Ghostty-specific extensions.</p>
|
||
<p>The uniform values available to shaders are as follows:</p>
|
||
<ul>
|
||
<li><p><code>sampler2D iChannel0</code> - Input texture.</p>
|
||
<p>A texture containing the current terminal screen. If multiple custom
|
||
shaders are specified, the output of previous shaders is written to this
|
||
texture, to allow combining multiple effects.</p></li>
|
||
<li><p><code>vec3 iResolution</code> - Output texture size,
|
||
<code>[width, height, 1]</code> (in px).</p></li>
|
||
<li><p><code>float iTime</code> - Time in seconds since first frame was
|
||
rendered.</p></li>
|
||
<li><p><code>float iTimeDelta</code> - Time in seconds since previous
|
||
frame was rendered.</p></li>
|
||
<li><p><code>float iFrameRate</code> - Average framerate. (NOT CURRENTLY
|
||
SUPPORTED)</p></li>
|
||
<li><p><code>int iFrame</code> - Number of frames that have been
|
||
rendered so far.</p></li>
|
||
<li><p><code>float iChannelTime[4]</code> - Current time for video or
|
||
sound input. (N/A)</p></li>
|
||
<li><p><code>vec3 iChannelResolution[4]</code> - Resolutions of the 4
|
||
input samplers.</p>
|
||
<p>Currently only <code>iChannel0</code> exists, and
|
||
<code>iChannelResolution[0]</code> is identical to
|
||
<code>iResolution</code>.</p></li>
|
||
<li><p><code>vec4 iMouse</code> - Mouse input info. (NOT CURRENTLY
|
||
SUPPORTED)</p></li>
|
||
<li><p><code>vec4 iDate</code> - Date/time info. (NOT CURRENTLY
|
||
SUPPORTED)</p></li>
|
||
<li><p><code>float iSampleRate</code> - Sample rate for audio.
|
||
(N/A)</p></li>
|
||
</ul>
|
||
<p>Ghostty-specific extensions:</p>
|
||
<ul>
|
||
<li><p><code>vec4 iCurrentCursor</code> - Info about the terminal
|
||
cursor.</p>
|
||
<ul>
|
||
<li><code>iCurrentCursor.xy</code> is the -X, +Y corner of the current
|
||
cursor.</li>
|
||
<li><code>iCurrentCursor.zw</code> is the width and height of the
|
||
current cursor.</li>
|
||
</ul></li>
|
||
<li><p><code>vec4 iPreviousCursor</code> - Info about the previous
|
||
terminal cursor.</p></li>
|
||
<li><p><code>vec4 iCurrentCursorColor</code> - Color of the terminal
|
||
cursor.</p></li>
|
||
<li><p><code>vec4 iPreviousCursorColor</code> - Color of the previous
|
||
terminal cursor.</p></li>
|
||
<li><p><code>vec4 iCurrentCursorStyle</code> - Style of the terminal
|
||
cursor</p>
|
||
<p>Macros simplified use are defined for the various cursor styles:</p>
|
||
<ul>
|
||
<li><code>CURSORSTYLE_BLOCK</code> or <code>0</code></li>
|
||
<li><code>CURSORSTYLE_BLOCK_HOLLOW</code> or <code>1</code></li>
|
||
<li><code>CURSORSTYLE_BAR</code> or <code>2</code></li>
|
||
<li><code>CURSORSTYLE_UNDERLINE</code> or <code>3</code></li>
|
||
<li><code>CURSORSTYLE_LOCK</code> or <code>4</code></li>
|
||
</ul></li>
|
||
<li><p><code>vec4 iPreviousCursorStyle</code> - Style of the previous
|
||
terminal cursor</p></li>
|
||
<li><p><code>vec4 iCursorVisible</code> - Visibility of the terminal
|
||
cursor.</p></li>
|
||
<li><p><code>float iTimeCursorChange</code> - Timestamp of terminal
|
||
cursor change.</p>
|
||
<p>When the terminal cursor changes position or color, this is set to
|
||
the same time as the <code>iTime</code> uniform, allowing you to compute
|
||
the time since the change by subtracting this from
|
||
<code>iTime</code>.</p></li>
|
||
<li><p><code>float iTimeFocus</code> - Timestamp when the surface last
|
||
gained iFocus.</p>
|
||
<p>When the surface gains focus, this is set to the current value of
|
||
<code>iTime</code>, similar to how <code>iTimeCursorChange</code> works.
|
||
This allows you to compute the time since focus was gained or lost by
|
||
calculating <code>iTime - iTimeFocus</code>. Use this to create
|
||
animations that restart when the terminal regains focus.</p></li>
|
||
<li><p><code>int iFocus</code> - Current focus state of the surface.</p>
|
||
<p>Set to 1.0 when the surface is focused, 0.0 when unfocused. This
|
||
allows shaders to detect unfocused state and avoid animation artifacts
|
||
from large time deltas caused by infrequent “deceptive frames” (e.g.,
|
||
modifier key presses, link hover events in unfocused split panes). Check
|
||
<code>iFocus > 0</code> to determine if the surface is currently
|
||
focused.</p></li>
|
||
<li><p><code>vec3 iPalette[256]</code> - The 256-color terminal
|
||
palette.</p>
|
||
<p>RGB values for all 256 colors in the terminal palette, normalized to
|
||
[0.0, 1.0]. Index 0-15 are the ANSI colors, 16-231 are the 6x6x6 color
|
||
cube, and 232-255 are the grayscale colors.</p></li>
|
||
<li><p><code>vec3 iBackgroundColor</code> - Terminal background color
|
||
(RGB).</p></li>
|
||
<li><p><code>vec3 iForegroundColor</code> - Terminal foreground color
|
||
(RGB).</p></li>
|
||
<li><p><code>vec3 iCursorColor</code> - Terminal cursor color
|
||
(RGB).</p></li>
|
||
<li><p><code>vec3 iCursorText</code> - Terminal cursor text color
|
||
(RGB).</p></li>
|
||
<li><p><code>vec3 iSelectionBackgroundColor</code> - Selection
|
||
background color (RGB).</p></li>
|
||
<li><p><code>vec3 iSelectionForegroundColor</code> - Selection
|
||
foreground color (RGB).</p></li>
|
||
</ul>
|
||
<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>This can be changed at runtime and will affect all open
|
||
terminals.</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 can be changed at runtime and will affect all open
|
||
terminals.</p>
|
||
</dd>
|
||
<dt><strong><code>--bell-features</code></strong></dt>
|
||
<dd>
|
||
<p>Bell features to enable if bell support is available in your runtime.
|
||
Not all features are available on all runtimes. 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.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><p><code>system</code></p>
|
||
<p>Instruct the system to notify the user using built-in system
|
||
functions. This could result in an audiovisual effect, a notification,
|
||
or something else entirely. Changing these effects require altering
|
||
system settings: for instance under the “Sound > Alert Sound” setting
|
||
in GNOME, or the “Accessibility > System Bell” settings in KDE
|
||
Plasma.</p>
|
||
<p>On macOS, this plays the system alert sound.</p></li>
|
||
<li><p><code>audio</code></p>
|
||
<p>Play a custom sound. (Available since 1.3.0 on macOS)</p></li>
|
||
<li><p><code>attention</code> <em>(enabled by default)</em></p>
|
||
<p>Request the user’s attention when Ghostty is unfocused, until it has
|
||
received focus again. On macOS, this will bounce the app icon in the
|
||
dock once. On Linux, the behavior depends on the desktop environment
|
||
and/or the window manager/compositor:</p>
|
||
<ul>
|
||
<li><p>On KDE, the background of the desktop icon in the task bar would
|
||
be highlighted;</p></li>
|
||
<li><p>On GNOME, you may receive a notification that, when clicked,
|
||
would bring the Ghostty window into focus;</p></li>
|
||
<li><p>On Sway, the window may be decorated with a distinctly colored
|
||
border;</p></li>
|
||
<li><p>On other systems this may have no effect at all.</p></li>
|
||
</ul></li>
|
||
<li><p><code>title</code> <em>(enabled by default)</em></p>
|
||
<p>Prepend a bell emoji (🔔) to the title of the alerted surface until
|
||
the terminal is re-focused or interacted with (such as on keyboard
|
||
input).</p></li>
|
||
<li><p><code>border</code></p>
|
||
<p>Display a border around the alerted surface until the terminal is
|
||
re-focused or interacted with (such as on keyboard input).</p>
|
||
<p>Available since: 1.2.0 on GTK, 1.2.1 on macOS</p></li>
|
||
</ul>
|
||
<p>Example: <code>audio</code>, <code>no-audio</code>,
|
||
<code>system</code>, <code>no-system</code></p>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--bell-audio-path</code></strong></dt>
|
||
<dd>
|
||
<p>If <code>audio</code> is an enabled bell feature, this is a path to
|
||
an audio file. If the path is not absolute, it is considered relative to
|
||
the directory of the configuration file that it is referenced from, or
|
||
from the current working directory if this is used as a CLI flag. The
|
||
path may be prefixed with <code>~/</code> to reference the user’s home
|
||
directory.</p>
|
||
<p>Available since: 1.2.0 on GTK, 1.3.0 on macOS.</p>
|
||
</dd>
|
||
<dt><strong><code>--bell-audio-volume</code></strong></dt>
|
||
<dd>
|
||
<p>If <code>audio</code> is an enabled bell feature, this is the volume
|
||
to play the audio file at (relative to the system volume). This is a
|
||
floating point number ranging from 0.0 (silence) to 1.0 (as loud as
|
||
possible). The default is 0.5.</p>
|
||
<p>Available since: 1.2.0 on GTK, 1.3.0 on macOS.</p>
|
||
</dd>
|
||
<dt><strong><code>--app-notifications</code></strong></dt>
|
||
<dd>
|
||
<p>Control the in-app notifications that Ghostty shows.</p>
|
||
<p>On Linux (GTK), in-app notifications show up as toasts. Toasts appear
|
||
overlaid on top of the terminal window. They are used to show
|
||
information that is not critical but may be important.</p>
|
||
<p>Possible notifications are:</p>
|
||
<ul>
|
||
<li><code>clipboard-copy</code> (default: true) - Show a notification
|
||
when text is copied to the clipboard.</li>
|
||
<li><code>config-reload</code> (default: true) - Show a notification
|
||
when the configuration is reloaded.</li>
|
||
</ul>
|
||
<p>To specify a notification to enable, specify the name of the
|
||
notification. To specify a notification to disable, prefix the name with
|
||
<code>no-</code>. For example, to disable <code>clipboard-copy</code>,
|
||
set this configuration to <code>no-clipboard-copy</code>. To enable it,
|
||
set this configuration to <code>clipboard-copy</code>.</p>
|
||
<p>Multiple notifications can be enabled or disabled by separating them
|
||
with a comma.</p>
|
||
<p>A value of “false” will disable all notifications. A value of “true”
|
||
will enable all notifications.</p>
|
||
<p>This configuration only applies to GTK.</p>
|
||
<p>Available since: 1.1.0</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>true</code> - Use non-native macOS fullscreen, hide the menu
|
||
bar</li>
|
||
<li><code>false</code> - Use native macOS fullscreen</li>
|
||
<li><code>visible-menu</code> - Use non-native macOS fullscreen, keep
|
||
the menu bar visible</li>
|
||
<li><code>padded-notch</code> - Use non-native macOS fullscreen, hide
|
||
the menu bar, but ensure the window is not obscured by the notch on
|
||
applicable devices. The area around the notch will remain transparent
|
||
currently, but in the future we may fill it with the window background
|
||
color.</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-window-buttons</code></strong></dt>
|
||
<dd>
|
||
<p>Whether the window buttons in the macOS titlebar are visible. The
|
||
window buttons are the colored buttons in the upper left corner of most
|
||
macOS apps, also known as the traffic lights, that allow you to close,
|
||
miniaturize, and zoom the window.</p>
|
||
<p>This setting has no effect when <code>window-decoration = none</code>
|
||
or <code>macos-titlebar-style = hidden</code>, as the window buttons are
|
||
always hidden in these modes.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><code>visible</code> - Show the window buttons.</li>
|
||
<li><code>hidden</code> - Hide the window buttons.</li>
|
||
</ul>
|
||
<p>The default value is <code>visible</code>.</p>
|
||
<p>Changing this option at runtime only applies to new windows.</p>
|
||
<p>Available since: 1.2.0</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, e.g. 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 = none</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.</p>
|
||
<p>When “hidden”, the top titlebar area can no longer be used for
|
||
dragging the window. To drag the window, you can use option+click on the
|
||
resizable areas of the frame to drag the window. This is a standard
|
||
macOS behavior and not something Ghostty enables.</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-dock-drop-behavior</code></strong></dt>
|
||
<dd>
|
||
<p>Controls the windowing behavior when dropping a file or folder onto
|
||
the Ghostty icon in the macOS dock.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><code>new-tab</code> - Create a new tab in the current window, or
|
||
open a new window if none exist.</li>
|
||
<li><code>new-window</code> - Create a new window unconditionally.</li>
|
||
</ul>
|
||
<p>The default value is <code>new-tab</code>.</p>
|
||
<p>This setting is only supported on macOS and has no effect on other
|
||
platforms.</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 produce 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. (e.g. <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>
|
||
</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-hidden</code></strong></dt>
|
||
<dd>
|
||
<p>If true, the macOS icon in the dock and app switcher will be hidden.
|
||
This is mainly intended for those primarily using the quick-terminal
|
||
mode.</p>
|
||
<p>Note that setting this to true means that keyboard layout changes
|
||
will no longer be automatic.</p>
|
||
<p>Control whether macOS app is excluded from the dock and app switcher,
|
||
a “hidden” state. This is mainly intended for those primarily using
|
||
quick-terminal mode, but is a general configuration for any use
|
||
case.</p>
|
||
<p>Available values:</p>
|
||
<ul>
|
||
<li><code>never</code> - The macOS app is never hidden.</li>
|
||
<li><code>always</code> - The macOS app is always hidden.</li>
|
||
</ul>
|
||
<p>Note: When the macOS application is hidden, keyboard layout changes
|
||
will no longer be automatic. This is a limitation of macOS.</p>
|
||
<p>Available since: 1.2.0</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>--macos-applescript</code></strong></dt>
|
||
<dd>
|
||
<p>If true, Ghostty exposes and handles the built-in AppleScript
|
||
dictionary on macOS.</p>
|
||
<p>If false, all AppleScript interactions are disabled. This includes
|
||
AppleScript commands and AppleScript object lookup for windows, tabs,
|
||
and terminals.</p>
|
||
<p>The default is true.</p>
|
||
</dd>
|
||
<dt><strong><code>--macos-icon</code></strong></dt>
|
||
<dd>
|
||
<p>Customize the macOS app icon.</p>
|
||
<p>This only affects the icon that appears in the dock, application
|
||
switcher, etc. This does not affect the icon in Finder because that is
|
||
controlled by a hardcoded value in the signed application bundle and
|
||
can’t be changed at runtime. For more details on what exactly is
|
||
affected, see the <code>NSApplication.icon</code> Apple documentation;
|
||
that is the API that is being used to set the icon.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li><code>official</code> - Use the official Ghostty icon.</li>
|
||
<li><code>blueprint</code>, <code>chalkboard</code>,
|
||
<code>microchip</code>, <code>glass</code>, <code>holographic</code>,
|
||
<code>paper</code>, <code>retro</code>, <code>xray</code> - Official
|
||
variants of the Ghostty icon hand-created by artists (no AI).</li>
|
||
<li><code>custom</code> - Use a completely custom icon. The location
|
||
must be specified using the additional <code>macos-custom-icon</code>
|
||
configuration</li>
|
||
<li><code>custom-style</code> - Use the official Ghostty icon but with
|
||
custom styles applied to various layers. The custom styles must be
|
||
specified using the additional <code>macos-icon</code>-prefixed
|
||
configurations. The <code>macos-icon-ghost-color</code> and
|
||
<code>macos-icon-screen-color</code> configurations are required for
|
||
this style.</li>
|
||
</ul>
|
||
<p>WARNING: The <code>custom-style</code> option is
|
||
<em>experimental</em>. We may change the format of the custom styles in
|
||
the future. We’re still finalizing the exact layers and customization
|
||
options that will be available.</p>
|
||
<p>Other caveats:</p>
|
||
<ul>
|
||
<li>The icon in the update dialog will always be the official icon. This
|
||
is because the update dialog is managed through a separate framework and
|
||
cannot be customized without significant effort.</li>
|
||
</ul>
|
||
</dd>
|
||
<dt><strong><code>--macos-custom-icon</code></strong></dt>
|
||
<dd>
|
||
<p>The absolute path to the custom icon file. Supported formats include
|
||
PNG, JPEG, and ICNS.</p>
|
||
<p>Defaults to <code>~/.config/ghostty/Ghostty.icns</code></p>
|
||
</dd>
|
||
<dt><strong><code>--macos-icon-frame</code></strong></dt>
|
||
<dd>
|
||
<p>The material to use for the frame of the macOS app icon.</p>
|
||
<p>Valid values:</p>
|
||
<ul>
|
||
<li><code>aluminum</code> - A brushed aluminum frame. This is the
|
||
default.</li>
|
||
<li><code>beige</code> - A classic 90’s computer beige frame.</li>
|
||
<li><code>plastic</code> - A glossy, dark plastic frame.</li>
|
||
<li><code>chrome</code> - A shiny chrome frame.</li>
|
||
</ul>
|
||
<p>Note: This configuration is required when <code>macos-icon</code> is
|
||
set to <code>custom-style</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--macos-icon-ghost-color</code></strong></dt>
|
||
<dd>
|
||
<p>The color of the ghost in the macOS app icon.</p>
|
||
<p>Note: This configuration is required when <code>macos-icon</code> is
|
||
set to <code>custom-style</code>.</p>
|
||
<p>Specified as either hex (<code>#RRGGBB</code> or <code>RRGGBB</code>)
|
||
or a named X11 color.</p>
|
||
</dd>
|
||
<dt><strong><code>--macos-icon-screen-color</code></strong></dt>
|
||
<dd>
|
||
<p>The color of the screen in the macOS app icon.</p>
|
||
<p>The screen is a linear gradient so you can specify multiple colors
|
||
that make up the gradient. Up to 64 comma-separated colors may be
|
||
specified as either hex (<code>#RRGGBB</code> or <code>RRGGBB</code>) or
|
||
as named X11 colors. The first color is the bottom of the gradient and
|
||
the last color is the top of the gradient.</p>
|
||
<p>Note: This configuration is required when <code>macos-icon</code> is
|
||
set to <code>custom-style</code>.</p>
|
||
</dd>
|
||
<dt><strong><code>--macos-shortcuts</code></strong></dt>
|
||
<dd>
|
||
<p>Whether macOS Shortcuts are allowed to control Ghostty.</p>
|
||
<p>Ghostty exposes a number of actions that allow Shortcuts to control
|
||
and interact with Ghostty. This includes creating new terminals, sending
|
||
text to terminals, running commands, invoking any keybind action,
|
||
etc.</p>
|
||
<p>This is a powerful feature but can be a security risk if a malicious
|
||
shortcut is able to be installed and executed. Therefore, this
|
||
configuration allows you to disable this feature.</p>
|
||
<p>Valid values are:</p>
|
||
<ul>
|
||
<li><p><code>ask</code> - Ask the user whether for permission. Ghostty
|
||
will remember this choice and never ask again. This is similar to other
|
||
macOS permissions such as microphone access, camera access,
|
||
etc.</p></li>
|
||
<li><p><code>allow</code> - Allow Shortcuts to control Ghostty without
|
||
asking.</p></li>
|
||
<li><p><code>deny</code> - Deny Shortcuts from controlling
|
||
Ghostty.</p></li>
|
||
</ul>
|
||
<p>Available since: 1.2.0</p>
|
||
</dd>
|
||
<dt><strong><code>--linux-cgroup</code></strong></dt>
|
||
<dd>
|
||
<p>Put every surface (tab, split, window) into a transient
|
||
<code>systemd</code> scope.</p>
|
||
<p>This allows per-surface resource management. 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 <code>systemd</code>. If <code>systemd</code>
|
||
is unavailable, cgroup initialization will fail. By default, this will
|
||
not prevent Ghostty from working (see
|
||
<code>linux-cgroup-hard-fail</code>).</p>
|
||
<p>Changing this value and reloading the config will not affect existing
|
||
surfaces.</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 <code>MemoryHigh</code> setting on the
|
||
transient <code>systemd</code> scope, which is a soft limit. You should
|
||
configure something like <code>systemd-oom</code> to handle killing
|
||
processes that have too much memory pressure.</p>
|
||
<p>Changing this value and reloading the config will not affect existing
|
||
surfaces.</p>
|
||
<p>See the <code>systemd.resource-control</code> manual page for more
|
||
information:
|
||
https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html</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 <code>TasksMax</code> setting on the
|
||
transient <code>systemd</code> scope, which is a hard limit.</p>
|
||
<p>Changing this value and reloading the config will not affect existing
|
||
surfaces.</p>
|
||
<p>See the <code>systemd.resource-control</code> manual page for more
|
||
information:
|
||
https://www.freedesktop.org/software/systemd/man/latest/systemd.resource-control.html</p>
|
||
</dd>
|
||
<dt><strong><code>--linux-cgroup-hard-fail</code></strong></dt>
|
||
<dd>
|
||
<p>If this is false, then creating a transient <code>systemd</code>
|
||
scope (for <code>linux-cgroup</code>) 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
|
||
surface creation will not fail if <code>systemd</code> APIs fail.</p>
|
||
<p>If this is true, then any transient <code>systemd</code> scope
|
||
creation failure will cause surface creation to fail.</p>
|
||
<p>Changing this value and reloading the config will not affect existing
|
||
surfaces.</p>
|
||
</dd>
|
||
<dt><strong><code>--gtk-opengl-debug</code></strong></dt>
|
||
<dd>
|
||
<p>Enable or disable GTK’s OpenGL debugging logs. The default is
|
||
<code>true</code> for debug builds, <code>false</code> for all
|
||
others.</p>
|
||
<p>Available since: 1.1.0</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>If <code>detect</code>, Ghostty will assume true (single instance)
|
||
unless one of the following scenarios is found:</p>
|
||
<ol type="1">
|
||
<li><p>TERM_PROGRAM environment variable is a non-empty value. In this
|
||
case, we assume Ghostty is being launched from a graphical terminal
|
||
session and you want a dedicated instance.</p></li>
|
||
<li><p>Any CLI arguments exist. In this case, we assume you are passing
|
||
custom Ghostty configuration. Single instance mode inherits the
|
||
configuration from when it was launched, so we must disable single
|
||
instance to load the new configuration.</p></li>
|
||
</ol>
|
||
<p>If either of these scenarios is producing a false positive, you can
|
||
set this configuration explicitly to the behavior you want.</p>
|
||
<p>The pre-1.2 option <code>desktop</code> has been deprecated. Please
|
||
replace this with <code>detect</code>.</p>
|
||
<p>The default value is <code>detect</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 none
|
||
or when running under macOS.</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, and hidden are supported. The default is top.</p>
|
||
<p>When <code>hidden</code> is set, 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>--gtk-titlebar-hide-when-maximized</code></strong></dt>
|
||
<dd>
|
||
<p>If this is <code>true</code>, the titlebar will be hidden when the
|
||
window is maximized, and shown when the titlebar is unmaximized. GTK
|
||
only.</p>
|
||
<p>Available since: 1.1.0</p>
|
||
</dd>
|
||
<dt><strong><code>--gtk-toolbar-style</code></strong></dt>
|
||
<dd>
|
||
<p>Determines the appearance of the top and bottom bars tab bar.</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>
|
||
</dd>
|
||
<dt><strong><code>--gtk-titlebar-style</code></strong></dt>
|
||
<dd>
|
||
<p>The style of the GTK titlebar. Available values are
|
||
<code>native</code> and <code>tabs</code>.</p>
|
||
<p>The <code>native</code> titlebar style is a traditional titlebar with
|
||
a title, a few buttons and window controls. A separate tab bar will show
|
||
up below the titlebar if you have multiple tabs open in the window.</p>
|
||
<p>The <code>tabs</code> titlebar merges the tab bar and the traditional
|
||
titlebar. This frees up vertical space on your screen if you use
|
||
multiple tabs. One limitation of the <code>tabs</code> titlebar is that
|
||
you cannot drag the titlebar by the titles any longer (as they are tab
|
||
titles now). Other areas of the <code>tabs</code> title bar can be used
|
||
to drag the window around.</p>
|
||
<p>The default style is <code>native</code>.</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-custom-css</code></strong></dt>
|
||
<dd>
|
||
<p>Custom CSS files to be loaded.</p>
|
||
<p>GTK CSS documentation can be found at the following links:</p>
|
||
<ul>
|
||
<li>https://docs.gtk.org/gtk4/css-overview.html - An overview of GTK
|
||
CSS.</li>
|
||
<li>https://docs.gtk.org/gtk4/css-properties.html - A comprehensive list
|
||
of supported CSS properties.</li>
|
||
</ul>
|
||
<p>Launch Ghostty with <code>env GTK_DEBUG=interactive ghostty</code> to
|
||
tweak Ghostty’s CSS in real time using the GTK Inspector. Errors in your
|
||
CSS files would also be reported in the terminal you started Ghostty
|
||
from. See https://developer.gnome.org/documentation/tools/inspector.html
|
||
for more information about the GTK Inspector.</p>
|
||
<p>This configuration can be repeated multiple times to load multiple
|
||
files. 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 (“). The
|
||
file size limit for a single stylesheet is 5MiB.</p>
|
||
<p>Available since: 1.1.0</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>--progress-style</code></strong></dt>
|
||
<dd>
|
||
<p>If <code>true</code> (default), applications running in the terminal
|
||
can show graphical progress bars using the ConEmu OSC 9;4 escape
|
||
sequence. If <code>false</code>, progress bar sequences are silently
|
||
ignored.</p>
|
||
</dd>
|
||
<dt><strong><code>--bold-color</code></strong></dt>
|
||
<dd>
|
||
<p>Modifies the color used for bold text in the terminal.</p>
|
||
<p>This can be set to a specific color, using the same format as
|
||
<code>background</code> or <code>foreground</code>
|
||
(e.g. <code>#RRGGBB</code> but other formats are also supported; see the
|
||
aforementioned documentation). If a specific color is set, this color
|
||
will always be used for the default bold text color. It will set the
|
||
rest of the bold colors to <code>bright</code>.</p>
|
||
<p>This can also be set to <code>bright</code>, which uses the bright
|
||
color palette for bold text. For example, if the text is red, then the
|
||
bold will use the bright red color. The terminal palette is set with
|
||
<code>palette</code> but can also be overridden by the terminal
|
||
application itself using escape sequences such as OSC 4. (Since Ghostty
|
||
1.2.0, the previous configuration <code>bold-is-bright</code> is
|
||
deprecated and replaced by this usage).</p>
|
||
<p>Available since Ghostty 1.2.0.</p>
|
||
</dd>
|
||
<dt><strong><code>--faint-opacity</code></strong></dt>
|
||
<dd>
|
||
<p>The opacity level (opposite of transparency) of the faint text. 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>Available since Ghostty 1.2.0.</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>--async-backend</code></strong></dt>
|
||
<dd>
|
||
<p>Configures the low-level API to use for async IO, eventing, etc.</p>
|
||
<p>Most users should leave this set to <code>auto</code>. This will
|
||
automatically detect scenarios where APIs may not be available (for
|
||
example <code>io_uring</code> on certain hardened kernels) and fall back
|
||
to a different API. However, if you want to force a specific backend for
|
||
any reason, you can set this here.</p>
|
||
<p>Based on various benchmarks, we haven’t found a statistically
|
||
significant difference between the backends with regards to memory, CPU,
|
||
or latency. The choice of backend is more about compatibility and
|
||
features.</p>
|
||
<p>Available options:</p>
|
||
<ul>
|
||
<li><code>auto</code> - Automatically choose the best backend for the
|
||
platform based on available options.</li>
|
||
<li><code>epoll</code> - Use the <code>epoll</code> API</li>
|
||
<li><code>io_uring</code> - Use the <code>io_uring</code> API</li>
|
||
</ul>
|
||
<p>If the selected backend is not available on the platform, Ghostty
|
||
will fall back to an automatically chosen backend that is available.</p>
|
||
<p>Changing this value requires a full application restart to take
|
||
effect.</p>
|
||
<p>This is only supported on Linux, since this is the only platform
|
||
where we have multiple options. On macOS, we always use
|
||
<code>kqueue</code>.</p>
|
||
<p>Available since: 1.2.0</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>If unset, we defer to Sparkle’s default behavior, which respects the
|
||
preference stored in the standard user defaults
|
||
(<code>defaults(1)</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.ghostty</em></dt>
|
||
<dd>
|
||
<p>Location of the default configuration file.</p>
|
||
</dd>
|
||
<dt><em>$HOME/Library/Application
|
||
Support/com.mitchellh.ghostty/config.ghostty</em></dt>
|
||
<dd>
|
||
<p><strong>On macOS</strong>, location of the default configuration
|
||
file. This location takes precedence over the XDG environment
|
||
locations.</p>
|
||
</dd>
|
||
<dt><em>$LOCALAPPDATA/ghostty/config.ghostty</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>$HOME/Library/Application
|
||
Support/com.mitchellh.ghostty</strong></dt>
|
||
<dd>
|
||
<p><strong>MACOS ONLY</strong> default location for configuration files.
|
||
This location takes precedence over the XDG environment locations.</p>
|
||
</dd>
|
||
<dt><strong>LOCALAPPDATA</strong></dt>
|
||
<dd>
|
||
<p><strong>WINDOWS ONLY:</strong> alternate location to search for
|
||
configuration files.</p>
|
||
</dd>
|
||
<dt><strong>GHOSTTY_LOG</strong></dt>
|
||
<dd>
|
||
<p>The <code>GHOSTTY_LOG</code> environment variable can be used to
|
||
control which destinations receive logs. Ghostty currently defines two
|
||
destinations:</p>
|
||
</dd>
|
||
<dd>
|
||
<ul>
|
||
<li><code>stderr</code> - logging to <code>stderr</code>.</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
<ul>
|
||
<li><code>macos</code> - logging to macOS’s unified log (has no effect
|
||
on non-macOS platforms).</li>
|
||
</ul>
|
||
</dd>
|
||
<dd>
|
||
<p>Combine values with a comma to enable multiple destinations. Prefix a
|
||
destination with <code>no-</code> to disable it. Enabling and disabling
|
||
destinations can be done at the same time. Setting
|
||
<code>GHOSTTY_LOG</code> to <code>true</code> will enable all
|
||
destinations. Setting <code>GHOSTTY_LOG</code> to <code>false</code>
|
||
will disable all destinations.</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> Ghostty contributors <a
|
||
href="https://github.com/ghostty-org/ghostty/graphs/contributors"
|
||
class="uri">https://github.com/ghostty-org/ghostty/graphs/contributors</a></p>
|
||
<h1 id="see-also">SEE ALSO</h1>
|
||
<p><strong>ghostty(5)</strong></p>
|
||
</body>
|
||
</html>
|