ptyxis1

Usage

Overview

ptyxis is a container-oriented terminal, designed for the GNOME desktop. It provides tight integration with podman, toolbox, distrobox, and jhbuild to simplify container-based development and system management.

--version

Show the version of the program.

--preferences

Show the preferences window.

--new-window

Open a new window in an existing instance of Ptyxis. If Ptyxis is not running, a new instance is started.

May be combined with --working-directory and --execute and --title options.

--tab

Open a new tab in the most-recently-used window of an existing Ptyxis instance. If Ptyxis is not running, a new instance is started.

May be combined with --working-directory and --execute and --title options.

-x, --execute

Execute a custom command.

This is similar to using -- to provide the custom command except that the entire command line should be provided as a single argument.

In general, you should use -- instead of this option. This is primarily available to be similar to bash -c 'command'

May be combined with --working-directory and --title options.

-d, --working-directory

Set the current working directory for a new tab [--tab], window [--window], or custom command [-- COMMAND...].

--title=TITLE

Sets the title for a new terminal page created with either --tab or --new-window.

--maximize

Maximize a newly created window.

--fullscreen

Fullscreen a newly created window.

--tab-with-profile=PROFILE

Creates a new tab in an existing instance using the specified profile. The profile should be a UUID string which can be found in the profile editor of the preferences dialog.

-s, --standalone

Start a new instance of Ptyxis, in single instance mode, ignoring any instances already running.

Single instance mode is implied when running a -- command.

-s, --gapplication-app-id=ID

Override the application ID in single instance mode.

-h, --help

Show a summary of options.

Other standard GNOME options not listed here are also supported.

Palette files

Ptyxis supports custom color palettes defined in INI-style files with a .palette extension. Palette files can be placed in ~/.local/share/org.gnome.Ptyxis/palettes/ to be available in the palette selector.

Palette files use the GKeyFile format (similar to INI files) and must contain at minimum a [Palette] section with a Name key. The palette can define colors in two ways:

Single Scheme

If neither [Light] nor [Dark] sections are present, color keys may be placed directly in the [Palette] section. The same colors will be used for both light and dark themes, with Ptyxis automatically determining which theme to use based on the system color scheme.

Dual Scheme

If both [Light] and [Dark] sections are present, each section defines colors for its respective theme. Both sections must contain the same required color keys.

The [Palette] section supports the following keys:

Name

(Required) The display name of the palette as shown in the palette selector.

Primary

(Optional) Boolean value (true/false). If set to true, marks this palette to be included in the initial set of palettes shown to the user. This is generally used for a limited set of palettes shipped with Ptyxis.

UseSystemAccent

(Optional) Boolean value (true/false). If set to true, the palette will use the system accent color.

Each color scheme section ( [Palette] , [Light] , or [Dark] ) must contain the following required color keys:

Foreground

Text foreground color.

Background

Terminal background color.

Color0

through Color15 The 16 standard terminal colors (0-7 are normal colors, 8-15 are bright colors).

The following color keys are optional and will use computed defaults if omitted:

Cursor

or CursorBackground Cursor background color. If not specified, defaults to the foreground color.

CursorForeground

Cursor foreground color.

TitlebarBackground

Titlebar background color. Defaults to a shaded version of the background.

TitlebarForeground

Titlebar foreground color. Defaults to a shaded version of the foreground.

BellForeground

Visual bell foreground color. Defaults to the titlebar foreground color.

BellBackground

Visual bell background color. Defaults to a mix of Color11 and titlebar background.

SuperuserForeground

Foreground color when running as superuser. Defaults to a shaded version of the titlebar foreground.

SuperuserBackground

Background color when running as superuser. Defaults to a mix of Color1 and the background.

RemoteForeground

Foreground color when connected remotely. Defaults to a shaded version of the titlebar foreground.

RemoteBackground

Background color when connected remotely. Defaults to a mix of Color12 and the background.

All color values must be specified in hexadecimal format, either as #RRGGBB or #RRGGBBAA (with optional alpha channel). For example: #ffffff (white) or #000000ff (black with full opacity).

Example palette file:

[Palette]
Name=My Custom Palette
[Light]
Foreground=#000000
Background=#ffffff
Color0=#000000
Color1=#cc0000
Color2=#00cc00
Color3=#cccc00
Color4=#0000cc
Color5=#cc00cc
Color6=#00cccc
Color7=#cccccc
Color8=#808080
Color9=#ff0000
Color10=#00ff00
Color11=#ffff00
Color12=#0000ff
Color13=#ff00ff
Color14=#00ffff
Color15=#ffffff
[Dark]
Foreground=#ffffff
Background=#000000
Color0=#000000
Color1=#cc0000
Color2=#00cc00
Color3=#cccc00
Color4=#0000cc
Color5=#cc00cc
Color6=#00cccc
Color7=#cccccc
Color8=#808080
Color9=#ff0000
Color10=#00ff00
Color11=#ffff00
Color12=#0000ff
Color13=#ff00ff
Color14=#00ffff
Color15=#ffffff