Configuration

DropTerm keeps every setting in RON files under one directory and reloads them live - changes apply without a restart, whether made in the settings drawer or by editing the file directly.

~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/

Each of the 51 keys is its own file in that directory. Edit one directly:

echo '60' > ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/height_percent
echo 'Left' > ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/h_align

Most keys are editable in the settings drawer; the exceptions write themselves (settings_drawer_width) or wait for behavior that does not ship yet (Parked and reserved keys).

The default config directory

What a fresh configuration carries - every key that has a default, with the file’s whole content as its value (a genuine string quoted; an enum, a number, or a bool bare). Pinned to the code by a test, so it cannot drift:

The remaining keys have no default to write, so their files do not exist until you set them: shell (unset falls back to $SHELL, then /bin/sh), args, default_profile, default_cwd, profiles and custom_key_binds (empty lists write nothing), autosuggestions_aliases (empty by default - no alias re-targets anything), output (reserved - nothing reads it yet), and settings_drawer_width (unset until the drawer’s drag handle first writes it).

Geometry

Geometry applies live: a shown surface is reshaped in place, a hidden one picks the new geometry up on its next show.

Appearance

Scheme names come from the built-in registry - the same names the drawer’s pickers offer (Theming). A name the registry does not know falls back to the COSMIC pair and is never rewritten. All six keys apply live.

Tab bar position

A change never resizes anything - the strip reorders immediately on a shown surface. Pick it in the Geometry section of the settings drawer.

Tab titles

A manual rename wins in every mode. Changing the mode re-titles every live tab immediately, renamed ones excepted; while in Profile mode, renaming a profile retitles its running tabs at once.

Status bar

status_bar_enabled (default true) shows the 28 px band at the surface’s free edge, beside the grab bar. The band’s segments, click-to-copy, selection, and context menu are covered in their own page: Status bar. Toggle it with Ctrl+Shift+B, on the Behavior tab, or by writing the key.

All live. A hidden segment is never computed - hiding the branch stops the .git reads, hiding the clock stops its tick, hiding the duration stops its 1 s tick while a command runs, hiding the exit status stops its verdict sampling.

Bar borders

The color follows the active scheme, so a scheme flip recolors both lines. Where the strips adjoin, only one line renders - no doubled seam. Pure display: no bar changes height, and both keys are independent. Toggle them on the Behavior tab.

Close confirmation

close_confirmation_enabled (default true) asks before closing a tab whose terminal runs a foreground process - through an in-surface modal, one prompt at a time, including the tab context menu’s Close Other Tabs and Close Tabs to the Right sweeps (pinned tabs never close). false restores instant, unconfirmed closes.

A shell exiting on its own never confirms. The key is read at request time, so a flip applies to the very next close.

Shell and directories

shell and args apply to the next spawn only - a running tab is never re-launched. new_tab_cwd covers the plain spawns (Ctrl+Shift+T, the tab bar +, the context menus’ plain New Tab, a bare remote new-tab, the fresh-startup tab); it never applies to Ctrl+Shift+H (home is that bind’s contract), duplicates, profile launches, or session restore. An explicit --cwd wins in both modes.

echo 'Default' > ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/new_tab_cwd
echo '"/srv/work"' > ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/default_cwd

Behavior toggles

The toggles apply at their next natural trigger - the session toggle at the next save/restore cycle, the slide toggle at the next transition, the bell toggle at the next bell, placement at the next new tab.

The alias map is written by hand, one expansion per declared alias:

// ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/autosuggestions_aliases
{
    "gc": "git checkout",
}

Layer, focus, and panels

The anchor itself never takes input or focus in either mode — it exists to keep a copied selection alive while the drop-down is hidden.

With an autohide panel, the hidden panel still reserves its handle strip, so a respecting drop-down sits a few pixels below the screen edge.

echo true > ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/respect_panel

Settings drawer width

settings_drawer_width (default unset) is the settings pane’s width in pixels, as last dragged. The drawer’s drag handle writes it on release; double-clicking the handle resets it to unset. Stored values are clamped at render into 344 px to half the surface, so a stale or hand-edited value can never outgrow the surface.

Profiles

Profiles are named presets of what a tab runs, managed on the settings drawer’s Profiles tab - or hand-edited in the profiles file, in this shape:

// ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/profiles
(
    {"name": "web-prod", "command": "ssh web-prod", "cwd": Some("/srv/web"), "color_scheme": Some("Dracula"), "font_size": Some(11), "scrollback_lines": Some(50000), "env": Some({"DROPTERM_PROFILE": "prod", "HTTP_PROXY": "http://bastion:3128"})},
    {"name": "top", "command": "htop"},
)

The appearance fields resolve per field, never per profile: a set field wins, an unset field inherits the global value - and each decides on its own. A profile deleted while its tabs run degrades them to the global picks field by field, never rewritten, never an error. The window background follows the active tab’s resolution, so the fallback background moves with a tab switch.

env values are verbatim strings - no expansion or interpolation, ever; keys must be non-empty and free of =. A profile whose command is blank (a hand-edited file) degrades to a plain shell and carries none of the profile’s identity.

default_profile (default unset) names the profile plain new tabs launch: Ctrl+Shift+T, the tab bar +, the context menu’s plain New Tab, a bare remote new-tab, and the fresh-startup tab all run it. A name the list no longer carries quietly falls back to the plain shell. Profiles are also launched six other ways - new-tab --profile NAME, the context menus’ profile submenus and Switch Profile folders, and the tab bar +’s right-click dropdown. A Switch Profile pick respawns that tab in place under the chosen profile: the running command and scrollback are lost, while the slot, the activation, and a pinned rename stay.

Keybindings

Keybindings are customized in the drawer’s Keybindings tab or by hand. custom_key_binds (default empty - all defaults) maps one action id to one binding; the full action-id table lives in keybindings:

// ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/custom_key_binds
{
    "copy": (modifiers: [Ctrl, Alt], key: "C"),
    "activate_tab_3": (modifiers: [], key: "F2"),
}

A binding spells modifier names (Ctrl, Shift, Alt, Super) plus a key name - single letters case-insensitive, named keys spelled out (Tab, PageUp, F1, Space). Rules:

• A custom binding replaces all of that action’s default chords; removing the entry reverts to the defaults.
• A chord two actions claim resolves to the later id in the file.
• Entries with unknown ids or an empty key are skipped with a warning - never fatal.
• The map is watched live: the very next key press after a write uses the new bindings.

Parked and reserved keys

Two keys load and persist today but change no behavior:

• settings_drawer_click_close (default true) is parked: the planned click-to-dismiss behavior cannot ship until a capture mechanism exists. A hand-edited value is inert.
• output (default unset) is reserved for monitor selection - naming the Wayland output the drop-down shows on. Nothing reads it yet; see the roadmap.

The completions data file

One more file can live in the config directory beside the keys: completions.toml, the autosuggestions’ subcommand and flag table. The curated five commands (git, cargo, docker, systemctl, npm) are built in; this file extends the table with your own commands - a command you declare adds beside the built-ins, and a command you re-declare replaces its built-in entry whole (the one way to give a built-in’s entries descriptions). DropTerm ships a generated core tier to start from: data/completions.toml in the repository - ninety-two commands with menu descriptions, converted from withfig/autocomplete at a pinned version (MIT; the licensing audit in the seed audit, the conversion and provenance in the breadth record) - copy it to the config directory and edit from there.

# ~/.config/cosmic/io.github.l1br3_io.CosmicExtDropterm/v1/completions.toml

# One table per command. `name` is the command word the table
# answers for - through the alias map too, so a mapped alias
# re-targets here exactly as it does the built-ins.
[[commands]]
name = "gh"

# Subcommands complete the first argument seat (`gh pr` ghosts
# and lists them). Every entry is a `name` plus an optional
# `description` - the completions menu shows it beside the row,
# dimmed; the ghost ignores descriptions (it is text only).
[[commands.subcommands]]
name = "pr"
description = "Manage pull requests"

[[commands.subcommands]]
name = "pr-check"

# Long flags complete the flag seat from any argument position
# (`gh --rep` finishes `--repo`). A flag's other forms - short
# ones included - belong in its `aliases`, never as their own
# entries: short forms are recognized, never suggested.
[[commands.flags]]
name = "--repo"
description = "Select another repository"

The shape is recursive: a [[commands.subcommands]] entry is itself a command, taking the same keys and its own subcommands, flags, and positional args, so docker compose and everything under it are described exactly as docker is. A command or subcommand also takes aliases (its other names, co for checkout), hidden (suggested only when typed exactly), priority (a 0-100 ordering hint), and filter_strategy ("prefix", the default, or "fuzzy"). A flag entry takes aliases for its other forms - short forms included, so the table knows a typed -d is --detach, while short forms themselves are never suggested - plus persistent (the flag rides into every subcommand), exclusive_on (flags that hide it once typed), hidden, priority, and the args it consumes. An args entry takes optional, variadic (consumes every following token), command (the argument is itself a command word - the sudo shape), template ("filepaths" or "folders", a path-shaped argument), and literal suggestions (a list of name + description entries). Every key at every depth is optional with a default - an entry carrying none of them is the plain name-plus-description shape above - and the same rejection rule holds at every depth: an unknown key anywhere fails the whole file. The top level’s subcommands and flags complete as they always have; the nested tiers ride the table for the completion walker that reads them.

Rules the loader holds:

• No executable content - ever. The schema rejects unknown keys, so a file carrying a script field (or any key the format does not define) fails whole: DropTerm logs at debug level and answers with the built-in table, never a half-loaded one. Data imports; scripts never arrive.
• The file is optional. No file, an unreadable file, or an invalid file is exactly the built-in behavior - the curated five, unchanged.
• Entries sort by name at load (the match policy - strict prefix, must extend, shortest wins, ties alphabetical - rides sorted lists); an unsorted file is fine.
• An edit applies at the next tab you open (the file reads fresh at spawn) or the next settings change (the file re-reads on every config pass); tabs already open pick it up at that pass’s next typed prefix.