claude-app-builder-4-mac/ghostty-template/Ghostty.app/Contents/Resources/man/man1/ghostty.1

.\" Automatically generated by Pandoc 3.7.0.2
.\"
.TH "GHOSTTY" "1" "" "Version 1.3.1" "Ghostty terminal emulator"
.SH NAME
\f[B]ghostty\f[R] \- Ghostty terminal emulator
.SH DESCRIPTION
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.
.PP
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.
.PP
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.
.SH COMMAND LINE ACTIONS
.TP
\f[B]\f[CB]\-\-version\f[B]\f[R]
The \f[CR]version\f[R] command is used to display information about
Ghostty.
Recognized as either \f[CR]+version\f[R] or \f[CR]\-\-version\f[R].
.TP
\f[B]\f[CB]\-\-help\f[B]\f[R]
The \f[CR]help\f[R] command shows general help about Ghostty.
Recognized as either
\f[CR]\-h,\f[R]\(enhelp\f[CR], or like other actions\f[R]+help\(ga.
.RS
.PP
You can also specify \f[CR]\-\-help\f[R] or \f[CR]\-h\f[R] along with
any action such as \f[CR]+list\-themes\f[R] to see help for a specific
action.
.RE
.TP
\f[B]\f[CB]+list\-fonts\f[B]\f[R]
The \f[CR]list\-fonts\f[R] 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.
.RS
.PP
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 \f[CR]\-\-family\f[R], the sorting will
be disabled and the results instead will be shown in the same priority
order Ghostty would use to pick a font.
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-bold\f[R]: Filter results to specific bold styles.
It is not guaranteed that only those styles are returned.
They are only prioritized.
.IP \(bu 2
\f[CR]\-\-italic\f[R]: Filter results to specific italic styles.
It is not guaranteed that only those styles are returned.
They are only prioritized.
.IP \(bu 2
\f[CR]\-\-style\f[R]: 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.
.IP \(bu 2
\f[CR]\-\-family\f[R]: Filter results to a specific font family.
The family handling is identical to the \f[CR]font\-family\f[R] set of
Ghostty configuration values, so this can be used to debug why your
desired font may not be loading.
.RE
.TP
\f[B]\f[CB]+list\-keybinds\f[B]\f[R]
The \f[CR]list\-keybinds\f[R] command is used to list all the available
keybinds for Ghostty.
.RS
.PP
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\(cqt any changes to the
keybinds it will print out the default ones configured for Ghostty
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-default\f[R]: will print out all the default keybinds
.IP \(bu 2
\f[CR]\-\-docs\f[R]: currently does nothing, intended to print out
documentation about the action associated with the keybinds
.IP \(bu 2
\f[CR]\-\-plain\f[R]: will disable formatting and make the output more
friendly for Unix tooling.
This is default when not printing to a tty.
.RE
.TP
\f[B]\f[CB]+list\-themes\f[B]\f[R]
The \f[CR]list\-themes\f[R] command is used to preview or list all the
available themes for Ghostty.
.RS
.PP
If this command is run from a TTY, a TUI preview of the themes will be
shown.
While in the preview, \f[CR]F1\f[R] will bring up a help screen and
\f[CR]ESC\f[R] will exit the preview.
Other keys that can be used to navigate the preview are listed in the
help screen.
.PP
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 \f[CR]\-\-plain\f[R] CLI flag.
.PP
Two different directories will be searched for themes.
.PP
The first directory is the \f[CR]themes\f[R] subdirectory of your
Ghostty configuration directory.
This is \f[CR]$XDG_CONFIG_HOME/ghostty/themes\f[R] or
\f[CR]\(ti/.config/ghostty/themes\f[R].
.PP
The second directory is the \f[CR]themes\f[R] 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
\f[CR]Ghostty.app/Contents/Resources/ghostty/themes\f[R].
On Linux, this directory is the \f[CR]share/ghostty/themes\f[R]
(wherever you installed the Ghostty \(lqshare\(rq directory).
If you\(cqre running Ghostty from the source, this is the
\f[CR]zig\-out/share/ghostty/themes\f[R] directory.
.PP
You can also set the \f[CR]GHOSTTY_RESOURCES_DIR\f[R] environment
variable to point to the resources directory.
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-path\f[R]: Show the full path to the theme.
.IP \(bu 2
\f[CR]\-\-plain\f[R]: Force a plain listing of themes.
.IP \(bu 2
\f[CR]\-\-color\f[R]: Specify the color scheme of the themes included in
the list.
This can be \f[CR]dark\f[R], \f[CR]light\f[R], or \f[CR]all\f[R].
The default is \f[CR]all\f[R].
.RE
.TP
\f[B]\f[CB]+list\-colors\f[B]\f[R]
The \f[CR]list\-colors\f[R] command is used to list all the named RGB
colors in Ghostty.
.RS
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-plain\f[R]: will disable formatting and make the output more
friendly for Unix tooling.
This is default when not printing to a tty.
.RE
.TP
\f[B]\f[CB]+list\-actions\f[B]\f[R]
The \f[CR]list\-actions\f[R] command is used to list all the available
keybind actions for Ghostty.
These are distinct from the CLI Actions which can be listed via
\f[CR]+help\f[R]
.RS
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-docs\f[R]: will print out the documentation for each action.
.RE
.TP
\f[B]\f[CB]+ssh\-cache\f[B]\f[R]
Manage the SSH terminfo cache for automatic remote host setup.
.RS
.PP
When SSH integration is enabled with
\f[CR]shell\-integration\-features = ssh\-terminfo\f[R], Ghostty
automatically installs its terminfo on remote hosts.
This command manages the cache of successful installations to avoid
redundant uploads.
.PP
The cache stores hostnames (or user\(athostname combinations) along with
timestamps.
Entries older than the expiration period are automatically removed
during cache operations.
By default, entries never expire.
.PP
Only one of \f[CR]\-\-clear\f[R], \f[CR]\-\-add\f[R],
\f[CR]\-\-remove\f[R], or \f[CR]\-\-host\f[R] can be specified.
If multiple are specified, one of the actions will be executed but it
isn\(cqt guaranteed which one.
This is entirely unsafe so you should split multiple actions into
separate commands.
.PP
Examples: ghostty +ssh\-cache # List all cached hosts ghostty
+ssh\-cache \(enhost=example.com # Check if host is cached ghostty
+ssh\-cache \(enadd=example.com # Manually add host to cache ghostty
+ssh\-cache \(enadd=user\(atexample.com # Add user\(athost combination
ghostty +ssh\-cache \(enremove=example.com # Remove host from cache
ghostty +ssh\-cache \(enclear # Clear entire cache ghostty +ssh\-cache
\(enexpire\-days=30 # Set custom expiration period
.RE
.TP
\f[B]\f[CB]+edit\-config\f[B]\f[R]
The \f[CR]edit\-config\f[R] command opens the Ghostty configuration file
in the editor specified by the \f[CR]$VISUAL\f[R] or \f[CR]$EDITOR\f[R]
environment variables.
.RS
.PP
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\(cqt capable of
this yet.
.PP
The filepath opened is the default user\-specific configuration file,
which is typically located at
\f[CR]$XDG_CONFIG_HOME/ghostty/config.ghostty\f[R].
On macOS, this may also be located at
\f[CR]\(ti/Library/Application Support/com.mitchellh.ghostty/config.ghostty\f[R].
On macOS, whichever path exists and is non\-empty will be prioritized,
prioritizing the Application Support directory if neither are
non\-empty.
.PP
This command prefers the \f[CR]$VISUAL\f[R] environment variable over
\f[CR]$EDITOR\f[R], if both are set.
If neither are set, it will print an error and exit.
.RE
.TP
\f[B]\f[CB]+show\-config\f[B]\f[R]
The \f[CR]show\-config\f[R] command shows the current configuration in a
valid Ghostty configuration file format.
.RS
.PP
When executed without any arguments this will output the current
configuration that is different from the default configuration.
If you\(cqre using the default configuration this will output nothing.
.PP
If you are a new user and want to see all available options with
documentation, run
\f[CR]ghostty +show\-config \-\-default \-\-docs\f[R].
.PP
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.
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-default\f[R]: Show the default configuration instead of
loading the user configuration.
.IP \(bu 2
\f[CR]\-\-changes\-only\f[R]: Only show the options that have been
changed from the default.
This has no effect if \f[CR]\-\-default\f[R] is specified.
.IP \(bu 2
\f[CR]\-\-docs\f[R]: 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 \f[CR]\-\-default\f[R].
.RE
.TP
\f[B]\f[CB]+validate\-config\f[B]\f[R]
The \f[CR]validate\-config\f[R] command is used to validate a Ghostty
config file.
.RS
.PP
When executed without any arguments, this will load the config from the
default location.
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-config\-file\f[R]: can be passed to validate a specific target
config file in a non\-default location
.RE
.TP
\f[B]\f[CB]+show\-face\f[B]\f[R]
The \f[CR]show\-face\f[R] 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.
.RS
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-cp\f[R]: Find the face for a single codepoint.
The codepoint may be specified in decimal (\f[CR]\-\-cp=65\f[R]),
hexadecimal (\f[CR]\-\-cp=0x41\f[R]), octal (\f[CR]\-\-cp=0o101\f[R]),
or binary (\f[CR]\-\-cp=0b1000001\f[R]).
.IP \(bu 2
\f[CR]\-\-string\f[R]: Find the face for all of the codepoints in a
string.
The string must be a valid UTF\-8 sequence.
.IP \(bu 2
\f[CR]\-\-style\f[R]: Search for a specific style.
Valid options are \f[CR]regular\f[R], \f[CR]bold\f[R],
\f[CR]italic\f[R], and \f[CR]bold_italic\f[R].
.IP \(bu 2
\f[CR]\-\-presentation\f[R]: If set, force searching for a specific
presentation style.
Valid options are \f[CR]text\f[R] and \f[CR]emoji\f[R].
If unset, the presentation style of a codepoint will be inferred from
the Unicode standard.
.RE
.TP
\f[B]\f[CB]+crash\-report\f[B]\f[R]
The \f[CR]crash\-report\f[R] command is used to inspect and send crash
reports.
.RS
.PP
When executed without any arguments, this will list existing crash
reports.
.PP
This command currently only supports listing crash reports.
Viewing and sending crash reports is unimplemented and will be added in
the future.
.RE
.TP
\f[B]\f[CB]+boo\f[B]\f[R]
The \f[CR]boo\f[R] command is used to display the animation from the
Ghostty website in the terminal
.TP
\f[B]\f[CB]+new\-window\f[B]\f[R]
The \f[CR]new\-window\f[R] will use native platform IPC to open up a new
window in a running instance of Ghostty.
.RS
.PP
If the \f[CR]\-\-class\f[R] flag is not set, the \f[CR]new\-window\f[R]
command will try and connect to a running instance of Ghostty based on
what optimizations the Ghostty CLI was compiled with.
Otherwise the \f[CR]new\-window\f[R] command will try and contact a
running Ghostty instance that was configured with the same
\f[CR]class\f[R] as was given on the command line.
.PP
All of the arguments after the \f[CR]+new\-window\f[R] argument (except
for the \f[CR]\-\-class\f[R] 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 \f[CR]\-\-working\-directory\f[R],
\f[CR]\-\-command\f[R], and \f[CR]\-\-title\f[R] are supported.
\f[CR]\-e\f[R] will also work as an alias for \f[CR]\-\-command\f[R],
except that if \f[CR]\-e\f[R] 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.
.PP
If \f[CR]\-\-working\-directory\f[R] is found on the command line and is
a relative path (i.e.\ doesn\(cqt start with \f[CR]/\f[R]) it will be
resolved to an absolute path relative to the current working directory
that the \f[CR]ghostty +new\-window\f[R] command is run from.
\f[CR]\(ti/\f[R] prefixes will also be expanded to the user\(cqs home
directory.
.PP
If \f[CR]\-\-working\-directory\f[R] is \f[I]not\f[R] found on the
command line, the working directory that \f[CR]ghostty +new\-window\f[R]
is run from will be passed to Ghostty.
.PP
GTK uses an application ID to identify instances of applications.
If Ghostty is compiled with release optimizations, the default
application ID will be \f[CR]com.mitchellh.ghostty\f[R].
If Ghostty is compiled with debug optimizations, the default application
ID will be \f[CR]com.mitchellh.ghostty\-debug\f[R].
The \f[CR]class\f[R] configuration entry can be used to set up a custom
application ID.
The class name must follow the requirements defined \c
.UR https://docs.gtk.org/gio/type_func.Application.id_is_valid.html
in the GTK documentation
.UE \c
\ or it will be ignored and Ghostty will use the default as defined
above.
.PP
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.
.PP
Only supported on GTK.
.PP
Flags:
.IP \(bu 2
\f[CR]\-\-class=<class>\f[R]: If set, open up a new window in a custom
instance of Ghostty.
The class must be a valid GTK application ID.
.IP \(bu 2
\f[CR]\-\-command\f[R]: The command to be executed in the first surface
of the new window.
.IP \(bu 2
\f[CR]\-\-working\-directory=<directory>\f[R]: The working directory to
pass to Ghostty.
.IP \(bu 2
\f[CR]\-\-title\f[R]: A title that will override the title of the first
surface in the new window.
The title override may be edited or removed later.
.IP \(bu 2
\f[CR]\-e\f[R]: 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.
.PP
Available since: 1.2.0
.RE
.SH CONFIGURATION OPTIONS
.TP
\f[B]\f[CB]\-\-language\f[B]\f[R]
Set Ghostty\(cqs graphical user interface language to a language other
than the system default language.
For example:
.RS
.IP
.EX
language = de
.EE
.PP
will force the strings in Ghostty\(cqs graphical user interface to be in
German rather than the system default.
.PP
This will not affect the language used by programs run \f[I]within\f[R]
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.
.PP
Warning: This setting cannot be reloaded at runtime.
To change the language you must fully restart Ghostty.
.PP
GTK only.
Available since 1.3.0.
.RE
.TP
\f[B]\f[CB]\-\-font\-family\f[B]\f[R]
The font families to use.
.RS
.PP
You can generate the list of valid values using the CLI:
.IP
.EX
ghostty +list\-fonts
.EE
.PP
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.
.PP
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.
.PP
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 \f[CR]font\-family\-bold = FooBar\f[R] and
\(lqFooBar\(rq cannot be found, Ghostty will use whatever font is set
for \f[CR]font\-family\f[R] for the bold style.
.PP
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
\f[CR]font\-style\f[R] configurations as documented below.
.PP
You can disable styles completely by using the \f[CR]font\-style\f[R]
set of configurations.
See the documentation for \f[CR]font\-style\f[R] for more information.
.PP
If you want to overwrite a previous set value rather than append a
fallback, specify the value as \f[CR]\(dq\(dq\f[R] (empty string) to
reset the list and then set the new values.
For example:
.IP
.EX
font\-family = \(dq\(dq
font\-family = \(dqMy Favorite Font\(dq
.EE
.PP
Setting any of these as CLI arguments will automatically clear the
values set in configuration files so you don\(cqt need to specify
\f[CR]\-\-font\-family=\(dq\(dq\f[R] 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.
.RE
.PP
\f[B]\f[CB]\-\-font\-family\-bold\f[B]\f[R]
.PP
\f[B]\f[CB]\-\-font\-family\-italic\f[B]\f[R]
.PP
\f[B]\f[CB]\-\-font\-family\-bold\-italic\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-font\-style\f[B]\f[R]
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, \(lqIosevka Heavy\(rq has a style of \(lqHeavy\(rq.
.RS
.PP
You can also use these fields to completely disable a font style.
If you set the value of the configuration below to literal
\f[CR]false\f[R] 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.
.PP
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\(cqre disabling the font style.
.RE
.PP
\f[B]\f[CB]\-\-font\-style\-bold\f[B]\f[R]
.PP
\f[B]\f[CB]\-\-font\-style\-italic\f[B]\f[R]
.PP
\f[B]\f[CB]\-\-font\-style\-bold\-italic\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-font\-synthetic\-style\f[B]\f[R]
Control whether Ghostty should synthesize a style if the requested style
is not available in the specified font\-family.
.RS
.PP
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.
.PP
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.
.PP
Set this to \(lqfalse\(rq or \(lqtrue\(rq to disable or enable synthetic
styles completely.
You can disable specific styles using \(lqno\-bold\(rq,
\(lqno\-italic\(rq, and \(lqno\-bold\-italic\(rq.
You can disable multiple styles by separating them with a comma.
For example, \(lqno\-bold,no\-italic\(rq.
.PP
Available style keys are: \f[CR]bold\f[R], \f[CR]italic\f[R],
\f[CR]bold\-italic\f[R].
.PP
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.
.PP
Warning: An easy mistake is to disable \f[CR]bold\f[R] or
\f[CR]italic\f[R] but not \f[CR]bold\-italic\f[R].
Disabling only \f[CR]bold\f[R] or \f[CR]italic\f[R] will NOT disable
either in the \f[CR]bold\-italic\f[R] style.
If you want to disable \f[CR]bold\-italic\f[R], you must explicitly
disable it.
You cannot partially disable \f[CR]bold\-italic\f[R].
.PP
By default, synthetic styles are enabled.
.RE
.TP
\f[B]\f[CB]\-\-font\-feature\f[B]\f[R]
Apply a font feature.
To enable multiple font features you can repeat this multiple times or
use a comma\-separated list of feature settings.
.RS
.PP
The syntax for feature settings is as follows, where \f[CR]feat\f[R] is
a feature:
.IP \(bu 2
Enable features with e.g.\ \f[CR]feat\f[R], \f[CR]+feat\f[R],
\f[CR]feat on\f[R], \f[CR]feat=1\f[R].
.IP \(bu 2
Disabled features with e.g.\ \f[CR]\-feat\f[R], \f[CR]feat off\f[R],
\f[CR]feat=0\f[R].
.IP \(bu 2
Set a feature value with e.g.\ \f[CR]feat=2\f[R], \f[CR]feat = 3\f[R],
\f[CR]feat 4\f[R].
.IP \(bu 2
Feature names may be wrapped in quotes, meaning this config should be
syntactically compatible with the \f[CR]font\-feature\-settings\f[R] CSS
property.
.PP
The syntax is fairly loose, but invalid settings will be silently
ignored.
.PP
The font feature will apply to all fonts rendered by Ghostty.
A future enhancement will allow targeting specific faces.
.PP
To disable programming ligatures, use \f[CR]\-calt\f[R] 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 \c
.UR https://fontdrop.info
fontdrop.info
.UE \c
\&.
.PP
To generally disable most ligatures, use
\f[CR]\-calt, \-liga, \-dlig\f[R].
.RE
.TP
\f[B]\f[CB]\-\-font\-size\f[B]\f[R]
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.
.RS
.PP
For example, 13.5pt \(at 2px/pt = 27px
.PP
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.
.PP
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).
.RE
.TP
\f[B]\f[CB]\-\-font\-variation\f[B]\f[R]
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
\f[CR]\-VF.ttf\f[R] or \f[CR]\-VF.otf\f[R] 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.
.RS
.PP
The format of this is \f[CR]id=value\f[R] where \f[CR]id\f[R] is the
axis identifier.
An axis identifier is always a 4 character string, such as
\f[CR]wght\f[R].
To get the list of supported axes, look at your font documentation or
use a font inspection tool.
.PP
Invalid ids and values are usually ignored.
For example, if a font only supports weights from 100 to 700, setting
\f[CR]wght=800\f[R] will do nothing (it will not be clamped to 700).
You must consult your font\(cqs documentation to see what values are
supported.
.PP
Common axes are: \f[CR]wght\f[R] (weight), \f[CR]slnt\f[R] (slant),
\f[CR]ital\f[R] (italic), \f[CR]opsz\f[R] (optical size),
\f[CR]wdth\f[R] (width), \f[CR]GRAD\f[R] (gradient), etc.
.RE
.PP
\f[B]\f[CB]\-\-font\-variation\-bold\f[B]\f[R]
.PP
\f[B]\f[CB]\-\-font\-variation\-italic\f[B]\f[R]
.PP
\f[B]\f[CB]\-\-font\-variation\-bold\-italic\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-font\-codepoint\-map\f[B]\f[R]
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.
.RS
.PP
The syntax is \f[CR]codepoint=fontname\f[R] where \f[CR]codepoint\f[R]
is either a single codepoint or a range.
Codepoints must be specified as full Unicode hex values, such as
\f[CR]U+ABCD\f[R].
Codepoints ranges are specified as \f[CR]U+ABCD\-U+DEFG\f[R].
You can specify multiple ranges for the same font separated by commas,
such as \f[CR]U+ABCD\-U+DEFG,U+1234\-U+5678=fontname\f[R].
The font name is the same value as you would use for
\f[CR]font\-family\f[R].
.PP
This configuration can be repeated multiple times to specify multiple
codepoint mappings.
.PP
Changing this configuration at runtime will only affect new terminals,
i.e.\ new windows, tabs, etc.
.RE
.TP
\f[B]\f[CB]\-\-clipboard\-codepoint\-map\f[B]\f[R]
Map specific Unicode codepoints to replacement values when copying text
to clipboard.
.RS
.PP
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.
.PP
The syntax is similar to \f[CR]font\-codepoint\-map\f[R]: \- Single
codepoint: \f[CR]U+1234=U+ABCD\f[R] or
\f[CR]U+1234=replacement_text\f[R] \- Codepoint range:
\f[CR]U+1234\-U+5678=U+ABCD\f[R]
.PP
Examples: \- \f[CR]clipboard\-codepoint\-map = U+2500=U+002D\f[R] (box
drawing horizontal → hyphen) \-
\f[CR]clipboard\-codepoint\-map = U+2502=U+007C\f[R] (box drawing
vertical → pipe) \- \f[CR]clipboard\-codepoint\-map = U+03A3=SUM\f[R]
(Greek sigma → \(lqSUM\(rq)
.PP
This configuration can be repeated multiple times to specify multiple
mappings.
Later entries take priority over earlier ones for overlapping ranges.
.PP
Note: This only applies to text copying operations, not URL copying.
.RE
.TP
\f[B]\f[CB]\-\-font\-thicken\f[B]\f[R]
Draw fonts with a thicker stroke, if supported.
This is currently only supported on macOS.
.TP
\f[B]\f[CB]\-\-font\-thicken\-strength\f[B]\f[R]
Strength of thickening when \f[CR]font\-thicken\f[R] is enabled.
.RS
.PP
Valid values are integers between \f[CR]0\f[R] and \f[CR]255\f[R].
\f[CR]0\f[R] does not correspond to \f[I]no\f[R] thickening, rather it
corresponds to the lightest available thickening.
.PP
Has no effect when \f[CR]font\-thicken\f[R] is set to \f[CR]false\f[R].
.PP
This is currently only supported on macOS.
.RE
.TP
\f[B]\f[CB]\-\-font\-shaping\-break\f[B]\f[R]
Locations to break font shaping into multiple runs.
.RS
.PP
A \(lqrun\(rq is a contiguous segment of text that is shaped together.
\(lqShaping\(rq 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 \(lq!=\(rq into a single glyph, then
it must see \(lq!\(rq and \(lq=\(rq next to each other in a single run.
When a run is broken, the text is shaped separately.
To continue our example, if \(lq!\(rq is at the end of one run and
\(lq=\(rq is at the start of the next run, then the ligature will not be
formed.
.PP
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.
.PP
Combine values with a comma to set multiple options.
Prefix an option with \(lqno\-\(rq to disable it.
Enabling and disabling options can be done at the same time.
.PP
Available options:
.IP \(bu 2
\f[CR]cursor\f[R] \- Break runs under the cursor.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-alpha\-blending\f[B]\f[R]
What color space to use when performing alpha blending.
.RS
.PP
This affects the appearance of text and of any images with transparency.
Additionally, custom shaders will receive colors in the configured
space.
.PP
On macOS the default is \f[CR]native\f[R], on all other platforms the
default is \f[CR]linear\-corrected\f[R].
.PP
Valid values:
.IP \(bu 2
\f[CR]native\f[R] \- Perform alpha blending in the native color space
for the OS.
On macOS this corresponds to Display P3, and on Linux it\(cqs sRGB.
.IP \(bu 2
\f[CR]linear\f[R] \- 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 \(lqgamma correction\(rq.
.IP \(bu 2
\f[CR]linear\-corrected\f[R] \- Same as \f[CR]linear\f[R], but with a
correction step applied for text that makes it look nearly or completely
identical to \f[CR]native\f[R], but without any of the darkening
artifacts.
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-adjust\-cell\-width\f[B]\f[R]
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.
.RS
.PP
For example, a value of \f[CR]1\f[R] increases the value by 1; it does
not set it to literally 1.
A value of \f[CR]20%\f[R] increases the value by 20%.
And so on.
.PP
There is little to no validation on these values so the wrong values
(e.g.
\f[CR]\-100%\f[R]) can cause the terminal to be unusable.
Use with caution and reason.
.PP
Some values are clamped to minimum or maximum values.
This can make it appear that certain values are ignored.
For example, many \f[CR]*\-thickness\f[R] adjustments cannot go below
1px.
.PP
\f[CR]adjust\-cell\-height\f[R] has some additional behaviors to
describe:
.IP \(bu 2
The font will be centered vertically in the cell.
.IP \(bu 2
The cursor will remain the same size as the font, but may be adjusted
separately with \f[CR]adjust\-cursor\-height\f[R].
.IP \(bu 2
Powerline glyphs will be adjusted along with the cell height so that
things like status lines continue to look aligned.
.RE
.PP
\f[B]\f[CB]\-\-adjust\-cell\-height\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-adjust\-font\-baseline\f[B]\f[R]
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 \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-underline\-position\f[B]\f[R]
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 \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-underline\-thickness\f[B]\f[R]
Thickness in pixels of the underline.
See the notes about adjustments in \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-strikethrough\-position\f[B]\f[R]
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 \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-strikethrough\-thickness\f[B]\f[R]
Thickness in pixels or percentage adjustment of the strikethrough.
See the notes about adjustments in \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-overline\-position\f[B]\f[R]
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 \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-overline\-thickness\f[B]\f[R]
Thickness in pixels or percentage adjustment of the overline.
See the notes about adjustments in \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-cursor\-thickness\f[B]\f[R]
Thickness in pixels or percentage adjustment of the bar cursor and
outlined rect cursor.
See the notes about adjustments in \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-cursor\-height\f[B]\f[R]
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 \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-box\-thickness\f[B]\f[R]
Thickness in pixels or percentage adjustment of box drawing characters.
See the notes about adjustments in \f[CR]adjust\-cell\-width\f[R].
.TP
\f[B]\f[CB]\-\-adjust\-icon\-height\f[B]\f[R]
Height in pixels or percentage adjustment of maximum height for nerd
font icons.
.RS
.PP
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.
.PP
Certain icons designed for box drawing and terminal graphics, such as
Powerline symbols, are not affected by this option.
.PP
See the notes about adjustments in \f[CR]adjust\-cell\-width\f[R].
.PP
Available in: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-grapheme\-width\-method\f[B]\f[R]
The method to use for calculating the cell width of a grapheme cluster.
The default value is \f[CR]unicode\f[R] 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 \f[CR]wcswidth\f[R].
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]legacy\f[R] \- 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.
.RS 2
.PP
This is called \(lqlegacy\(rq 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 \f[CR]wcswidth\f[R] now or in
the future.
.RE
.IP \(bu 2
\f[CR]unicode\f[R] \- Use the Unicode standard to determine grapheme
width.
.PP
If a running program explicitly enables terminal mode 2027, then
\f[CR]unicode\f[R] width will be forced regardless of this
configuration.
When mode 2027 is reset, this configuration will be used again.
.PP
This configuration can be changed at runtime but will not affect
existing terminals.
Only new terminals will use the new configuration.
.RE
.TP
\f[B]\f[CB]\-\-freetype\-load\-flags\f[B]\f[R]
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 \f[CR]no\-\f[R] then it is disabled.
If you omit a flag, its default value is used, so you must explicitly
disable flags you don\(cqt want.
You can also use \f[CR]true\f[R] or \f[CR]false\f[R] to turn all flags
on or off.
.RS
.PP
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.
.PP
Available flags:
.IP \(bu 2
\f[CR]hinting\f[R] \- Enable or disable hinting.
Enabled by default.
.IP \(bu 2
\f[CR]force\-autohint\f[R] \- Always use the freetype auto\-hinter
instead of the font\(cqs native hinter.
Disabled by default.
.IP \(bu 2
\f[CR]monochrome\f[R] \- Instructs renderer to use 1\-bit monochrome
rendering.
This will disable anti\-aliasing, and probably not look very good unless
you\(cqre using a pixel font.
Disabled by default.
.IP \(bu 2
\f[CR]autohint\f[R] \- Enable the freetype auto\-hinter.
Enabled by default.
.IP \(bu 2
\f[CR]light\f[R] \- Use a light hinting style, better preserving glyph
shapes.
This is the most common setting in GTK apps and therefore also
Ghostty\(cqs default.
This has no effect if \f[CR]monochrome\f[R] is enabled.
Enabled by default.
.PP
Example: \f[CR]hinting\f[R], \f[CR]no\-hinting\f[R],
\f[CR]force\-autohint\f[R], \f[CR]no\-force\-autohint\f[R]
.RE
.TP
\f[B]\f[CB]\-\-theme\f[B]\f[R]
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.
.RS
.PP
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.
.PP
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.
.PP
The first directory is the \f[CR]themes\f[R] subdirectory of your
Ghostty configuration directory.
This is \f[CR]$XDG_CONFIG_HOME/ghostty/themes\f[R] or
\f[CR]\(ti/.config/ghostty/themes\f[R].
.PP
The second directory is the \f[CR]themes\f[R] 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
\f[CR]Ghostty.app/Contents/Resources/ghostty/themes\f[R] directory.
On Linux, this list is in the \f[CR]share/ghostty/themes\f[R] directory
(wherever you installed the Ghostty \(lqshare\(rq directory.
.PP
To see a list of available themes, run \f[CR]ghostty +list\-themes\f[R].
.PP
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.
.PP
Some options cannot be set within theme files.
The reason these are not supported should be self\-evident.
A theme file cannot set \f[CR]theme\f[R] or \f[CR]config\-file\f[R].
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.
.PP
Any additional colors specified via background, foreground, palette,
etc.
will override the colors specified in the theme.
.PP
To specify a different theme for light and dark mode, use the following
syntax: \f[CR]light:theme\-name,dark:theme\-name\f[R].
For example: \f[CR]light:Rose Pine Dawn,dark:Rose Pine\f[R].
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.
.PP
There are some known bugs with light/dark mode theming.
These will be fixed in a future update:
.IP \(bu 2
macOS: titlebar tabs style is not updated when switching themes.
.RE
.TP
\f[B]\f[CB]\-\-background\f[B]\f[R]
Background color for the window.
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
.TP
\f[B]\f[CB]\-\-foreground\f[B]\f[R]
Foreground color for the window.
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
.TP
\f[B]\f[CB]\-\-background\-image\f[B]\f[R]
Background image for the terminal.
.RS
.PP
This should be a path to a PNG or JPEG file, other image formats are not
yet supported.
.PP
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.
.PP
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.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-background\-image\-opacity\f[B]\f[R]
Background image opacity.
.RS
.PP
This is relative to the value of \f[CR]background\-opacity\f[R].
.PP
A value of \f[CR]1.0\f[R] (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
\f[CR]background\-opacity\f[R].
.PP
A value less than \f[CR]1.0\f[R] will result in the background image
being mixed with the general background color before the combined result
is adjusted to the configured \f[CR]background\-opacity\f[R].
.PP
A value greater than \f[CR]1.0\f[R] will result in the background image
having a higher opacity than the general background color.
For instance, if the configured \f[CR]background\-opacity\f[R] is
\f[CR]0.5\f[R] and \f[CR]background\-image\-opacity\f[R] is set to
\f[CR]1.5\f[R], then the final opacity of the background image will be
\f[CR]0.5 * 1.5 = 0.75\f[R].
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-background\-image\-position\f[B]\f[R]
Background image position.
.RS
.PP
Valid values are: * \f[CR]top\-left\f[R] * \f[CR]top\-center\f[R] *
\f[CR]top\-right\f[R] * \f[CR]center\-left\f[R] * \f[CR]center\f[R] *
\f[CR]center\-right\f[R] * \f[CR]bottom\-left\f[R] *
\f[CR]bottom\-center\f[R] * \f[CR]bottom\-right\f[R]
.PP
The default value is \f[CR]center\f[R].
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-background\-image\-fit\f[B]\f[R]
Background image fit.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]contain\f[R]
.RS 2
.PP
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.
.RE
.IP \(bu 2
\f[CR]cover\f[R]
.RS 2
.PP
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.
.RE
.IP \(bu 2
\f[CR]stretch\f[R]
.RS 2
.PP
Stretch the background image to the full size of the terminal, without
preserving the aspect ratio.
.RE
.IP \(bu 2
\f[CR]none\f[R]
.RS 2
.PP
Don\(cqt scale the background image.
.RE
.PP
The default value is \f[CR]contain\f[R].
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-background\-image\-repeat\f[B]\f[R]
Whether to repeat the background image or not.
.RS
.PP
If this is set to true, the background image will be repeated if there
would otherwise be blank space around it because it doesn\(cqt
completely fill the terminal area.
.PP
The default value is \f[CR]false\f[R].
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-selection\-foreground\f[B]\f[R]
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 (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
Since version 1.2.0, this can also be set to \f[CR]cell\-foreground\f[R]
to match the cell foreground color, or \f[CR]cell\-background\f[R] to
match the cell background color.
.PP
\f[B]\f[CB]\-\-selection\-background\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-selection\-clear\-on\-typing\f[B]\f[R]
Whether to clear selected text when typing.
This defaults to \f[CR]true\f[R].
This is typical behavior for most terminal emulators as well as text
input fields.
If you set this to \f[CR]false\f[R], then the selected text will not be
cleared when typing.
.RS
.PP
\(lqTyping\(rq 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).
.PP
If this is \f[CR]false\f[R], then the selection can still be manually
cleared by clicking once or by pressing \f[CR]escape\f[R].
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-selection\-clear\-on\-copy\f[B]\f[R]
Whether to clear selected text after copying.
This defaults to \f[CR]false\f[R].
.RS
.PP
When set to \f[CR]true\f[R], the selection will be automatically cleared
after any copy operation that invokes the \f[CR]copy_to_clipboard\f[R]
keyboard binding.
Importantly, this will not clear the selection if the copy operation was
invoked via \f[CR]copy\-on\-select\f[R].
.PP
When set to \f[CR]false\f[R], the selection remains visible after
copying, allowing to see what was copied and potentially perform
additional operations on the same selection.
.RE
.TP
\f[B]\f[CB]\-\-selection\-word\-chars\f[B]\f[R]
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.
.RS
.PP
This is similar to the \f[CR]WORDCHARS\f[R] 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.
.PP
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.
.PP
The null character (U+0000) is always treated as a boundary and does not
need to be included in this configuration.
.PP
Default: \f[CR]\(rst\(aq\(dq│\(ga|:;,()[]{}<>$\f[R]
.PP
To add or remove specific characters, you can set this to a custom
value.
For example, to treat semicolons as part of words:
.IP
.EX
selection\-word\-chars = \(dq \(rst\(aq\(rs\(dq│\(ga|:,()[]{}<>$\(dq
.EE
.PP
Available since: 1.3.0
.RE
.TP
\f[B]\f[CB]\-\-minimum\-contrast\f[B]\f[R]
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 \c
.UR https://www.w3.org/TR/WCAG20/
WCAG 2.0 specification
.UE \c
\&.
.RS
.PP
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.
.PP
This value does not apply to Emoji or images.
.RE
.TP
\f[B]\f[CB]\-\-palette\f[B]\f[R]
Color palette for the 256 color form that many terminal applications
use.
The syntax of this configuration is \f[CR]N=COLOR\f[R] where
\f[CR]N\f[R] is 0 to 255 (for the 256 colors in the terminal color
table) and \f[CR]COLOR\f[R] is a typical RGB color code such as
\f[CR]#AABBCC\f[R] or \f[CR]AABBCC\f[R], or a named X11 color.
For example, \f[CR]palette = 5=#BB78D9\f[R] will set the `purple' color.
.RS
.PP
The palette index can be in decimal, binary, octal, or hexadecimal.
Decimal is assumed unless a prefix is used: \f[CR]0b\f[R] for binary,
\f[CR]0o\f[R] for octal, and \f[CR]0x\f[R] for hexadecimal.
.PP
For definitions on the color indices and what they canonically map to,
\c
.UR https://www.ditig.com/256-colors-cheat-sheet
see this cheat sheet
.UE \c
\&.
.PP
For most themes, you only need to set the first 16 colors (0\(en15)
since the rest of the palette (16\(en255) will be automatically
generated by default (see \f[CR]palette\-generate\f[R] for more
details).
.RE
.TP
\f[B]\f[CB]\-\-palette\-generate\f[B]\f[R]
Whether to automatically generate the extended 256 color palette
(indices 16\(en255) from the base 16 ANSI colors.
.RS
.PP
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.
.PP
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 \f[CR]palette\f[R] are never
overwritten.
.PP
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.
.PP
For more information on how the generation works, see here:
https://gist.github.com/jake\-stewart/0a8ea46159a7da2c808e5be2177e1783
.PP
Available since: 1.3.0
.RE
.TP
\f[B]\f[CB]\-\-palette\-harmonious\f[B]\f[R]
Invert the palette colors generated when \f[CR]palette\-generate\f[R] 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.
.RS
.PP
This defaults to off because some legacy terminal applications hardcode
the assumption that palette indices 16\(en231 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.
.PP
This has no effect if \f[CR]palette\-generate\f[R] is disabled.
.PP
For more information see \f[CR]palette\-generate\f[R].
.PP
Available since: 1.3.0
.RE
.TP
\f[B]\f[CB]\-\-cursor\-color\f[B]\f[R]
The color of the cursor.
If this is not set, a default will be chosen.
.RS
.PP
Direct colors can be specified as either hex (\f[CR]#RRGGBB\f[R] or
\f[CR]RRGGBB\f[R]) or a named X11 color.
.PP
Additionally, special values can be used to set the color to match other
colors at runtime:
.IP \(bu 2
\f[CR]cell\-foreground\f[R] \- Match the cell foreground color.
(Available since: 1.2.0)
.IP \(bu 2
\f[CR]cell\-background\f[R] \- Match the cell background color.
(Available since: 1.2.0)
.RE
.TP
\f[B]\f[CB]\-\-cursor\-opacity\f[B]\f[R]
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.
.TP
\f[B]\f[CB]\-\-cursor\-style\f[B]\f[R]
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 \f[CR]CSI q\f[R]).
Shell configurations will often request specific cursor styles.
.RS
.PP
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
\f[CR]shell\-integration\-features = no\-cursor\f[R] or disabling shell
integration entirely.
.PP
Valid values are:
.IP \(bu 2
\f[CR]block\f[R]
.IP \(bu 2
\f[CR]bar\f[R]
.IP \(bu 2
\f[CR]underline\f[R]
.IP \(bu 2
\f[CR]block_hollow\f[R]
.RE
.TP
\f[B]\f[CB]\-\-cursor\-style\-blink\f[B]\f[R]
Sets the default blinking state of the cursor.
This is just the default state; running programs may override the cursor
style using \f[CR]DECSCUSR\f[R] (\f[CR]CSI q\f[R]).
.RS
.PP
If this is not set, the cursor blinks by default.
Note that this is not the same as a \(lqtrue\(rq value, as noted below.
.PP
If this is not set at all (\f[CR]null\f[R]), 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 \f[CR]DECSCUSR\f[R] will still be respected.
.PP
Valid values are:
.IP \(bu 2
\f[CR]\f[R] (blank)
.IP \(bu 2
\f[CR]true\f[R]
.IP \(bu 2
\f[CR]false\f[R]
.RE
.TP
\f[B]\f[CB]\-\-cursor\-text\f[B]\f[R]
The color of the text under the cursor.
If this is not set, a default will be chosen.
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
Since version 1.2.0, this can also be set to \f[CR]cell\-foreground\f[R]
to match the cell foreground color, or \f[CR]cell\-background\f[R] to
match the cell background color.
.TP
\f[B]\f[CB]\-\-cursor\-click\-to\-move\f[B]\f[R]
Enables the ability to move the cursor at prompts by clicking on a
location in the prompt text.
.RS
.PP
This feature requires shell integration, specifically prompt marking via
\f[CR]OSC 133\f[R].
Some shells like Fish (v4) and Nu (0.111+) natively support this while
others may require additional configuration or Ghostty\(cqs shell
integration features to be enabled.
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-mouse\-hide\-while\-typing\f[B]\f[R]
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.
.TP
\f[B]\f[CB]\-\-scroll\-to\-bottom\f[B]\f[R]
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 \f[CR]no\-\f[R] then it is disabled.
If you omit an option, its default value is used.
.RS
.PP
Available options:
.IP \(bu 2
\f[CR]keystroke\f[R] 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).
.IP \(bu 2
\f[CR]output\f[R] 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).
.PP
The default is \f[CR]keystroke, no\-output\f[R].
.RE
.TP
\f[B]\f[CB]\-\-mouse\-shift\-capture\f[B]\f[R]
Determines whether running programs can detect the shift key pressed
with a mouse click.
Typically, the shift key is used to extend mouse selection.
.RS
.PP
The default value of \f[CR]false\f[R] 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 \f[CR]XTSHIFTESCAPE\f[R] sequence.
.PP
The value \f[CR]true\f[R] means that the shift key is sent with the
mouse protocol but the running program can override this behavior with
\f[CR]XTSHIFTESCAPE\f[R].
.PP
The value \f[CR]never\f[R] is the same as \f[CR]false\f[R] but the
running program cannot override this behavior with
\f[CR]XTSHIFTESCAPE\f[R].
The value \f[CR]always\f[R] is the same as \f[CR]true\f[R] but the
running program cannot override this behavior with
\f[CR]XTSHIFTESCAPE\f[R].
.PP
If you always want shift to extend mouse selection even if the program
requests otherwise, set this to \f[CR]never\f[R].
.PP
Valid values are:
.IP \(bu 2
\f[CR]true\f[R]
.IP \(bu 2
\f[CR]false\f[R]
.IP \(bu 2
\f[CR]always\f[R]
.IP \(bu 2
\f[CR]never\f[R]
.RE
.TP
\f[B]\f[CB]\-\-mouse\-reporting\f[B]\f[R]
Enable or disable mouse reporting.
When set to \f[CR]false\f[R], 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.
.RS
.PP
When set to \f[CR]true\f[R] (the default), terminal applications can
request mouse reporting and will receive mouse events according to their
requested mode.
.PP
This can be toggled at runtime using the
\f[CR]toggle_mouse_reporting\f[R] keybind action.
.RE
.TP
\f[B]\f[CB]\-\-mouse\-scroll\-multiplier\f[B]\f[R]
Multiplier for scrolling distance with the mouse wheel.
.RS
.PP
A prefix of \f[CR]precision:\f[R] or \f[CR]discrete:\f[R] 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.
\f[CR]precision:0.1,discrete:3\f[R].
If no prefix is used, the multiplier applies to all scrolling devices.
Specifying a prefix was introduced in Ghostty 1.2.1.
.PP
The value will be clamped to [0.01, 10,000].
Both of these are extreme and you\(cqre likely to have a bad experience
if you set either extreme.
.PP
The default value is \(lq3\(rq for discrete devices and \(lq1\(rq for
precision devices.
.RE
.TP
\f[B]\f[CB]\-\-background\-opacity\f[B]\f[R]
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.
.RS
.PP
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\(cqt generally desirable.
.PP
On macOS, changing this configuration requires restarting Ghostty
completely.
.RE
.TP
\f[B]\f[CB]\-\-background\-opacity\-cells\f[B]\f[R]
Applies background opacity to cells with an explicit background color
set.
.RS
.PP
Normally, \f[CR]background\-opacity\f[R] 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 \f[CR]background\-opacity\f[R] (by design).
.PP
Setting this to \f[CR]true\f[R] will apply the
\f[CR]background\-opacity\f[R] to all cells regardless of whether they
have an explicit background color set or not.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-background\-blur\f[B]\f[R]
Whether to blur the background when \f[CR]background\-opacity\f[R] is
less than 1.
.RS
.PP
Valid values are:
.IP \(bu 2
a nonnegative integer specifying the \f[I]blur intensity\f[R]
.IP \(bu 2
\f[CR]false\f[R], equivalent to a blur intensity of 0
.IP \(bu 2
\f[CR]true\f[R], 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.
.PP
On macOS 26.0 and later, there are additional special values that can be
set to use the native macOS glass effects:
.IP \(bu 2
\f[CR]macos\-glass\-regular\f[R] \- Standard glass effect with some
opacity
.IP \(bu 2
\f[CR]macos\-glass\-clear\f[R] \- Highly transparent glass effect
.PP
If the macOS values are set, then this implies
\f[CR]background\-blur = true\f[R] on non\-macOS platforms.
.PP
Supported on macOS and on some Linux desktop environments, including:
.IP \(bu 2
KDE Plasma (Wayland and X11)
.PP
Warning: the exact blur intensity is \f[I]ignored\f[R] under KDE Plasma,
and setting this setting to either \f[CR]true\f[R] 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.
.PP
To configure KWin\(cqs global blur setting, open System Settings and go
to \(lqApps & Windows\(rq > \(lqWindow Management\(rq > \(lqDesktop
Effects\(rq and select the \(lqBlur\(rq plugin.
If disabled, enable it by ticking the checkbox to the left.
Then click on the \(lqConfigure\(rq button and there will be two sliders
that allow you to set background blur and noise intensities for all
apps, including Ghostty.
.PP
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\(cqt a unified interface for doing so.
.RE
.TP
\f[B]\f[CB]\-\-unfocused\-split\-opacity\f[B]\f[R]
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.
.RS
.PP
A value of 1 is fully opaque and a value of 0 is fully transparent.
Because \(lq0\(rq 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\(cqs going
on.
A value outside of the range 0.15 to 1 will be clamped to the nearest
valid value.
.RE
.TP
\f[B]\f[CB]\-\-unfocused\-split\-fill\f[B]\f[R]
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.
.RS
.PP
This will default to the background color.
.PP
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
.RE
.TP
\f[B]\f[CB]\-\-split\-divider\-color\f[B]\f[R]
The color of the split divider.
If this is not set, a default will be chosen.
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
.RS
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-split\-preserve\-zoom\f[B]\f[R]
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.
.RS
.PP
This can be set to \f[CR]navigation\f[R] to preserve the zoomed split
state when navigating to another split (e.g.\ via
\f[CR]goto_split\f[R]).
This will change the zoomed split to the newly focused split instead of
unzooming.
.PP
Any options can also be prefixed with \f[CR]no\-\f[R] to disable that
option.
.PP
Example: \f[CR]split\-preserve\-zoom = navigation\f[R]
.PP
Available since: 1.3.0
.RE
.TP
\f[B]\f[CB]\-\-search\-foreground\f[B]\f[R]
The foreground and background color for search matches.
This only applies to non\-focused search matches, also known as
candidate matches.
.RS
.PP
Valid values:
.IP \(bu 2
Hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R])
.IP \(bu 2
Named X11 color
.IP \(bu 2
\(lqcell\-foreground\(rq to match the cell foreground color
.IP \(bu 2
\(lqcell\-background\(rq to match the cell background color
.PP
The default value is black text on a golden yellow background.
.RE
.PP
\f[B]\f[CB]\-\-search\-background\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-search\-selected\-foreground\f[B]\f[R]
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.
.RS
.PP
Valid values:
.IP \(bu 2
Hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R])
.IP \(bu 2
Named X11 color
.IP \(bu 2
\(lqcell\-foreground\(rq to match the cell foreground color
.IP \(bu 2
\(lqcell\-background\(rq to match the cell background color
.PP
The default value is black text on a soft peach background.
.RE
.PP
\f[B]\f[CB]\-\-search\-selected\-background\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-command\f[B]\f[R]
The command to run, usually a shell.
If this is not an absolute path, it\(cqll be looked up in the
\f[CR]PATH\f[R].
If this is not set, a default will be looked up from your system.
The rules for the default lookup are:
.RS
.IP \(bu 2
\f[CR]SHELL\f[R] environment variable
.IP \(bu 2
\f[CR]passwd\f[R] entry (user information)
.PP
This can contain additional arguments to run the command with.
If additional arguments are provided, the command will be executed using
\f[CR]/bin/sh \-c\f[R] to offload shell argument expansion.
.PP
To avoid shell expansion altogether, prefix the command with
\f[CR]direct:\f[R], e.g.
\f[CR]direct:nvim foo\f[R].
This will avoid the roundtrip to \f[CR]/bin/sh\f[R] but will also not
support any shell parsing such as arguments with spaces, filepaths with
\f[CR]\(ti\f[R], globs, etc.
(Available since: 1.2.0)
.PP
You can also explicitly prefix the command with \f[CR]shell:\f[R] 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)
.PP
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 \f[CR]initial\-command\f[R] configuration.
.PP
Ghostty supports the common \f[CR]\-e\f[R] flag for executing a command
with arguments.
For example, \f[CR]ghostty \-e fish \-\-with \-\-custom \-\-args\f[R].
This flag sets the \f[CR]initial\-command\f[R] configuration, see that
for more information.
.RE
.TP
\f[B]\f[CB]\-\-initial\-command\f[B]\f[R]
This is the same as \(lqcommand\(rq, but only applies to the first
terminal surface created when Ghostty starts.
Subsequent terminal surfaces will use the \f[CR]command\f[R]
configuration.
.RS
.PP
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.
.PP
If you\(cqre using the \f[CR]ghostty\f[R] CLI there is also a shortcut
to set this with arguments directly: you can use the \f[CR]\-e\f[R]
flag.
For example: \f[CR]ghostty \-e fish \-\-with \-\-custom \-\-args\f[R].
The \f[CR]\-e\f[R] flag automatically forces some other behaviors as
well:
.IP \(bu 2
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
\f[CR]ghostty \-e\f[R] command).
.IP \(bu 2
\f[CR]gtk\-single\-instance=false\f[R] \- This ensures that a new
instance is launched and the CLI args are respected.
.IP \(bu 2
\f[CR]quit\-after\-last\-window\-closed=true\f[R] \- This ensures that
the Ghostty process will exit when the command exits.
Additionally, the \f[CR]quit\-after\-last\-window\-closed\-delay\f[R] is
unset.
.IP \(bu 2
\f[CR]shell\-integration=detect\f[R] (if not \f[CR]none\f[R]) \- This
prevents forcibly injecting any configured shell integration into the
command\(cqs environment.
With \f[CR]\-e\f[R] its highly unlikely that you\(cqre 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 \f[CR]\-e\f[R]\-executed command,
you must either name your binary appropriately or source the shell
integration script manually.
.RE
.TP
\f[B]\f[CB]\-\-notify\-on\-command\-finish\f[B]\f[R]
Controls when command finished notifications are sent.
There are three options:
.RS
.IP \(bu 2
\f[CR]never\f[R] \- Never send notifications (the default).
.IP \(bu 2
\f[CR]unfocused\f[R] \- Only send notifications if the surface that the
command is running in is not focused.
.IP \(bu 2
\f[CR]always\f[R] \- Always send notifications.
.PP
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.
.PP
On GTK, there is a context menu item that will enable command finished
notifications for a single command, overriding the \f[CR]never\f[R] and
\f[CR]unfocused\f[R] options.
.PP
Available since 1.3.0.
.RE
.TP
\f[B]\f[CB]\-\-notify\-on\-command\-finish\-action\f[B]\f[R]
If command finished notifications are enabled, this controls how the
user is notified.
.RS
.PP
Available options:
.IP \(bu 2
\f[CR]bell\f[R] \- enabled by default
.IP \(bu 2
\f[CR]notify\f[R] \- disabled by default
.PP
Options can be combined by listing them as a comma separated list.
Options can be negated by prefixing them with \f[CR]no\-\f[R].
For example \f[CR]no\-bell,notify\f[R].
.PP
Available since 1.3.0.
.RE
.TP
\f[B]\f[CB]\-\-notify\-on\-command\-finish\-after\f[B]\f[R]
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.
.RS
.PP
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.
.PP
The allowed time units are as follows:
.IP \(bu 2
\f[CR]y\f[R] \- 365 SI days, or 8760 hours, or 31536000 seconds.
No adjustments are made for leap years or leap seconds.
.IP \(bu 2
\f[CR]d\f[R] \- one SI day, or 86400 seconds.
.IP \(bu 2
\f[CR]h\f[R] \- one hour, or 3600 seconds.
.IP \(bu 2
\f[CR]m\f[R] \- one minute, or 60 seconds.
.IP \(bu 2
\f[CR]s\f[R] \- one second.
.IP \(bu 2
\f[CR]ms\f[R] \- one millisecond, or 0.001 second.
.IP \(bu 2
\f[CR]us\f[R] or \f[CR]µs\f[R] \- one microsecond, or 0.000001 second.
.IP \(bu 2
\f[CR]ns\f[R] \- one nanosecond, or 0.000000001 second.
.PP
Examples: * \f[CR]1h30m\f[R] * \f[CR]45s\f[R]
.PP
Units can be repeated and will be added together.
This means that \f[CR]1h1h\f[R] is equivalent to \f[CR]2h\f[R].
This is confusing and should be avoided.
A future update may disallow this.
.PP
The maximum value is \f[CR]584y 49w 23h 34m 33s 709ms 551µs 615ns\f[R].
Any value larger than this will be clamped to the maximum value.
.PP
Available since 1.3.0
.RE
.TP
\f[B]\f[CB]\-\-env\f[B]\f[R]
Extra environment variables to pass to commands launched in a terminal
surface.
The format is \f[CR]env=KEY=VALUE\f[R].
.RS
.PP
\f[CR]env = foo=bar\f[R] \f[CR]env = bar=baz\f[R]
.PP
Setting \f[CR]env\f[R] to an empty string will reset the entire map to
default (empty).
.PP
\f[CR]env =\f[R]
.PP
Setting a key to an empty string will remove that particular key and
corresponding value from the map.
.PP
\f[CR]env = foo=bar\f[R] \f[CR]env = foo=\f[R]
.PP
will result in \f[CR]foo\f[R] not being passed to the launched commands.
.PP
Setting a key multiple times will overwrite previous entries.
.PP
\f[CR]env = foo=bar\f[R] \f[CR]env = foo=baz\f[R]
.PP
will result in \f[CR]foo=baz\f[R] being passed to the launched commands.
.PP
These environment variables will override any existing environment
variables set by Ghostty.
For example, if you set \f[CR]GHOSTTY_RESOURCES_DIR\f[R] then the value
you set here will override the value Ghostty typically automatically
injects.
.PP
These environment variables \f[I]will not\f[R] be passed to commands run
by Ghostty for other purposes, like \f[CR]open\f[R] or
\f[CR]xdg\-open\f[R] used to open URLs in your browser.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-input\f[B]\f[R]
Data to send as input to the command on startup.
.RS
.PP
The configured \f[CR]command\f[R] 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.
.PP
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.
.PP
The format of this value is:
.IP \(bu 2
\f[CR]raw:<string>\f[R] \- Send raw text as\-is.
This uses Zig string literal syntax so you can specify control
characters and other standard escapes.
.IP \(bu 2
\f[CR]path:<path>\f[R] \- Read a filepath and send the contents.
The path must be to a file with finite length.
e.g.\ don\(cqt use a device such as \f[CR]/dev/stdin\f[R] or
\f[CR]/dev/urandom\f[R] 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.
.PP
If no valid prefix is found, it is assumed to be a \f[CR]raw:\f[R]
input.
This is an ergonomic choice to allow you to simply write
\f[CR]input = \(dqHello, world!\(dq\f[R] (a common case) without needing
to prefix every value with \f[CR]raw:\f[R].
.PP
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).
.PP
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.
.PP
Changing this configuration at runtime will only affect new terminals.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-wait\-after\-command\f[B]\f[R]
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.
.RS
.PP
This is primarily useful for scripts or debugging.
.RE
.TP
\f[B]\f[CB]\-\-abnormal\-command\-exit\-runtime\f[B]\f[R]
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.
.RS
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-scrollback\-limit\f[B]\f[R]
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.
.RS
.PP
When this limit is reached, the oldest lines are removed from the
scrollback.
.PP
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.
.PP
This size is per terminal surface, not for the entire application.
.PP
It is not currently possible to set an unlimited scrollback buffer.
This is a future planned feature.
.PP
This can be changed at runtime but will only affect new terminal
surfaces.
.RE
.TP
\f[B]\f[CB]\-\-scrollbar\f[B]\f[R]
Control when the scrollbar is shown to scroll the scrollback buffer.
.RS
.PP
The default value is \f[CR]system\f[R].
.PP
Valid values:
.IP \(bu 2
\f[CR]system\f[R] \- Respect the system settings for when to show
scrollbars.
For example, on macOS, this will respect the \(lqScrollbar behavior\(rq
system setting which by default usually only shows scrollbars while
actively scrolling or hovering the gutter.
.IP \(bu 2
\f[CR]never\f[R] \- 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.
.RE
.TP
\f[B]\f[CB]\-\-link\f[B]\f[R]
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.\ \f[CR]open\f[R] or
\f[CR]xdg\-open\f[R]) or executing any arbitrary binding action.
.RS
.PP
Links that are configured earlier take precedence over links that are
configured later.
.PP
A default link that matches a URL and opens it in the system opener
always exists.
This can be disabled using \f[CR]link\-url\f[R].
.PP
TODO: This can\(cqt currently be set!
.RE
.TP
\f[B]\f[CB]\-\-link\-url\f[B]\f[R]
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.
.RS
.PP
The URL matcher is always lowest priority of any configured links (see
\f[CR]link\f[R]).
If you want to customize URL matching, use \f[CR]link\f[R] and disable
this.
.RE
.TP
\f[B]\f[CB]\-\-link\-previews\f[B]\f[R]
Show link previews for a matched URL.
.RS
.PP
When true, link previews are shown for all matched URLs.
When false, link previews are never shown.
When set to \(lqosc8\(rq, 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).
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-maximize\f[B]\f[R]
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.
.RS
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-fullscreen\f[B]\f[R]
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.
.RS
.PP
Allowable values are:
.IP \(bu 2
\f[CR]false\f[R] \- Don\(cqt start in fullscreen (default)
.IP \(bu 2
\f[CR]true\f[R] \- Start in native fullscreen
.IP \(bu 2
\f[CR]non\-native\f[R] \- (macOS only) Start in non\-native fullscreen,
hiding the menu bar.
This is faster than native fullscreen since it doesn\(cqt use
animations.
On non\-macOS platforms, this behaves the same as \f[CR]true\f[R].
.IP \(bu 2
\f[CR]non\-native\-visible\-menu\f[R] \- (macOS only) Start in
non\-native fullscreen, keeping the menu bar visible.
On non\-macOS platforms, behaves like \f[CR]true\f[R].
.IP \(bu 2
\f[CR]non\-native\-padded\-notch\f[R] \- (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 \f[CR]true\f[R].
.PP
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 \f[CR]true\f[R] (native) instead.
.PP
On macOS, \f[CR]true\f[R] (native fullscreen) does not work if
\f[CR]window\-decoration\f[R] is set to \f[CR]false\f[R], because native
fullscreen on macOS requires window decorations.
.RE
.TP
\f[B]\f[CB]\-\-title\f[B]\f[R]
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.
.RS
.PP
If you want a blank title, set this to one or more spaces by quoting the
value.
For example, \f[CR]title = \(dq \(dq\f[R].
This effectively hides the title.
This is necessary because setting a blank value resets the title to the
default value of the running program.
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-class\f[B]\f[R]
The setting that will change the application class value.
.RS
.PP
This controls the class field of the \f[CR]WM_CLASS\f[R] 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.
.PP
Note that changing this value between invocations will create new,
separate instances, of Ghostty when running with
\f[CR]gtk\-single\-instance=true\f[R].
See that option for more details.
.PP
Changing this value may break launching Ghostty from \f[CR].desktop\f[R]
files, via DBus activation, or systemd user services as the system is
expecting Ghostty to connect to DBus using the default \f[CR]class\f[R]
when it is launched.
.PP
The class name must follow the requirements defined \c
.UR https://docs.gtk.org/gio/type_func.Application.id_is_valid.html
in the GTK documentation
.UE \c
\&.
.PP
The default is \f[CR]com.mitchellh.ghostty\f[R].
.PP
This only affects GTK builds.
.RE
.TP
\f[B]\f[CB]\-\-x11\-instance\-name\f[B]\f[R]
This controls the instance name field of the \f[CR]WM_CLASS\f[R] X11
property when running under X11.
It has no effect otherwise.
.RS
.PP
The default is \f[CR]ghostty\f[R].
.PP
This only affects GTK builds.
.RE
.TP
\f[B]\f[CB]\-\-working\-directory\f[B]\f[R]
The directory to change to after starting the command.
.RS
.PP
This setting is secondary to the
\f[CR]window\-inherit\-working\-directory\f[R] setting.
If a previous Ghostty terminal exists in the same process,
\f[CR]window\-inherit\-working\-directory\f[R] will take precedence.
Otherwise, this setting will be used.
Typically, this setting is used only for the first window.
.PP
The default is \f[CR]inherit\f[R] except in special scenarios listed
next.
On macOS, if Ghostty can detect it is launched from launchd
(double\-clicked) or \f[CR]open\f[R], then it defaults to
\f[CR]home\f[R].
On Linux with GTK, if Ghostty can detect it was launched from a desktop
launcher, then it defaults to \f[CR]home\f[R].
.PP
The value of this must be an absolute path, a path prefixed with
\f[CR]\(ti/\f[R] (the tilde will be expanded to the user\(cqs home
directory), or one of the special values below:
.IP \(bu 2
\f[CR]home\f[R] \- The home directory of the executing user.
.IP \(bu 2
\f[CR]inherit\f[R] \- The working directory of the launching process.
.RE
.TP
\f[B]\f[CB]\-\-keybind\f[B]\f[R]
Key bindings.
The format is \f[CR]trigger=action\f[R].
Duplicate triggers will overwrite previously set values.
The list of actions is available in the documentation or using the
\f[CR]ghostty +list\-actions\f[R] command.
.RS
.PP
Trigger: \f[CR]+\f[R]\-separated list of keys and modifiers.
Example: \f[CR]ctrl+a\f[R], \f[CR]ctrl+shift+b\f[R], \f[CR]up\f[R].
.PP
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, \f[CR]a\f[R] will match the \f[CR]a\f[R] key on a QWERTY
keyboard, but will match the \f[CR]q\f[R] key on a AZERTY keyboard
(assuming US physical layout).
.PP
For Unicode codepoints, matching is done by comparing the set of
modifiers with the unmodified codepoint.
The unmodified codepoint is sometimes called an \(lqunshifted
character\(rq in other software, but all modifiers are considered, not
only shift.
For example, \f[CR]ctrl+a\f[R] will match \f[CR]a\f[R] but not
\f[CR]ctrl+shift+a\f[R] (which is \f[CR]A\f[R] on a US keyboard).
.PP
Further, codepoint matching is case\-insensitive and the unmodified
codepoint is always case folded for comparison.
As a result, \f[CR]ctrl+A\f[R] configured will match when
\f[CR]ctrl+a\f[R] is pressed.
Note that this means some key combinations are impossible depending on
keyboard layout.
For example, \f[CR]ctrl+_\f[R] is impossible on a US keyboard because
\f[CR]_\f[R] is \f[CR]shift+\-\f[R] and \f[CR]ctrl+shift+\-\f[R] is not
equal to \f[CR]ctrl+_\f[R] (because the modifiers don\(cqt 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
.PP
Physical key codes can be specified by using any of the key codes as
specified by the \c
.UR https://www.w3.org/TR/uievents-code/
W3C specification
.UE \c
\&.
For example, \f[CR]KeyA\f[R] will match the physical \f[CR]a\f[R] key on
a US standard keyboard regardless of the keyboard layout.
These are case\-sensitive.
.PP
For aesthetic reasons, the w3c codes also support snake case.
For example, \f[CR]key_a\f[R] is equivalent to \f[CR]KeyA\f[R].
The only exceptions are function keys, e.g.\ \f[CR]F1\f[R] is
\f[CR]f1\f[R] (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.
.PP
Function keys such as \f[CR]insert\f[R], \f[CR]up\f[R], \f[CR]f5\f[R],
etc.
are also specified using the keys as specified by the previously linked
W3C specification.
.PP
Physical keys always match with a higher priority than Unicode
codepoints, so if you specify both \f[CR]a\f[R] and \f[CR]KeyA\f[R], the
physical key will always be used regardless of what order they are
configured.
.PP
The special key \f[CR]catch_all\f[R] can be used to match any key that
is not otherwise bound.
This can be combined with modifiers, for example
\f[CR]ctrl+catch_all\f[R] will match any key pressed with
\f[CR]ctrl\f[R] that is not otherwise bound.
When looking up a binding, Ghostty first tries to match
\f[CR]catch_all\f[R] with modifiers.
If no match is found and the event has modifiers, it falls back to
\f[CR]catch_all\f[R] without modifiers.
.PP
Valid modifiers are \f[CR]shift\f[R], \f[CR]ctrl\f[R] (alias:
\f[CR]control\f[R]), \f[CR]alt\f[R] (alias: \f[CR]opt\f[R],
\f[CR]option\f[R]), and \f[CR]super\f[R] (alias: \f[CR]cmd\f[R],
\f[CR]command\f[R]).
You may use the modifier or the alias.
When debugging keybinds, the non\-aliased modifier will always be used
in output.
.PP
Note: The fn or \(lqglobe\(rq key on keyboards are not supported as a
modifier.
This is a limitation of the operating systems and GUI toolkits that
Ghostty uses.
.PP
Some additional notes for triggers:
.IP \(bu 2
modifiers cannot repeat, \f[CR]ctrl+ctrl+a\f[R] is invalid.
.IP \(bu 2
modifiers and keys can be in any order, \f[CR]shift+a+ctrl\f[R] is
\f[I]weird\f[R], but valid.
.IP \(bu 2
only a single key input is allowed, \f[CR]ctrl+a+b\f[R] is invalid.
.PP
You may also specify multiple triggers separated by \f[CR]>\f[R] to
require a sequence of triggers to activate the action.
For example, \f[CR]ctrl+a>n=new_window\f[R] will only trigger the
\f[CR]new_window\f[R] action if the user presses \f[CR]ctrl+a\f[R]
followed separately by \f[CR]n\f[R].
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.
.PP
Warning: If you define a sequence as a CLI argument to
\f[CR]ghostty\f[R], you probably have to quote the keybind since
\f[CR]>\f[R] is a special character in most shells.
Example: ghostty \(enkeybind=`ctrl+a>n=new_window'
.PP
A trigger sequence has some special handling:
.IP \(bu 2
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.\ \f[CR]ctrl+a>ctrl+a=text:foo\f[R]) or press an unbound key which
will send both keys to the program.
.IP \(bu 2
If an unbound key is pressed during a sequence and a
\f[CR]catch_all\f[R] binding exists that would \f[CR]ignore\f[R] 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.
.IP \(bu 2
If a prefix in a sequence is previously bound, the sequence will
override the previous binding.
For example, if \f[CR]ctrl+a\f[R] is bound to \f[CR]new_window\f[R] and
\f[CR]ctrl+a>n\f[R] is bound to \f[CR]new_tab\f[R], pressing
\f[CR]ctrl+a\f[R] will do nothing.
.IP \(bu 2
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 \f[CR]ctrl+a>n\f[R] and \f[CR]ctrl+a>t\f[R],
and then bind \f[CR]ctrl+a\f[R] directly, both \f[CR]ctrl+a>n\f[R] and
\f[CR]ctrl+a>t\f[R] will become unbound.
.IP \(bu 2
Trigger sequences are not allowed for \f[CR]global:\f[R] or
\f[CR]all:\f[R]\-prefixed triggers.
This is a limitation we could remove in the future.
.PP
Action is the action to take when the trigger is satisfied.
It takes the format \f[CR]action\f[R] or \f[CR]action:param\f[R].
The latter form is only valid if the action requires a parameter.
.IP \(bu 2
\f[CR]ignore\f[R] \- Do nothing, ignore the key input.
This can be used to black hole certain inputs to have no effect.
.IP \(bu 2
\f[CR]unbind\f[R] \- 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
\f[CR]physical:\f[R]\-prefixed triggers without specifying the prefix.
.IP \(bu 2
\f[CR]csi:text\f[R] \- Send a CSI sequence.
e.g.\ \f[CR]csi:A\f[R] sends \(lqcursor up\(rq.
.IP \(bu 2
\f[CR]esc:text\f[R] \- Send an escape sequence.
e.g.\ \f[CR]esc:d\f[R] deletes to the end of the word to the right.
.IP \(bu 2
\f[CR]text:text\f[R] \- Send a string.
Uses Zig string literal syntax.
e.g.\ \f[CR]text:\(rsx15\f[R] sends Ctrl\-U.
.IP \(bu 2
All other actions can be found in the documentation or by using the
\f[CR]ghostty +list\-actions\f[R] command.
.PP
Some notes for the action:
.IP \(bu 2
The parameter is taken as\-is after the \f[CR]:\f[R].
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: \f[CR]\-\-keybind=\(dqup=csi:A B\(dq\f[R]
.PP
There are some additional special values that can be specified for
keybind:
.IP \(bu 2
\f[CR]keybind=clear\f[R] will clear all set keybindings.
Warning: this removes ALL keybindings up to this point, including the
default keybindings.
.PP
The keybind trigger can be prefixed with some special values to change
the behavior of the keybind.
These are:
.IP \(bu 2
\f[CR]all:\f[R]
.RS 2
.PP
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.\ \f[CR]quit\f[R]), this prefix
has no effect.
.PP
Available since: 1.0.0
.RE
.IP \(bu 2
\f[CR]global:\f[R]
.RS 2
.PP
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 \f[CR]all:\f[R].
.PP
Note: this does not work in all environments; see the additional notes
below for more information.
.PP
Available since: 1.0.0 on macOS, 1.2.0 on GTK
.RE
.IP \(bu 2
\f[CR]unconsumed:\f[R]
.RS 2
.PP
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
\f[CR]unconsumed:\f[R] prefix before the entire keybind.
For example: \f[CR]unconsumed:ctrl+a=reload_config\f[R].
\f[CR]global:\f[R] and \f[CR]all:\f[R]\-prefixed keybinds will always
consume the input regardless of this setting.
Since they are not associated with a specific terminal surface,
they\(cqre never encoded.
.PP
Available since: 1.0.0
.RE
.IP \(bu 2
\f[CR]performable:\f[R]
.RS 2
.PP
Only consume the input if the action is able to be performed.
For example, the \f[CR]copy_to_clipboard\f[R] 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 \f[CR]global:\f[R] or \f[CR]all:\f[R]\-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).
.PP
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\(cqt appear as a
shortcut label in the menu.
.PP
Available since: 1.1.0
.RE
.PP
Keybind triggers are not unique per prefix combination.
For example, \f[CR]ctrl+a\f[R] and \f[CR]global:ctrl+a\f[R] are not two
separate keybinds.
The keybind set later will overwrite the keybind set earlier.
In this case, the \f[CR]global:\f[R] keybind will be used.
.PP
Multiple prefixes can be specified.
For example, \f[CR]global:unconsumed:ctrl+a=reload_config\f[R] will make
the keybind global and not consume the input to reload the config.
.PP
Note: \f[CR]global:\f[R] is only supported on macOS and certain Linux
platforms.
.PP
On macOS, this feature requires accessibility permissions to be granted
to Ghostty.
When a \f[CR]global:\f[R] 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.
.PP
On Linux, you need a desktop environment that implements the \c
.UR https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.GlobalShortcuts.html
Global Shortcuts
.UE \c
\ protocol as a part of its XDG desktop protocol implementation.
Desktop environments that are known to support (or not support) global
shortcuts include:
.IP \(bu 2
Users using KDE Plasma (since \c
.UR https://kde.org/announcements/plasma/5/5.27.0/#wayland
5.27
.UE \c
) and GNOME (since \c
.UR https://release.gnome.org/48/#and-thats-not-all
48
.UE \c
) should be able to use global shortcuts with little to no
configuration.
.IP \(bu 2
Some manual configuration is required on Hyprland.
Consult the steps outlined on the \c
.UR https://wiki.hyprland.org/Configuring/Binds/#dbus-global-shortcuts
Hyprland Wiki
.UE \c
\ to set up global shortcuts correctly.
(Important: \c
.UR https://wiki.hyprland.org/Hypr-Ecosystem/xdg-desktop-portal-hyprland/
\f[CR]xdg\-desktop\-portal\-hyprland\f[R]
.UE \c
\ must also be installed!)
.IP \(bu 2
Notably, global shortcuts have not been implemented on wlroots\-based
compositors like Sway (see \c
.UR https://github.com/emersion/xdg-desktop-portal-wlr/issues/240
upstream issue
.UE \c
).
.SS Chained Actions
.PP
A keybind can have multiple actions by using the \f[CR]chain\f[R]
keyword for subsequent actions.
When a keybind is activated, all chained actions are executed in order.
The syntax is:
.IP
.EX
keybind = ctrl+a=new_window
keybind = chain=goto_split:left
.EE
.PP
This binds \f[CR]ctrl+a\f[R] to first open a new window, then move focus
to the left split.
Each \f[CR]chain\f[R] entry appends an action to the most recently
defined keybind.
You can chain as many actions as you want:
.IP
.EX
keybind = ctrl+a=new_window
keybind = chain=goto_split:left
keybind = chain=toggle_fullscreen
.EE
.PP
Chained actions cannot have prefixes like \f[CR]global:\f[R] or
\f[CR]unconsumed:\f[R].
The flags from the original keybind apply to the entire chain.
.PP
Chained actions work with key sequences as well.
For example:
.IP
.EX
keybind = ctrl+a>n=new_window
keybind = chain=goto_split:left
.EE
.PP
Chains with key sequences apply to the most recent binding in the
sequence.
.PP
Chained keybinds are available since Ghostty 1.3.0.
.SS Key Tables
.PP
You may also create a named set of keybindings known as a \(lqkey
table.\(rq A key table must be explicitly activated for the bindings to
become available.
This can be used to implement features such as a \(lqcopy mode\(rq,
\(lqvim mode\(rq, etc.
Generically, this can implement modal keyboard input.
.PP
Key tables are defined using the syntax \f[CR]<table>/<binding>\f[R].
The \f[CR]<binding>\f[R] value is everything documented above for
keybinds.
The \f[CR]<table>\f[R] value is the name of the key table.
Table names can contain anything except \f[CR]/\f[R], \f[CR]=\f[R],
\f[CR]+\f[R], and \f[CR]>\f[R].
The characters \f[CR]+\f[R] and \f[CR]>\f[R] are reserved for keybind
syntax (modifier combinations and key sequences).
For example \f[CR]foo/ctrl+a=new_window\f[R] defines a binding within a
table named \f[CR]foo\f[R].
.PP
Tables are activated and deactivated using the binding actions
\f[CR]activate_key_table:<name>\f[R] and
\f[CR]deactivate_key_table\f[R].
Other table related binding actions also exist; see the documentation
for a full list.
These are the primary way to interact with key tables.
.PP
Binding lookup proceeds from the innermost table outward, so keybinds in
the default table remain available unless explicitly unbound in an inner
table.
.PP
A key table has some special syntax and handling:
.IP \(bu 2
\f[CR]<name>/\f[R] (with no binding) defines and clears a table,
resetting all of its keybinds and settings.
.IP \(bu 2
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., \f[CR]A \-> B \-> A \-> B\f[R] is valid,
but \f[CR]A \-> B \-> B\f[R] is not).
.IP \(bu 2
A table can be activated in one\-shot mode using
\f[CR]activate_key_table_once:<name>\f[R].
A one\-shot table is automatically deactivated when any non\-catch\-all
binding is invoked.
.IP \(bu 2
Key sequences work within tables:
\f[CR]foo/ctrl+a>ctrl+b=new_window\f[R].
If an invalid key is pressed, the sequence ends but the table remains
active.
.IP \(bu 2
Chain actions work within tables, the \f[CR]chain\f[R] keyword applies
to the most recently defined binding in the table.
e.g.\ if you set \f[CR]table/ctrl+a=new_window\f[R] you can chain by
using \f[CR]chain=text:hello\f[R].
Important: chain itself doesn\(cqt get prefixed with the table name,
since it applies to the most recent binding in any table.
.IP \(bu 2
Prefixes like \f[CR]global:\f[R] work within tables:
\f[CR]foo/global:ctrl+a=new_window\f[R].
.PP
Key tables are available since Ghostty 1.3.0.
.RE
.TP
\f[B]\f[CB]\-\-key\-remap\f[B]\f[R]
Remap modifier keys within Ghostty.
This allows you to swap or reassign modifier keys at the application
level without affecting system\-wide settings.
.RS
.PP
The format is \f[CR]from=to\f[R] where both \f[CR]from\f[R] and
\f[CR]to\f[R] are modifier key names.
You can use generic names like \f[CR]ctrl\f[R], \f[CR]alt\f[R],
\f[CR]shift\f[R], \f[CR]super\f[R] (macOS:
\f[CR]cmd\f[R]/\f[CR]command\f[R]) or sided names like
\f[CR]left_ctrl\f[R], \f[CR]right_alt\f[R], etc.
.PP
This will NOT change keyboard layout or key encodings outside of
Ghostty.
For example, on macOS, \f[CR]option+a\f[R] may still produce
\f[CR]å\f[R] even if \f[CR]option\f[R] is remapped to \f[CR]ctrl\f[R].
Desktop environments usually handle key layout long before Ghostty
receives the key events.
.PP
Example:
.IP
.EX
key\-remap = ctrl=super
key\-remap = left_control=right_alt
.EE
.PP
Important notes:
.IP \(bu 2
This is a one\-way remap.
If you remap \f[CR]ctrl=super\f[R], then the physical Ctrl key acts as
Super, but the Super key remains Super.
.IP \(bu 2
Remaps are not transitive.
If you remap \f[CR]ctrl=super\f[R] and \f[CR]alt=ctrl\f[R], pressing Alt
will produce Ctrl, NOT Super.
.IP \(bu 2
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, \f[CR]option+a\f[R] on macOS may still produce \f[CR]å\f[R]
even if \f[CR]option\f[R] is remapped to \f[CR]ctrl\f[R].
.IP \(bu 2
Generic modifiers (e.g.\ \f[CR]ctrl\f[R]) match both left and right
physical keys.
Use sided names (e.g.\ \f[CR]left_ctrl\f[R]) to remap only one side.
.PP
There are other edge case scenarios that may not behave as expected but
are working as intended the way this feature is designed:
.IP \(bu 2
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.
.PP
This configuration can be repeated to specify multiple remaps.
.RE
.TP
\f[B]\f[CB]\-\-window\-padding\-x\f[B]\f[R]
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.
.RS
.PP
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.
.PP
Changing this configuration at runtime will only affect new terminals,
i.e.
new windows, tabs, etc.
.PP
To set a different left and right padding, specify two numerical values
separated by a comma.
For example, \f[CR]window\-padding\-x = 2,4\f[R] 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, \f[CR]window\-padding\-x = 2\f[R] will set both paddings to
2.
.RE
.TP
\f[B]\f[CB]\-\-window\-padding\-y\f[B]\f[R]
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.
.RS
.PP
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.
.PP
Changing this configuration at runtime will only affect new terminals,
i.e.\ new windows, tabs, etc.
.PP
To set a different top and bottom padding, specify two numerical values
separated by a comma.
For example, \f[CR]window\-padding\-y = 2,4\f[R] 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, \f[CR]window\-padding\-y = 2\f[R] will set both paddings to
2.
.RE
.TP
\f[B]\f[CB]\-\-window\-padding\-balance\f[B]\f[R]
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 \f[CR]true\f[R], then this extra padding is automatically
balanced between all four edges to minimize imbalance on one side.
If this is \f[CR]false\f[R], the top left grid cell will always hug the
edge with zero padding other than what may be specified with the other
\f[CR]window\-padding\f[R] options.
.RS
.PP
If other \f[CR]window\-padding\f[R] fields are set and this is
\f[CR]true\f[R], 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.
.RE
.TP
\f[B]\f[CB]\-\-window\-padding\-color\f[B]\f[R]
The color of the padding area of the window.
Valid values are:
.RS
.IP \(bu 2
\f[CR]background\f[R] \- The background color specified in
\f[CR]background\f[R].
.IP \(bu 2
\f[CR]extend\f[R] \- Extend the background color of the nearest grid
cell.
.IP \(bu 2
\f[CR]extend\-always\f[R] \- Same as \(lqextend\(rq but always extends
without applying any of the heuristics that disable extending noted
below.
.PP
The \(lqextend\(rq 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:
.IP \(bu 2
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.
.IP \(bu 2
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.
.IP \(bu 2
The nearest row contains a perfect fit powerline character.
These don\(cqt look good extended.
.RE
.TP
\f[B]\f[CB]\-\-window\-vsync\f[B]\f[R]
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.
.RS
.PP
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.
.PP
Changing this value at runtime will only affect new terminals.
.PP
This setting is only supported currently on macOS.
.RE
.TP
\f[B]\f[CB]\-\-window\-inherit\-working\-directory\f[B]\f[R]
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 \f[CR]working\-directory\f[R] option).
.TP
\f[B]\f[CB]\-\-tab\-inherit\-working\-directory\f[B]\f[R]
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 \f[CR]working\-directory\f[R] option).
.TP
\f[B]\f[CB]\-\-split\-inherit\-working\-directory\f[B]\f[R]
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 \f[CR]working\-directory\f[R] option).
.TP
\f[B]\f[CB]\-\-window\-inherit\-font\-size\f[B]\f[R]
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
\f[CR]font\-size\f[R] will be used.
.TP
\f[B]\f[CB]\-\-window\-decoration\f[B]\f[R]
Configure a preference for window decorations.
This setting specifies a \f[I]preference\f[R]; 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.
.RS
.PP
Valid values:
.IP \(bu 2
\f[CR]none\f[R]
.RS 2
.PP
All window decorations will be disabled.
Titlebar, borders, etc.
will not be shown.
On macOS, this will also disable tabs (enforced by the system).
.RE
.IP \(bu 2
\f[CR]auto\f[R]
.RS 2
.PP
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 \(lqnative\(rq for your
desktop.
.RE
.IP \(bu 2
\f[CR]client\f[R]
.RS 2
.PP
Prefer client\-side decorations.
.PP
Available since: 1.1.0
.RE
.IP \(bu 2
\f[CR]server\f[R]
.RS 2
.PP
Prefer server\-side decorations.
This is only relevant on Linux with GTK, either on X11, or Wayland on a
compositor that supports the \f[CR]org_kde_kwin_server_decoration\f[R]
protocol (e.g.\ KDE Plasma, but almost any non\-GNOME desktop supports
this protocol).
.PP
If \f[CR]server\f[R] is set but the environment doesn\(cqt support
server\-side decorations, client\-side decorations will be used instead.
.PP
Available since: 1.1.0
.RE
.PP
The default value is \f[CR]auto\f[R].
.PP
For the sake of backwards compatibility and convenience, this setting
also accepts boolean true and false values.
If set to \f[CR]true\f[R], this is equivalent to \f[CR]auto\f[R].
If set to \f[CR]false\f[R], this is equivalent to \f[CR]none\f[R].
This is convenient for users who live primarily on systems that don\(cqt
differentiate between client and server\-side decorations (e.g.\ macOS
and Windows).
.PP
The \(lqtoggle_window_decorations\(rq keybind action can be used to
create a keybinding to toggle this setting at runtime.
.PP
macOS: To hide the titlebar without removing the native window borders
or rounded corners, use \f[CR]macos\-titlebar\-style = hidden\f[R]
instead.
.RE
.TP
\f[B]\f[CB]\-\-window\-title\-font\-family\f[B]\f[R]
The font that will be used for the application\(cqs window and tab
titles.
.RS
.PP
If this setting is left unset, the system default font will be used.
.PP
Note: any font available on the system may be used, this font is not
required to be a fixed\-width font.
.PP
Available since: 1.0.0 on macOS, 1.1.0 on GTK
.RE
.TP
\f[B]\f[CB]\-\-window\-subtitle\f[B]\f[R]
The text that will be displayed in the subtitle of the window.
Valid values:
.RS
.IP \(bu 2
\f[CR]false\f[R] \- Disable the subtitle.
.IP \(bu 2
\f[CR]working\-directory\f[R] \- Set the subtitle to the working
directory of the surface.
.PP
This feature is only supported on GTK.
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-window\-theme\f[B]\f[R]
The theme to use for the windows.
Valid values:
.RS
.IP \(bu 2
\f[CR]auto\f[R] \- Determine the theme based on the configured terminal
background color.
This has no effect if the \(lqtheme\(rq configuration has separate light
and dark themes.
In that case, the behavior of \(lqauto\(rq is equivalent to
\(lqsystem\(rq.
.IP \(bu 2
\f[CR]system\f[R] \- Use the system theme.
.IP \(bu 2
\f[CR]light\f[R] \- Use the light theme regardless of system theme.
.IP \(bu 2
\f[CR]dark\f[R] \- Use the dark theme regardless of system theme.
.IP \(bu 2
\f[CR]ghostty\f[R] \- Use the background and foreground colors specified
in the Ghostty configuration.
This is only supported on Linux builds.
.PP
On macOS, if \f[CR]macos\-titlebar\-style\f[R] is \f[CR]tabs\f[R] or
\f[CR]transparent\f[R], 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.
.PP
This is currently only supported on macOS and Linux.
.RE
.TP
\f[B]\f[CB]\-\-window\-colorspace\f[B]\f[R]
The color space to use when interpreting terminal colors.
\(lqTerminal colors\(rq refers to colors specified in your configuration
and colors produced by direct\-color SGR sequences.
.RS
.PP
Valid values:
.IP \(bu 2
\f[CR]srgb\f[R] \- Interpret colors in the sRGB color space.
This is the default.
.IP \(bu 2
\f[CR]display\-p3\f[R] \- Interpret colors in the Display P3 color
space.
.PP
This setting is currently only supported on macOS.
.RE
.TP
\f[B]\f[CB]\-\-window\-height\f[B]\f[R]
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.
.RS
.PP
We don\(cqt currently support specifying a size in pixels but a future
change can enable that.
If this isn\(cqt specified, the app runtime will determine some default
size.
.PP
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.
.PP
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.
.PP
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.
.PP
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 \f[CR]window\-decoration\f[R]),
then this will work as expected.
.PP
Windows smaller than 10 wide by 4 high are not allowed.
.RE
.PP
\f[B]\f[CB]\-\-window\-width\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-window\-position\-x\f[B]\f[R]
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.
.RS
.PP
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.
.PP
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.
.PP
Invalid positions are runtime\-specific, but generally the positions are
clamped to the nearest valid position.
.PP
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.
.PP
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.
.RE
.PP
\f[B]\f[CB]\-\-window\-position\-y\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-window\-save\-state\f[B]\f[R]
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 \f[CR]shell\-integration\f[R] for more information.
.RS
.PP
There are three valid values for this configuration:
.IP \(bu 2
\f[CR]default\f[R] 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.
.IP \(bu 2
\f[CR]never\f[R] will never save window state.
.IP \(bu 2
\f[CR]always\f[R] will always save window state whenever Ghostty is
exited.
.PP
If you change this value to \f[CR]never\f[R] while Ghostty is not
running, the next Ghostty launch will NOT restore the window state.
.PP
If you change this value to \f[CR]default\f[R] 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\(cqt provide this information).
.PP
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.
.PP
The default value is \f[CR]default\f[R].
.PP
This is currently only supported on macOS.
This has no effect on Linux.
.RE
.TP
\f[B]\f[CB]\-\-window\-step\-resize\f[B]\f[R]
Resize the window in discrete increments of the focused surface\(cqs
cell size.
If this is disabled, surfaces are resized in pixel increments.
Currently only supported on macOS.
.TP
\f[B]\f[CB]\-\-window\-new\-tab\-position\f[B]\f[R]
The position where new tabs are created.
Valid values:
.RS
.IP \(bu 2
\f[CR]current\f[R] \- Insert the new tab after the currently focused
tab, or at the end if there are no focused tabs.
.IP \(bu 2
\f[CR]end\f[R] \- Insert the new tab at the end of the tab list.
.RE
.TP
\f[B]\f[CB]\-\-window\-show\-tab\-bar\f[B]\f[R]
Whether to show the tab bar.
.RS
.PP
Valid values:
.IP \(bu 2
\f[CR]always\f[R]
.RS 2
.PP
Always display the tab bar, even when there\(cqs only one tab.
.PP
Available since: 1.2.0
.RE
.IP \(bu 2
\f[CR]auto\f[R] \f[I](default)\f[R]
.RS 2
.PP
Automatically show and hide the tab bar.
The tab bar is only shown when there are two or more tabs present.
.RE
.IP \(bu 2
\f[CR]never\f[R]
.RS 2
.PP
Never show the tab bar.
Tabs are only accessible via the tab overview or by keybind actions.
.RE
.PP
Currently only supported on Linux (GTK).
.RE
.TP
\f[B]\f[CB]\-\-window\-titlebar\-background\f[B]\f[R]
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.
.RS
.PP
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
.RE
.TP
\f[B]\f[CB]\-\-window\-titlebar\-foreground\f[B]\f[R]
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.
.RS
.PP
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
.RE
.TP
\f[B]\f[CB]\-\-resize\-overlay\f[B]\f[R]
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:
.RS
.IP \(bu 2
\f[CR]always\f[R] \- Always show resize overlays.
.IP \(bu 2
\f[CR]never\f[R] \- Never show resize overlays.
.IP \(bu 2
\f[CR]after\-first\f[R] \- The resize overlay will not appear when the
surface is first created, but will show up if the surface is
subsequently resized.
.PP
The default is \f[CR]after\-first\f[R].
.RE
.TP
\f[B]\f[CB]\-\-resize\-overlay\-position\f[B]\f[R]
If resize overlays are enabled, this controls the position of the
overlay.
The possible options are:
.RS
.IP \(bu 2
\f[CR]center\f[R]
.IP \(bu 2
\f[CR]top\-left\f[R]
.IP \(bu 2
\f[CR]top\-center\f[R]
.IP \(bu 2
\f[CR]top\-right\f[R]
.IP \(bu 2
\f[CR]bottom\-left\f[R]
.IP \(bu 2
\f[CR]bottom\-center\f[R]
.IP \(bu 2
\f[CR]bottom\-right\f[R]
.PP
The default is \f[CR]center\f[R].
.RE
.TP
\f[B]\f[CB]\-\-resize\-overlay\-duration\f[B]\f[R]
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.
.RS
.PP
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.
.PP
The allowed time units are as follows:
.IP \(bu 2
\f[CR]y\f[R] \- 365 SI days, or 8760 hours, or 31536000 seconds.
No adjustments are made for leap years or leap seconds.
.IP \(bu 2
\f[CR]d\f[R] \- one SI day, or 86400 seconds.
.IP \(bu 2
\f[CR]h\f[R] \- one hour, or 3600 seconds.
.IP \(bu 2
\f[CR]m\f[R] \- one minute, or 60 seconds.
.IP \(bu 2
\f[CR]s\f[R] \- one second.
.IP \(bu 2
\f[CR]ms\f[R] \- one millisecond, or 0.001 second.
.IP \(bu 2
\f[CR]us\f[R] or \f[CR]µs\f[R] \- one microsecond, or 0.000001 second.
.IP \(bu 2
\f[CR]ns\f[R] \- one nanosecond, or 0.000000001 second.
.PP
Examples: * \f[CR]1h30m\f[R] * \f[CR]45s\f[R]
.PP
Units can be repeated and will be added together.
This means that \f[CR]1h1h\f[R] is equivalent to \f[CR]2h\f[R].
This is confusing and should be avoided.
A future update may disallow this.
.PP
The maximum value is \f[CR]584y 49w 23h 34m 33s 709ms 551µs 615ns\f[R].
Any value larger than this will be clamped to the maximum value.
.PP
Available since 1.0.0
.RE
.TP
\f[B]\f[CB]\-\-focus\-follows\-mouse\f[B]\f[R]
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.
.RS
.PP
Default is false.
.RE
.TP
\f[B]\f[CB]\-\-clipboard\-read\f[B]\f[R]
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.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]ask\f[R]
.IP \(bu 2
\f[CR]allow\f[R]
.IP \(bu 2
\f[CR]deny\f[R]
.RE
.PP
\f[B]\f[CB]\-\-clipboard\-write\f[B]\f[R]
.TP
\f[B]\f[CB]\-\-clipboard\-trim\-trailing\-spaces\f[B]\f[R]
Trims trailing whitespace on data that is copied to the clipboard.
This does not affect data sent to the clipboard via
\f[CR]clipboard\-write\f[R].
This only applies to trailing whitespace on lines that have other
characters.
Completely blank lines always have their whitespace trimmed.
.TP
\f[B]\f[CB]\-\-clipboard\-paste\-protection\f[B]\f[R]
Require confirmation before pasting text that appears unsafe.
This helps prevent a \(lqcopy/paste attack\(rq where a user may
accidentally execute unsafe commands by pasting text with newlines.
.TP
\f[B]\f[CB]\-\-clipboard\-paste\-bracketed\-safe\f[B]\f[R]
If true, bracketed pastes will be considered safe.
By default, bracketed pastes are considered safe.
\(lqBracketed\(rq pastes are pastes while the running program has
bracketed paste mode enabled (a setting set by the running program, not
the terminal emulator).
.TP
\f[B]\f[CB]\-\-title\-report\f[B]\f[R]
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.
.RS
.PP
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).
.PP
Available since: 1.0.1
.RE
.TP
\f[B]\f[CB]\-\-image\-storage\-limit\f[B]\f[R]
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.
.RS
.PP
This value is separate for primary and alternate screens so the
effective limit per surface is double.
.RE
.TP
\f[B]\f[CB]\-\-copy\-on\-select\f[B]\f[R]
Whether to automatically copy selected text to the clipboard.
\f[CR]true\f[R] will prefer to copy to the selection clipboard,
otherwise it will copy to the system clipboard.
.RS
.PP
The value \f[CR]clipboard\f[R] will always copy text to the selection
clipboard as well as the system clipboard.
.PP
Middle\-click paste will always use the selection clipboard.
Middle\-click paste is always enabled even if this is \f[CR]false\f[R].
.PP
The default value is true on Linux and macOS.
.RE
.TP
\f[B]\f[CB]\-\-right\-click\-action\f[B]\f[R]
The action to take when the user right\-clicks on the terminal surface.
.RS
.PP
Valid values: * \f[CR]context\-menu\f[R] \- Show the context menu.
* \f[CR]paste\f[R] \- Paste the contents of the clipboard.
* \f[CR]copy\f[R] \- Copy the selected text to the clipboard.
* \f[CR]copy\-or\-paste\f[R] \- If there is a selection, copy the
selected text to the clipboard; otherwise, paste the contents of the
clipboard.
* \f[CR]ignore\f[R] \- Do nothing, ignore the right\-click.
.PP
The default value is \f[CR]context\-menu\f[R].
.RE
.TP
\f[B]\f[CB]\-\-click\-repeat\-interval\f[B]\f[R]
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.
.TP
\f[B]\f[CB]\-\-config\-file\f[B]\f[R]
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 \f[CR]config\-file\f[R]
directive.
For command\-line arguments, paths are relative to the current working
directory.
.RS
.PP
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 (\(lq).
.PP
Cycles are not allowed.
If a cycle is detected, an error will be logged and the configuration
file will be ignored.
.PP
Configuration files are loaded after the configuration they\(cqre
defined within in the order they\(cqre defined.
\f[B]THIS IS A VERY SUBTLE BUT IMPORTANT POINT.\f[R] To put it another
way: configuration files do not take effect until after the entire
configuration is loaded.
For example, in the configuration below:
.IP
.EX
config\-file = \(dqfoo\(dq
a = 1
.EE
.PP
If \(lqfoo\(rq contains \f[CR]a = 2\f[R], the final value of
\f[CR]a\f[R] will be 2, because \f[CR]foo\f[R] is loaded after the
configuration file that configures the nested \f[CR]config\-file\f[R]
value.
.RE
.TP
\f[B]\f[CB]\-\-config\-default\-files\f[B]\f[R]
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).
.RS
.PP
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.
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-confirm\-close\-surface\f[B]\f[R]
Confirms that a surface should be closed before closing it.
.RS
.PP
This defaults to \f[CR]true\f[R].
If set to \f[CR]false\f[R], surfaces will close without any
confirmation.
This can also be set to \f[CR]always\f[R], which will always confirm
closing a surface, even if shell integration says a process isn\(cqt
running.
.RE
.TP
\f[B]\f[CB]\-\-quit\-after\-last\-window\-closed\f[B]\f[R]
Whether or not to quit after the last surface is closed.
.RS
.PP
This defaults to \f[CR]false\f[R] on macOS since that is standard
behavior for a macOS application.
On Linux, this defaults to \f[CR]true\f[R] since that is generally
expected behavior.
.PP
On Linux, if this is \f[CR]true\f[R], Ghostty can delay quitting fully
until a configurable amount of time has passed after the last window is
closed.
See the documentation of
\f[CR]quit\-after\-last\-window\-closed\-delay\f[R].
.RE
.TP
\f[B]\f[CB]\-\-quit\-after\-last\-window\-closed\-delay\f[B]\f[R]
Controls how long Ghostty will stay running after the last open surface
has been closed.
This only has an effect if \f[CR]quit\-after\-last\-window\-closed\f[R]
is also set to \f[CR]true\f[R].
.RS
.PP
The minimum value for this configuration is \f[CR]1s\f[R].
Any values lower than this will be clamped to \f[CR]1s\f[R].
.PP
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.
.PP
The allowed time units are as follows:
.IP \(bu 2
\f[CR]y\f[R] \- 365 SI days, or 8760 hours, or 31536000 seconds.
No adjustments are made for leap years or leap seconds.
.IP \(bu 2
\f[CR]d\f[R] \- one SI day, or 86400 seconds.
.IP \(bu 2
\f[CR]h\f[R] \- one hour, or 3600 seconds.
.IP \(bu 2
\f[CR]m\f[R] \- one minute, or 60 seconds.
.IP \(bu 2
\f[CR]s\f[R] \- one second.
.IP \(bu 2
\f[CR]ms\f[R] \- one millisecond, or 0.001 second.
.IP \(bu 2
\f[CR]us\f[R] or \f[CR]µs\f[R] \- one microsecond, or 0.000001 second.
.IP \(bu 2
\f[CR]ns\f[R] \- one nanosecond, or 0.000000001 second.
.PP
Examples: * \f[CR]1h30m\f[R] * \f[CR]45s\f[R]
.PP
Units can be repeated and will be added together.
This means that \f[CR]1h1h\f[R] is equivalent to \f[CR]2h\f[R].
This is confusing and should be avoided.
A future update may disallow this.
.PP
The maximum value is \f[CR]584y 49w 23h 34m 33s 709ms 551µs 615ns\f[R].
Any value larger than this will be clamped to the maximum value.
.PP
By default \f[CR]quit\-after\-last\-window\-closed\-delay\f[R] is unset
and Ghostty will quit immediately after the last window is closed if
\f[CR]quit\-after\-last\-window\-closed\f[R] is \f[CR]true\f[R].
.PP
Only implemented on Linux.
.RE
.TP
\f[B]\f[CB]\-\-initial\-window\f[B]\f[R]
This controls whether an initial window is created when Ghostty is run.
Note that if \f[CR]quit\-after\-last\-window\-closed\f[R] is
\f[CR]true\f[R] and \f[CR]quit\-after\-last\-window\-closed\-delay\f[R]
is set, setting \f[CR]initial\-window\f[R] to \f[CR]false\f[R] will mean
that Ghostty will quit after the configured delay if no window is ever
created.
Only implemented on Linux and macOS.
.TP
\f[B]\f[CB]\-\-undo\-timeout\f[B]\f[R]
The duration that undo operations remain available.
After this time, the operation will be removed from the undo stack and
cannot be undone.
.RS
.PP
The default value is 5 seconds.
.PP
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.
.PP
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.
.PP
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.
.PP
The allowed time units are as follows:
.IP \(bu 2
\f[CR]y\f[R] \- 365 SI days, or 8760 hours, or 31536000 seconds.
No adjustments are made for leap years or leap seconds.
.IP \(bu 2
\f[CR]d\f[R] \- one SI day, or 86400 seconds.
.IP \(bu 2
\f[CR]h\f[R] \- one hour, or 3600 seconds.
.IP \(bu 2
\f[CR]m\f[R] \- one minute, or 60 seconds.
.IP \(bu 2
\f[CR]s\f[R] \- one second.
.IP \(bu 2
\f[CR]ms\f[R] \- one millisecond, or 0.001 second.
.IP \(bu 2
\f[CR]us\f[R] or \f[CR]µs\f[R] \- one microsecond, or 0.000001 second.
.IP \(bu 2
\f[CR]ns\f[R] \- one nanosecond, or 0.000000001 second.
.PP
Examples: * \f[CR]1h30m\f[R] * \f[CR]45s\f[R]
.PP
Units can be repeated and will be added together.
This means that \f[CR]1h1h\f[R] is equivalent to \f[CR]2h\f[R].
This is confusing and should be avoided.
A future update may disallow this.
.PP
This configuration is only supported on macOS.
Linux doesn\(cqt support undo operations at all so this configuration
has no effect.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-quick\-terminal\-position\f[B]\f[R]
The position of the \(lqquick\(rq terminal window.
To learn more about the quick terminal, see the documentation for the
\f[CR]toggle_quick_terminal\f[R] binding action.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]top\f[R] \- Terminal appears at the top of the screen.
.IP \(bu 2
\f[CR]bottom\f[R] \- Terminal appears at the bottom of the screen.
.IP \(bu 2
\f[CR]left\f[R] \- Terminal appears at the left of the screen.
.IP \(bu 2
\f[CR]right\f[R] \- Terminal appears at the right of the screen.
.IP \(bu 2
\f[CR]center\f[R] \- Terminal appears at the center of the screen.
.PP
On macOS, changing this configuration requires restarting Ghostty
completely.
.PP
Note: There is no default keybind for toggling the quick terminal.
To enable this feature, bind the \f[CR]toggle_quick_terminal\f[R] action
to a key.
.RE
.TP
\f[B]\f[CB]\-\-quick\-terminal\-size\f[B]\f[R]
The size of the quick terminal.
.RS
.PP
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 \f[CR]%\f[R] (e.g.\ \f[CR]20%\f[R])
while pixel values are suffixed with \f[CR]px\f[R]
(e.g.\ \f[CR]300px\f[R]).
A bare value without a suffix is a config error.
.PP
When only one size is specified, the size parameter affects the size of
the quick terminal on its \f[I]primary axis\f[R], 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\(cqs orientation: height when on a landscape monitor, and width
when on a portrait monitor.
.PP
The \f[I]secondary axis\f[R] would be maximized for non\-center
positioned quick terminals unless another size parameter is specified,
separated from the first by a comma (\f[CR],\f[R]).
Percentage and pixel sizes can be mixed together: for instance, a size
of \f[CR]50%,500px\f[R] for a top\-positioned quick terminal would be
half a screen tall, and 500 pixels wide.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-gtk\-quick\-terminal\-layer\f[B]\f[R]
The layer of the quick terminal window.
The higher the layer, the more windows the quick terminal may conceal.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]overlay\f[R]
.RS 2
.PP
The quick terminal appears in front of all windows.
.RE
.IP \(bu 2
\f[CR]top\f[R] (default)
.RS 2
.PP
The quick terminal appears in front of normal windows but behind
fullscreen overlays like lock screens.
.RE
.IP \(bu 2
\f[CR]bottom\f[R]
.RS 2
.PP
The quick terminal appears behind normal windows but in front of
wallpapers and other windows in the background layer.
.RE
.IP \(bu 2
\f[CR]background\f[R]
.RS 2
.PP
The quick terminal appears behind all windows.
.RE
.PP
GTK Wayland only.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-gtk\-quick\-terminal\-namespace\f[B]\f[R]
The namespace for the quick terminal window.
.RS
.PP
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.
.PP
GTK Wayland only.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-quick\-terminal\-screen\f[B]\f[R]
The screen where the quick terminal should show up.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]main\f[R] \- 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.
.IP \(bu 2
\f[CR]mouse\f[R] \- The screen that the mouse is currently hovered over.
.IP \(bu 2
\f[CR]macos\-menu\-bar\f[R] \- 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.
.PP
The default value is \f[CR]main\f[R] because this is the recommended
screen by the operating system.
.PP
Only implemented on macOS.
.RE
.TP
\f[B]\f[CB]\-\-quick\-terminal\-animation\-duration\f[B]\f[R]
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.
.RS
.PP
Only implemented on macOS.
.RE
.TP
\f[B]\f[CB]\-\-quick\-terminal\-autohide\f[B]\f[R]
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.
.RS
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-quick\-terminal\-space\-behavior\f[B]\f[R]
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.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]move\f[R] \- When switching to another space, the quick terminal
will also moved to the current space.
.IP \(bu 2
\f[CR]remain\f[R] \- The quick terminal will stay only in the space
where it was originally opened and will not follow when switching to
another space.
.PP
The default value is \f[CR]move\f[R].
.PP
Only implemented on macOS.
On Linux the behavior is always equivalent to \f[CR]move\f[R].
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-quick\-terminal\-keyboard\-interactivity\f[B]\f[R]
Determines under which circumstances that the quick terminal should
receive keyboard input.
See the corresponding \c
.UR https://wayland.app/protocols/wlr-layer-shell-unstable-v1#zwlr_layer_surface_v1:enum:keyboard_interactivity
Wayland documentation
.UE \c
\ for a more detailed explanation of the behavior of each option.
.RS
.RS
.PP
[!NOTE] The exact behavior of each option may differ significantly
across compositors \(en experiment with them on your system to find one
that suits your liking!
.RE
.PP
Valid values are:
.IP \(bu 2
\f[CR]none\f[R]
.RS 2
.PP
The quick terminal will not receive any keyboard input.
.RE
.IP \(bu 2
\f[CR]on\-demand\f[R] (default)
.RS 2
.PP
The quick terminal would only receive keyboard input when it is focused.
.RE
.IP \(bu 2
\f[CR]exclusive\f[R]
.RS 2
.PP
The quick terminal will always receive keyboard input, even when another
window is currently focused.
.RE
.PP
Only has an effect on Linux Wayland.
On macOS the behavior is always equivalent to \f[CR]on\-demand\f[R].
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-shell\-integration\f[B]\f[R]
Whether to enable shell integration auto\-injection or not.
Shell integration greatly enhances the terminal experience by enabling a
number of features:
.RS
.IP \(bu 2
Working directory reporting so new tabs, splits inherit the previous
terminal\(cqs working directory.
.IP \(bu 2
Prompt marking that enables the \(lqjump_to_prompt\(rq keybinding.
.IP \(bu 2
If you\(cqre sitting at a prompt, closing a terminal will not ask for
confirmation.
.IP \(bu 2
Resizing the window with a complex prompt usually paints much better.
.PP
Allowable values are:
.IP \(bu 2
\f[CR]none\f[R] \- Do not do any automatic injection.
You can still manually configure your shell to enable the integration.
.IP \(bu 2
\f[CR]detect\f[R] \- Detect the shell based on the filename.
.IP \(bu 2
\f[CR]bash\f[R], \f[CR]elvish\f[R], \f[CR]fish\f[R], \f[CR]nushell\f[R],
\f[CR]zsh\f[R] \- Use this specific shell injection scheme.
.PP
The default value is \f[CR]detect\f[R].
.RE
.TP
\f[B]\f[CB]\-\-shell\-integration\-features\f[B]\f[R]
Shell integration features to enable.
These require our shell integration to be loaded, either automatically
via shell\-integration or manually.
.RS
.PP
The format of this is a list of features to enable separated by commas.
If you prefix a feature with \f[CR]no\-\f[R] then it is disabled.
If you omit a feature, its default value is used, so you must explicitly
disable features you don\(cqt want.
You can also use \f[CR]true\f[R] or \f[CR]false\f[R] to turn all
features on or off.
.PP
Example: \f[CR]cursor\f[R], \f[CR]no\-cursor\f[R], \f[CR]sudo\f[R],
\f[CR]no\-sudo\f[R], \f[CR]title\f[R], \f[CR]no\-title\f[R]
.PP
Available features:
.IP \(bu 2
\f[CR]cursor\f[R] \- Set the cursor to a bar at the prompt.
.IP \(bu 2
\f[CR]sudo\f[R] \- Set sudo wrapper to preserve terminfo.
.IP \(bu 2
\f[CR]title\f[R] \- Set the window title via shell integration.
.IP \(bu 2
\f[CR]ssh\-env\f[R] \- Enable SSH environment variable compatibility.
Automatically converts TERM from \f[CR]xterm\-ghostty\f[R] to
\f[CR]xterm\-256color\f[R] 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)
.IP \(bu 2
\f[CR]ssh\-terminfo\f[R] \- Enable automatic terminfo installation on
remote hosts.
Attempts to install Ghostty\(cqs terminfo entry using \f[CR]infocmp\f[R]
and \f[CR]tic\f[R] when connecting to hosts that lack it.
Requires \f[CR]infocmp\f[R] to be available locally and \f[CR]tic\f[R]
to be available on remote hosts.
Once terminfo is installed on a remote host, it will be automatically
\(lqcached\(rq to avoid repeat installations.
If desired, the \f[CR]+ssh\-cache\f[R] CLI action can be used to manage
the installation cache manually using various arguments.
(Available since: 1.2.0)
.IP \(bu 2
\f[CR]path\f[R] \- Add Ghostty\(cqs binary directory to PATH.
This ensures the \f[CR]ghostty\f[R] 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.
.PP
SSH features work independently and can be combined for optimal
experience: when both \f[CR]ssh\-env\f[R] and \f[CR]ssh\-terminfo\f[R]
are enabled, Ghostty will install its terminfo on remote hosts and use
\f[CR]xterm\-ghostty\f[R] as TERM, falling back to
\f[CR]xterm\-256color\f[R] with environment variables if terminfo
installation fails.
.RE
.TP
\f[B]\f[CB]\-\-command\-palette\-entry\f[B]\f[R]
Custom entries into the command palette.
.RS
.PP
Each entry requires the title, the corresponding action, and an optional
description.
Each field should be prefixed with the field name, a colon
(\f[CR]:\f[R]), and then the specified value.
The syntax for actions is identical to the one for keybind actions.
Whitespace in between fields is ignored.
.PP
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 \c
.UR https://ziglang.org/documentation/master/#Escape-Sequences
Zig documentation
.UE \c
\ for more information on string literals.
Note that multiline string literals are not supported.
.PP
Double quotes can not be used around the field names.
.IP
.EX
command\-palette\-entry = title:Reset Font Style, action:csi:0m
command\-palette\-entry = title:Crash on Main Thread,description:Causes a crash on the main (UI) thread.,action:crash:main
command\-palette\-entry = title:Focus Split: Right,description:\(dqFocus the split to the right, if it exists.\(dq,action:goto_split:right
command\-palette\-entry = title:\(dqGhostty\(dq,description:\(dqAdd a little Ghostty to your terminal.\(dq,action:\(dqtext:\(rsxf0\(rsx9f\(rsx91\(rsxbb\(dq
.EE
.PP
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:
.IP
.EX
command\-palette\-entry =
.EE
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-osc\-color\-report\-format\f[B]\f[R]
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.
.RS
.PP
Allowable values are:
.IP \(bu 2
\f[CR]none\f[R] \- OSC 4/10/11 queries receive no reply
.IP \(bu 2
\f[CR]8\-bit\f[R] \- Color components are return unscaled,
e.g.\ \f[CR]rr/gg/bb\f[R]
.IP \(bu 2
\f[CR]16\-bit\f[R] \- Color components are returned scaled,
e.g.\ \f[CR]rrrr/gggg/bbbb\f[R]
.PP
The default value is \f[CR]16\-bit\f[R].
.RE
.TP
\f[B]\f[CB]\-\-vt\-kam\-allowed\f[B]\f[R]
If true, allows the \(lqKAM\(rq 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\(cqt know if you need KAM, you don\(cqt need it.
.TP
\f[B]\f[CB]\-\-custom\-shader\f[B]\f[R]
Custom shaders to run after the default shaders.
This is a file path to a GLSL\-syntax shader for all platforms.
.RS
.PP
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.
.PP
Custom shader support is based on and compatible with the Shadertoy
shaders.
Shaders should specify a \f[CR]mainImage\f[R] function and the available
uniforms largely match Shadertoy, with some caveats and
Ghostty\-specific extensions.
.PP
The uniform values available to shaders are as follows:
.IP \(bu 2
\f[CR]sampler2D iChannel0\f[R] \- Input texture.
.RS 2
.PP
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.
.RE
.IP \(bu 2
\f[CR]vec3 iResolution\f[R] \- Output texture size,
\f[CR][width, height, 1]\f[R] (in px).
.IP \(bu 2
\f[CR]float iTime\f[R] \- Time in seconds since first frame was
rendered.
.IP \(bu 2
\f[CR]float iTimeDelta\f[R] \- Time in seconds since previous frame was
rendered.
.IP \(bu 2
\f[CR]float iFrameRate\f[R] \- Average framerate.
(NOT CURRENTLY SUPPORTED)
.IP \(bu 2
\f[CR]int iFrame\f[R] \- Number of frames that have been rendered so
far.
.IP \(bu 2
\f[CR]float iChannelTime[4]\f[R] \- Current time for video or sound
input.
(N/A)
.IP \(bu 2
\f[CR]vec3 iChannelResolution[4]\f[R] \- Resolutions of the 4 input
samplers.
.RS 2
.PP
Currently only \f[CR]iChannel0\f[R] exists, and
\f[CR]iChannelResolution[0]\f[R] is identical to \f[CR]iResolution\f[R].
.RE
.IP \(bu 2
\f[CR]vec4 iMouse\f[R] \- Mouse input info.
(NOT CURRENTLY SUPPORTED)
.IP \(bu 2
\f[CR]vec4 iDate\f[R] \- Date/time info.
(NOT CURRENTLY SUPPORTED)
.IP \(bu 2
\f[CR]float iSampleRate\f[R] \- Sample rate for audio.
(N/A)
.PP
Ghostty\-specific extensions:
.IP \(bu 2
\f[CR]vec4 iCurrentCursor\f[R] \- Info about the terminal cursor.
.RS 2
.IP \(bu 2
\f[CR]iCurrentCursor.xy\f[R] is the \-X, +Y corner of the current
cursor.
.IP \(bu 2
\f[CR]iCurrentCursor.zw\f[R] is the width and height of the current
cursor.
.RE
.IP \(bu 2
\f[CR]vec4 iPreviousCursor\f[R] \- Info about the previous terminal
cursor.
.IP \(bu 2
\f[CR]vec4 iCurrentCursorColor\f[R] \- Color of the terminal cursor.
.IP \(bu 2
\f[CR]vec4 iPreviousCursorColor\f[R] \- Color of the previous terminal
cursor.
.IP \(bu 2
\f[CR]vec4 iCurrentCursorStyle\f[R] \- Style of the terminal cursor
.RS 2
.PP
Macros simplified use are defined for the various cursor styles:
.IP \(bu 2
\f[CR]CURSORSTYLE_BLOCK\f[R] or \f[CR]0\f[R]
.IP \(bu 2
\f[CR]CURSORSTYLE_BLOCK_HOLLOW\f[R] or \f[CR]1\f[R]
.IP \(bu 2
\f[CR]CURSORSTYLE_BAR\f[R] or \f[CR]2\f[R]
.IP \(bu 2
\f[CR]CURSORSTYLE_UNDERLINE\f[R] or \f[CR]3\f[R]
.IP \(bu 2
\f[CR]CURSORSTYLE_LOCK\f[R] or \f[CR]4\f[R]
.RE
.IP \(bu 2
\f[CR]vec4 iPreviousCursorStyle\f[R] \- Style of the previous terminal
cursor
.IP \(bu 2
\f[CR]vec4 iCursorVisible\f[R] \- Visibility of the terminal cursor.
.IP \(bu 2
\f[CR]float iTimeCursorChange\f[R] \- Timestamp of terminal cursor
change.
.RS 2
.PP
When the terminal cursor changes position or color, this is set to the
same time as the \f[CR]iTime\f[R] uniform, allowing you to compute the
time since the change by subtracting this from \f[CR]iTime\f[R].
.RE
.IP \(bu 2
\f[CR]float iTimeFocus\f[R] \- Timestamp when the surface last gained
iFocus.
.RS 2
.PP
When the surface gains focus, this is set to the current value of
\f[CR]iTime\f[R], similar to how \f[CR]iTimeCursorChange\f[R] works.
This allows you to compute the time since focus was gained or lost by
calculating \f[CR]iTime \- iTimeFocus\f[R].
Use this to create animations that restart when the terminal regains
focus.
.RE
.IP \(bu 2
\f[CR]int iFocus\f[R] \- Current focus state of the surface.
.RS 2
.PP
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 \(lqdeceptive
frames\(rq (e.g., modifier key presses, link hover events in unfocused
split panes).
Check \f[CR]iFocus > 0\f[R] to determine if the surface is currently
focused.
.RE
.IP \(bu 2
\f[CR]vec3 iPalette[256]\f[R] \- The 256\-color terminal palette.
.RS 2
.PP
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.
.RE
.IP \(bu 2
\f[CR]vec3 iBackgroundColor\f[R] \- Terminal background color (RGB).
.IP \(bu 2
\f[CR]vec3 iForegroundColor\f[R] \- Terminal foreground color (RGB).
.IP \(bu 2
\f[CR]vec3 iCursorColor\f[R] \- Terminal cursor color (RGB).
.IP \(bu 2
\f[CR]vec3 iCursorText\f[R] \- Terminal cursor text color (RGB).
.IP \(bu 2
\f[CR]vec3 iSelectionBackgroundColor\f[R] \- Selection background color
(RGB).
.IP \(bu 2
\f[CR]vec3 iSelectionForegroundColor\f[R] \- Selection foreground color
(RGB).
.PP
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 \c
.UR https://shadertoy.com
shadertoy.com
.UE \c
\&.
.PP
This can be repeated multiple times to load multiple shaders.
The shaders will be run in the order they are specified.
.PP
This can be changed at runtime and will affect all open terminals.
.RE
.TP
\f[B]\f[CB]\-\-custom\-shader\-animation\f[B]\f[R]
If \f[CR]true\f[R] (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.
.RS
.PP
If this is set to \f[CR]false\f[R], the terminal and custom shader will
only render when the terminal is updated.
This is more efficient but the shader will not animate.
.PP
This can also be set to \f[CR]always\f[R], 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.
.PP
This can be changed at runtime and will affect all open terminals.
.RE
.TP
\f[B]\f[CB]\-\-bell\-features\f[B]\f[R]
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 \f[CR]no\-\f[R] then it is disabled.
If you omit a feature, its default value is used.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]system\f[R]
.RS 2
.PP
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 \(lqSound > Alert Sound\(rq setting in GNOME, or the
\(lqAccessibility > System Bell\(rq settings in KDE Plasma.
.PP
On macOS, this plays the system alert sound.
.RE
.IP \(bu 2
\f[CR]audio\f[R]
.RS 2
.PP
Play a custom sound.
(Available since 1.3.0 on macOS)
.RE
.IP \(bu 2
\f[CR]attention\f[R] \f[I](enabled by default)\f[R]
.RS 2
.PP
Request the user\(cqs 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:
.IP \(bu 2
On KDE, the background of the desktop icon in the task bar would be
highlighted;
.IP \(bu 2
On GNOME, you may receive a notification that, when clicked, would bring
the Ghostty window into focus;
.IP \(bu 2
On Sway, the window may be decorated with a distinctly colored border;
.IP \(bu 2
On other systems this may have no effect at all.
.RE
.IP \(bu 2
\f[CR]title\f[R] \f[I](enabled by default)\f[R]
.RS 2
.PP
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).
.RE
.IP \(bu 2
\f[CR]border\f[R]
.RS 2
.PP
Display a border around the alerted surface until the terminal is
re\-focused or interacted with (such as on keyboard input).
.PP
Available since: 1.2.0 on GTK, 1.2.1 on macOS
.RE
.PP
Example: \f[CR]audio\f[R], \f[CR]no\-audio\f[R], \f[CR]system\f[R],
\f[CR]no\-system\f[R]
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-bell\-audio\-path\f[B]\f[R]
If \f[CR]audio\f[R] 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 \f[CR]\(ti/\f[R] to reference the
user\(cqs home directory.
.RS
.PP
Available since: 1.2.0 on GTK, 1.3.0 on macOS.
.RE
.TP
\f[B]\f[CB]\-\-bell\-audio\-volume\f[B]\f[R]
If \f[CR]audio\f[R] 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.
.RS
.PP
Available since: 1.2.0 on GTK, 1.3.0 on macOS.
.RE
.TP
\f[B]\f[CB]\-\-app\-notifications\f[B]\f[R]
Control the in\-app notifications that Ghostty shows.
.RS
.PP
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.
.PP
Possible notifications are:
.IP \(bu 2
\f[CR]clipboard\-copy\f[R] (default: true) \- Show a notification when
text is copied to the clipboard.
.IP \(bu 2
\f[CR]config\-reload\f[R] (default: true) \- Show a notification when
the configuration is reloaded.
.PP
To specify a notification to enable, specify the name of the
notification.
To specify a notification to disable, prefix the name with
\f[CR]no\-\f[R].
For example, to disable \f[CR]clipboard\-copy\f[R], set this
configuration to \f[CR]no\-clipboard\-copy\f[R].
To enable it, set this configuration to \f[CR]clipboard\-copy\f[R].
.PP
Multiple notifications can be enabled or disabled by separating them
with a comma.
.PP
A value of \(lqfalse\(rq will disable all notifications.
A value of \(lqtrue\(rq will enable all notifications.
.PP
This configuration only applies to GTK.
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-macos\-non\-native\-fullscreen\f[B]\f[R]
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\(cqs faster than the native fullscreen mode since it doesn\(cqt use
animations.
.RS
.PP
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.
.PP
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.
.PP
Allowable values are:
.IP \(bu 2
\f[CR]true\f[R] \- Use non\-native macOS fullscreen, hide the menu bar
.IP \(bu 2
\f[CR]false\f[R] \- Use native macOS fullscreen
.IP \(bu 2
\f[CR]visible\-menu\f[R] \- Use non\-native macOS fullscreen, keep the
menu bar visible
.IP \(bu 2
\f[CR]padded\-notch\f[R] \- 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.
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-macos\-window\-buttons\f[B]\f[R]
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.
.RS
.PP
This setting has no effect when \f[CR]window\-decoration = none\f[R] or
\f[CR]macos\-titlebar\-style = hidden\f[R], as the window buttons are
always hidden in these modes.
.PP
Valid values are:
.IP \(bu 2
\f[CR]visible\f[R] \- Show the window buttons.
.IP \(bu 2
\f[CR]hidden\f[R] \- Hide the window buttons.
.PP
The default value is \f[CR]visible\f[R].
.PP
Changing this option at runtime only applies to new windows.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-macos\-titlebar\-style\f[B]\f[R]
The style of the macOS titlebar.
Available values are: \(lqnative\(rq, \(lqtransparent\(rq, \(lqtabs\(rq,
and \(lqhidden\(rq.
.RS
.PP
The \(lqnative\(rq style uses the native macOS titlebar with zero
customization.
The titlebar will match your window theme (see
\f[CR]window\-theme\f[R]).
.PP
The \(lqtransparent\(rq style is the same as \(lqnative\(rq 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.
.PP
The \(lqtransparent\(rq 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\(cqt match.
.PP
The \(lqtabs\(rq 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.
.PP
The \(lqhidden\(rq style hides the titlebar.
Unlike \f[CR]window\-decoration = none\f[R], 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.
.PP
When \(lqhidden\(rq, 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.
.PP
The default value is \(lqtransparent\(rq.
This is an opinionated choice but its one I think is the most
aesthetically pleasing and works in most cases.
.PP
Changing this option at runtime only applies to new windows.
.RE
.TP
\f[B]\f[CB]\-\-macos\-titlebar\-proxy\-icon\f[B]\f[R]
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.
.RS
.PP
The proxy icon is only visible with the native macOS titlebar style.
.PP
Valid values are:
.IP \(bu 2
\f[CR]visible\f[R] \- Show the proxy icon.
.IP \(bu 2
\f[CR]hidden\f[R] \- Hide the proxy icon.
.PP
The default value is \f[CR]visible\f[R].
.PP
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 \f[CR]cd\f[R] to a different directory, open a different file in
an editor, etc.
.RE
.TP
\f[B]\f[CB]\-\-macos\-dock\-drop\-behavior\f[B]\f[R]
Controls the windowing behavior when dropping a file or folder onto the
Ghostty icon in the macOS dock.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]new\-tab\f[R] \- Create a new tab in the current window, or open a
new window if none exist.
.IP \(bu 2
\f[CR]new\-window\f[R] \- Create a new window unconditionally.
.PP
The default value is \f[CR]new\-tab\f[R].
.PP
This setting is only supported on macOS and has no effect on other
platforms.
.RE
.TP
\f[B]\f[CB]\-\-macos\-option\-as\-alt\f[B]\f[R]
macOS doesn\(cqt have a distinct \(lqalt\(rq key and instead has the
\(lqoption\(rq 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 \(lq∫\(rq.
This may be undesirable if you want to use \(lqoption\(rq as an
\(lqalt\(rq key for keybindings in terminal programs or shells.
.RS
.PP
This configuration lets you change the behavior so that option is
treated as alt.
.PP
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 \(lqtrue\(rq.
Otherwise, the default value is \(lqfalse\(rq.
Keyboard layouts with a default value of \(lqtrue\(rq are:
.IP \(bu 2
U.S.
Standard
.IP \(bu 2
U.S.
International
.PP
Note that if an \f[I]Option\f[R]\-sequence doesn\(cqt produce a
printable character, it will be treated as \f[I]Alt\f[R] regardless of
this setting.
(e.g.\ \f[CR]alt+ctrl+a\f[R]).
.PP
Explicit values that can be set:
.PP
If \f[CR]true\f[R], the \f[I]Option\f[R] key will be treated as
\f[I]Alt\f[R].
This makes terminal sequences expecting \f[I]Alt\f[R] to work properly,
but will break Unicode input sequences on macOS if you use them via the
\f[I]Alt\f[R] key.
.PP
You may set this to \f[CR]false\f[R] to restore the macOS \f[I]Alt\f[R]
key unicode sequences but this will break terminal sequences expecting
\f[I]Alt\f[R] to work.
.PP
The values \f[CR]left\f[R] or \f[CR]right\f[R] enable this for the left
or right \f[I]Option\f[R] key, respectively.
.RE
.TP
\f[B]\f[CB]\-\-macos\-window\-shadow\f[B]\f[R]
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.
.TP
\f[B]\f[CB]\-\-macos\-hidden\f[B]\f[R]
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.
.RS
.PP
Note that setting this to true means that keyboard layout changes will
no longer be automatic.
.PP
Control whether macOS app is excluded from the dock and app switcher, a
\(lqhidden\(rq state.
This is mainly intended for those primarily using quick\-terminal mode,
but is a general configuration for any use case.
.PP
Available values:
.IP \(bu 2
\f[CR]never\f[R] \- The macOS app is never hidden.
.IP \(bu 2
\f[CR]always\f[R] \- The macOS app is always hidden.
.PP
Note: When the macOS application is hidden, keyboard layout changes will
no longer be automatic.
This is a limitation of macOS.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-macos\-auto\-secure\-input\f[B]\f[R]
If true, Ghostty on macOS will automatically enable the \(lqSecure
Input\(rq feature when it detects that a password prompt is being
displayed.
.RS
.PP
\(lqSecure Input\(rq is a macOS security feature that prevents
applications from reading keyboard events.
This can always be enabled manually using the
\f[CR]Ghostty > Secure Keyboard Entry\f[R] menu item.
.PP
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\(cqt work.
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-macos\-secure\-input\-indication\f[B]\f[R]
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.
.RS
.PP
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.
.RE
.TP
\f[B]\f[CB]\-\-macos\-applescript\f[B]\f[R]
If true, Ghostty exposes and handles the built\-in AppleScript
dictionary on macOS.
.RS
.PP
If false, all AppleScript interactions are disabled.
This includes AppleScript commands and AppleScript object lookup for
windows, tabs, and terminals.
.PP
The default is true.
.RE
.TP
\f[B]\f[CB]\-\-macos\-icon\f[B]\f[R]
Customize the macOS app icon.
.RS
.PP
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\(cqt be changed
at runtime.
For more details on what exactly is affected, see the
\f[CR]NSApplication.icon\f[R] Apple documentation; that is the API that
is being used to set the icon.
.PP
Valid values:
.IP \(bu 2
\f[CR]official\f[R] \- Use the official Ghostty icon.
.IP \(bu 2
\f[CR]blueprint\f[R], \f[CR]chalkboard\f[R], \f[CR]microchip\f[R],
\f[CR]glass\f[R], \f[CR]holographic\f[R], \f[CR]paper\f[R],
\f[CR]retro\f[R], \f[CR]xray\f[R] \- Official variants of the Ghostty
icon hand\-created by artists (no AI).
.IP \(bu 2
\f[CR]custom\f[R] \- Use a completely custom icon.
The location must be specified using the additional
\f[CR]macos\-custom\-icon\f[R] configuration
.IP \(bu 2
\f[CR]custom\-style\f[R] \- Use the official Ghostty icon but with
custom styles applied to various layers.
The custom styles must be specified using the additional
\f[CR]macos\-icon\f[R]\-prefixed configurations.
The \f[CR]macos\-icon\-ghost\-color\f[R] and
\f[CR]macos\-icon\-screen\-color\f[R] configurations are required for
this style.
.PP
WARNING: The \f[CR]custom\-style\f[R] option is \f[I]experimental\f[R].
We may change the format of the custom styles in the future.
We\(cqre still finalizing the exact layers and customization options
that will be available.
.PP
Other caveats:
.IP \(bu 2
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.
.RE
.TP
\f[B]\f[CB]\-\-macos\-custom\-icon\f[B]\f[R]
The absolute path to the custom icon file.
Supported formats include PNG, JPEG, and ICNS.
.RS
.PP
Defaults to \f[CR]\(ti/.config/ghostty/Ghostty.icns\f[R]
.RE
.TP
\f[B]\f[CB]\-\-macos\-icon\-frame\f[B]\f[R]
The material to use for the frame of the macOS app icon.
.RS
.PP
Valid values:
.IP \(bu 2
\f[CR]aluminum\f[R] \- A brushed aluminum frame.
This is the default.
.IP \(bu 2
\f[CR]beige\f[R] \- A classic 90\(cqs computer beige frame.
.IP \(bu 2
\f[CR]plastic\f[R] \- A glossy, dark plastic frame.
.IP \(bu 2
\f[CR]chrome\f[R] \- A shiny chrome frame.
.PP
Note: This configuration is required when \f[CR]macos\-icon\f[R] is set
to \f[CR]custom\-style\f[R].
.RE
.TP
\f[B]\f[CB]\-\-macos\-icon\-ghost\-color\f[B]\f[R]
The color of the ghost in the macOS app icon.
.RS
.PP
Note: This configuration is required when \f[CR]macos\-icon\f[R] is set
to \f[CR]custom\-style\f[R].
.PP
Specified as either hex (\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or a
named X11 color.
.RE
.TP
\f[B]\f[CB]\-\-macos\-icon\-screen\-color\f[B]\f[R]
The color of the screen in the macOS app icon.
.RS
.PP
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
(\f[CR]#RRGGBB\f[R] or \f[CR]RRGGBB\f[R]) or as named X11 colors.
The first color is the bottom of the gradient and the last color is the
top of the gradient.
.PP
Note: This configuration is required when \f[CR]macos\-icon\f[R] is set
to \f[CR]custom\-style\f[R].
.RE
.TP
\f[B]\f[CB]\-\-macos\-shortcuts\f[B]\f[R]
Whether macOS Shortcuts are allowed to control Ghostty.
.RS
.PP
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.
.PP
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.
.PP
Valid values are:
.IP \(bu 2
\f[CR]ask\f[R] \- 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.
.IP \(bu 2
\f[CR]allow\f[R] \- Allow Shortcuts to control Ghostty without asking.
.IP \(bu 2
\f[CR]deny\f[R] \- Deny Shortcuts from controlling Ghostty.
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-linux\-cgroup\f[B]\f[R]
Put every surface (tab, split, window) into a transient
\f[CR]systemd\f[R] scope.
.RS
.PP
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.
.PP
This will cause startup times to be slower (a hundred milliseconds or
so), so the default value is \(lqsingle\-instance.\(rq 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.
.PP
This feature requires \f[CR]systemd\f[R].
If \f[CR]systemd\f[R] is unavailable, cgroup initialization will fail.
By default, this will not prevent Ghostty from working (see
\f[CR]linux\-cgroup\-hard\-fail\f[R]).
.PP
Changing this value and reloading the config will not affect existing
surfaces.
.PP
Valid values are:
.IP \(bu 2
\f[CR]never\f[R] \- Never use cgroups.
.IP \(bu 2
\f[CR]always\f[R] \- Always use cgroups.
.IP \(bu 2
\f[CR]single\-instance\f[R] \- Enable cgroups only for Ghostty instances
launched as single\-instance applications (see gtk\-single\-instance).
.RE
.TP
\f[B]\f[CB]\-\-linux\-cgroup\-memory\-limit\f[B]\f[R]
Memory limit for any individual terminal process (tab, split, window,
etc.)
in bytes.
If this is unset then no memory limit will be set.
.RS
.PP
Note that this sets the \f[CR]MemoryHigh\f[R] setting on the transient
\f[CR]systemd\f[R] scope, which is a soft limit.
You should configure something like \f[CR]systemd\-oom\f[R] to handle
killing processes that have too much memory pressure.
.PP
Changing this value and reloading the config will not affect existing
surfaces.
.PP
See the \f[CR]systemd.resource\-control\f[R] manual page for more
information:
https://www.freedesktop.org/software/systemd/man/latest/systemd.resource\-control.html
.RE
.TP
\f[B]\f[CB]\-\-linux\-cgroup\-processes\-limit\f[B]\f[R]
Number of processes limit for any individual terminal process (tab,
split, window, etc.).
If this is unset then no limit will be set.
.RS
.PP
Note that this sets the \f[CR]TasksMax\f[R] setting on the transient
\f[CR]systemd\f[R] scope, which is a hard limit.
.PP
Changing this value and reloading the config will not affect existing
surfaces.
.PP
See the \f[CR]systemd.resource\-control\f[R] manual page for more
information:
https://www.freedesktop.org/software/systemd/man/latest/systemd.resource\-control.html
.RE
.TP
\f[B]\f[CB]\-\-linux\-cgroup\-hard\-fail\f[B]\f[R]
If this is false, then creating a transient \f[CR]systemd\f[R] scope
(for \f[CR]linux\-cgroup\f[R]) will be allowed to fail and the failure
is ignored.
This is useful if you view cgroup isolation as a \(lqnice to have\(rq
and not a critical resource management feature, because surface creation
will not fail if \f[CR]systemd\f[R] APIs fail.
.RS
.PP
If this is true, then any transient \f[CR]systemd\f[R] scope creation
failure will cause surface creation to fail.
.PP
Changing this value and reloading the config will not affect existing
surfaces.
.RE
.TP
\f[B]\f[CB]\-\-gtk\-opengl\-debug\f[B]\f[R]
Enable or disable GTK\(cqs OpenGL debugging logs.
The default is \f[CR]true\f[R] for debug builds, \f[CR]false\f[R] for
all others.
.RS
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-gtk\-single\-instance\f[B]\f[R]
If \f[CR]true\f[R], the Ghostty GTK application will run in
single\-instance mode: each new \f[CR]ghostty\f[R] process launched will
result in a new window if there is already a running process.
.RS
.PP
If \f[CR]false\f[R], each new ghostty process will launch a separate
application.
.PP
If \f[CR]detect\f[R], Ghostty will assume true (single instance) unless
one of the following scenarios is found:
.IP "1." 3
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.
.IP "2." 3
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.
.PP
If either of these scenarios is producing a false positive, you can set
this configuration explicitly to the behavior you want.
.PP
The pre\-1.2 option \f[CR]desktop\f[R] has been deprecated.
Please replace this with \f[CR]detect\f[R].
.PP
The default value is \f[CR]detect\f[R].
.PP
Note that debug builds of Ghostty have a separate single\-instance ID so
you can test single instance without conflicting with release builds.
.RE
.TP
\f[B]\f[CB]\-\-gtk\-titlebar\f[B]\f[R]
When enabled, the full GTK titlebar is displayed instead of your window
manager\(cqs simple titlebar.
The behavior of this option will vary with your window manager.
.RS
.PP
This option does nothing when \f[CR]window\-decoration\f[R] is none or
when running under macOS.
.RE
.TP
\f[B]\f[CB]\-\-gtk\-tabs\-location\f[B]\f[R]
Determines the side of the screen that the GTK tab bar will stick to.
Top, bottom, and hidden are supported.
The default is top.
.RS
.PP
When \f[CR]hidden\f[R] 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 \f[CR]toggle_tab_overview\f[R] action in
a keybind if your window doesn\(cqt have a title bar, or you can switch
tabs with keybinds.
.RE
.TP
\f[B]\f[CB]\-\-gtk\-titlebar\-hide\-when\-maximized\f[B]\f[R]
If this is \f[CR]true\f[R], the titlebar will be hidden when the window
is maximized, and shown when the titlebar is unmaximized.
GTK only.
.RS
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-gtk\-toolbar\-style\f[B]\f[R]
Determines the appearance of the top and bottom bars tab bar.
.RS
.PP
Valid values are:
.IP \(bu 2
\f[CR]flat\f[R] \- Top and bottom bars are flat with the terminal
window.
.IP \(bu 2
\f[CR]raised\f[R] \- Top and bottom bars cast a shadow on the terminal
area.
.IP \(bu 2
\f[CR]raised\-border\f[R] \- Similar to \f[CR]raised\f[R] but the shadow
is replaced with a more subtle border.
.RE
.TP
\f[B]\f[CB]\-\-gtk\-titlebar\-style\f[B]\f[R]
The style of the GTK titlebar.
Available values are \f[CR]native\f[R] and \f[CR]tabs\f[R].
.RS
.PP
The \f[CR]native\f[R] 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.
.PP
The \f[CR]tabs\f[R] 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 \f[CR]tabs\f[R] titlebar is that you cannot drag
the titlebar by the titles any longer (as they are tab titles now).
Other areas of the \f[CR]tabs\f[R] title bar can be used to drag the
window around.
.PP
The default style is \f[CR]native\f[R].
.RE
.TP
\f[B]\f[CB]\-\-gtk\-wide\-tabs\f[B]\f[R]
If \f[CR]true\f[R] (default), then the Ghostty GTK tabs will be
\(lqwide.\(rq Wide tabs are the new typical Gnome style where tabs fill
their available space.
If you set this to \f[CR]false\f[R] then tabs will only take up space
they need, which is the old style.
.TP
\f[B]\f[CB]\-\-gtk\-custom\-css\f[B]\f[R]
Custom CSS files to be loaded.
.RS
.PP
GTK CSS documentation can be found at the following links:
.IP \(bu 2
https://docs.gtk.org/gtk4/css\-overview.html \- An overview of GTK CSS.
.IP \(bu 2
https://docs.gtk.org/gtk4/css\-properties.html \- A comprehensive list
of supported CSS properties.
.PP
Launch Ghostty with \f[CR]env GTK_DEBUG=interactive ghostty\f[R] to
tweak Ghostty\(cqs 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.
.PP
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 (\(lq).
The file size limit for a single stylesheet is 5MiB.
.PP
Available since: 1.1.0
.RE
.TP
\f[B]\f[CB]\-\-desktop\-notifications\f[B]\f[R]
If \f[CR]true\f[R] (default), applications running in the terminal can
show desktop notifications using certain escape sequences such as OSC 9
or OSC 777.
.TP
\f[B]\f[CB]\-\-progress\-style\f[B]\f[R]
If \f[CR]true\f[R] (default), applications running in the terminal can
show graphical progress bars using the ConEmu OSC 9;4 escape sequence.
If \f[CR]false\f[R], progress bar sequences are silently ignored.
.TP
\f[B]\f[CB]\-\-bold\-color\f[B]\f[R]
Modifies the color used for bold text in the terminal.
.RS
.PP
This can be set to a specific color, using the same format as
\f[CR]background\f[R] or \f[CR]foreground\f[R] (e.g.\ \f[CR]#RRGGBB\f[R]
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 \f[CR]bright\f[R].
.PP
This can also be set to \f[CR]bright\f[R], 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 \f[CR]palette\f[R] 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
\f[CR]bold\-is\-bright\f[R] is deprecated and replaced by this usage).
.PP
Available since Ghostty 1.2.0.
.RE
.TP
\f[B]\f[CB]\-\-faint\-opacity\f[B]\f[R]
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.
.RS
.PP
Available since Ghostty 1.2.0.
.RE
.TP
\f[B]\f[CB]\-\-term\f[B]\f[R]
This will be used to set the \f[CR]TERM\f[R] environment variable.
HACK: We set this with an \f[CR]xterm\f[R] prefix because vim uses that
to enable key protocols (specifically this will enable
\f[CR]modifyOtherKeys\f[R]), among other features.
An option exists in vim to modify this:
\f[CR]:set keyprotocol=ghostty:kitty\f[R], however a bug in the
implementation prevents it from working properly.
https://github.com/vim/vim/pull/13211 fixes this.
.TP
\f[B]\f[CB]\-\-enquiry\-response\f[B]\f[R]
String to send when we receive \f[CR]ENQ\f[R] (\f[CR]0x05\f[R]) from the
command that we are running.
Defaults to an empty string if not set.
.TP
\f[B]\f[CB]\-\-async\-backend\f[B]\f[R]
Configures the low\-level API to use for async IO, eventing, etc.
.RS
.PP
Most users should leave this set to \f[CR]auto\f[R].
This will automatically detect scenarios where APIs may not be available
(for example \f[CR]io_uring\f[R] 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.
.PP
Based on various benchmarks, we haven\(cqt 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.
.PP
Available options:
.IP \(bu 2
\f[CR]auto\f[R] \- Automatically choose the best backend for the
platform based on available options.
.IP \(bu 2
\f[CR]epoll\f[R] \- Use the \f[CR]epoll\f[R] API
.IP \(bu 2
\f[CR]io_uring\f[R] \- Use the \f[CR]io_uring\f[R] API
.PP
If the selected backend is not available on the platform, Ghostty will
fall back to an automatically chosen backend that is available.
.PP
Changing this value requires a full application restart to take effect.
.PP
This is only supported on Linux, since this is the only platform where
we have multiple options.
On macOS, we always use \f[CR]kqueue\f[R].
.PP
Available since: 1.2.0
.RE
.TP
\f[B]\f[CB]\-\-auto\-update\f[B]\f[R]
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.
.RS
.PP
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\(cqt 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.
.PP
Valid values are:
.IP \(bu 2
\f[CR]off\f[R] \- Disable auto\-updates.
.IP \(bu 2
\f[CR]check\f[R] \- Check for updates and notify the user if an update
is available, but do not automatically download or install the update.
.IP \(bu 2
\f[CR]download\f[R] \- Check for updates, automatically download the
update, notify the user, but do not automatically install the update.
.PP
If unset, we defer to Sparkle\(cqs default behavior, which respects the
preference stored in the standard user defaults
(\f[CR]defaults(1)\f[R]).
.PP
Changing this value at runtime works after a small delay.
.RE
.TP
\f[B]\f[CB]\-\-auto\-update\-channel\f[B]\f[R]
The release channel to use for auto\-updates.
.RS
.PP
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 \f[CR]tip\f[R] and you will receive pre\-release updates.
If you download a stable version of Ghostty then this will be set to
\f[CR]stable\f[R] and you will receive stable updates.
.PP
Valid values are:
.IP \(bu 2
\f[CR]stable\f[R] \- Stable, tagged releases such as \(lq1.0.0\(rq.
.IP \(bu 2
\f[CR]tip\f[R] \- 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.
.PP
Changing this configuration requires a full restart of Ghostty to take
effect.
.PP
This only works on macOS since only macOS has an auto\-update feature.
.RE
.SH FILES
.TP
\f[I]$XDG_CONFIG_HOME/ghostty/config.ghostty\f[R]
Location of the default configuration file.
.TP
\f[I]$HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty\f[R]
\f[B]On macOS\f[R], location of the default configuration file.
This location takes precedence over the XDG environment locations.
.TP
\f[I]$LOCALAPPDATA/ghostty/config.ghostty\f[R]
\f[B]On Windows\f[R], if \f[I]$XDG_CONFIG_HOME\f[R] is not set,
\f[I]$LOCALAPPDATA\f[R] will be searched for configuration files.
.SH ENVIRONMENT
.TP
\f[B]TERM\f[R]
Defaults to \f[CR]xterm\-ghostty\f[R].
Can be configured with the \f[CR]term\f[R] configuration option.
.TP
\f[B]GHOSTTY_RESOURCES_DIR\f[R]
Where the Ghostty resources can be found.
.TP
\f[B]XDG_CONFIG_HOME\f[R]
Default location for configuration files.
.TP
\f[B]$HOME/Library/Application Support/com.mitchellh.ghostty\f[R]
\f[B]MACOS ONLY\f[R] default location for configuration files.
This location takes precedence over the XDG environment locations.
.TP
\f[B]LOCALAPPDATA\f[R]
\f[B]WINDOWS ONLY:\f[R] alternate location to search for configuration
files.
.TP
\f[B]GHOSTTY_LOG\f[R]
The \f[CR]GHOSTTY_LOG\f[R] environment variable can be used to control
which destinations receive logs.
Ghostty currently defines two destinations:
.IP \(bu 2
\f[CR]stderr\f[R] \- logging to \f[CR]stderr\f[R].
.IP \(bu 2
\f[CR]macos\f[R] \- logging to macOS\(cqs unified log (has no effect on
non\-macOS platforms).
Combine values with a comma to enable multiple destinations.
Prefix a destination with \f[CR]no\-\f[R] to disable it.
Enabling and disabling destinations can be done at the same time.
Setting \f[CR]GHOSTTY_LOG\f[R] to \f[CR]true\f[R] will enable all
destinations.
Setting \f[CR]GHOSTTY_LOG\f[R] to \f[CR]false\f[R] will disable all
destinations.
.SH BUGS
See GitHub issues: \c
.UR https://github.com/ghostty-org/ghostty/issues
.UE \c
.SH AUTHOR
Mitchell Hashimoto \c
.MT m@mitchellh.com
.ME \c
\ Ghostty contributors \c
.UR https://github.com/ghostty-org/ghostty/graphs/contributors
.UE \c
.SH SEE ALSO
\f[B]ghostty(5)\f[R]