Reference and troubleshooting
Local configuration and data
Terminalis stores profiles, preferences, histories, and disposable output caches locally. Portable exports are useful definition snapshots, but they are not complete backups of local state.
Configuration files
The default macOS configuration directory is ~/Library/Application Support/dev.terminalis.app. A launch-time TERMINALIS_CONFIG_DIR override selects a different configuration directory. The main files are:
| File | Purpose |
|---|---|
terminals.yaml | App-owned local profile definitions. |
settings.yaml | App preferences, global command library, and AI connection/model choices. |
settings.yaml.bak | Previous validated settings snapshot for recovery. |
window-bounds.json | Saved window placement. |
mcp-port | Discovery of the current local app listener. |
Use the editor and Settings for ordinary changes. terminals.yaml is not the same schema as a portable .terminalis file: local profiles use app-owned fields, while portable files use the strict interchange schema.
External edits
terminals.yaml is watched. A valid external change reloads the profile configuration, destroys existing shells, and restores idle shells without autostart. This can interrupt running work, so stop it and back up the file before editing externally. An invalid update leaves the active configuration in place until corrected.
settings.yaml is read on app launch rather than watched. Quit Terminalis before editing it and reopen afterward; changes made through Settings itself apply according to the preference rules.
If settings are corrupt, Terminalis can recover a valid backup and preserves invalid copies under timestamped .corrupt-* names. Read the recovery warning instead of repeatedly overwriting the files. Import receipts and transaction journals are app bookkeeping; do not edit them during import or recovery.
Storage locations
| Location | Contents |
|---|---|
Configuration directory history/ | Private Bash/Zsh shell-history files. |
Configuration directory command-history/ | Separate per-terminal recent-command records. |
Configuration directory managed-command-history/ | Legacy recent-command data retained as a migration source. |
| Fish's data directory | terminalis_<profile-id>_history sessions, respecting Fish/XDG configuration. |
Configuration directory ai/chatgpt/<connection-id>/auth.json | Sign-in credentials for one ChatGPT connection. |
~/Library/Caches/dev.terminalis.app/scrollback/ | Disposable rendered output snapshots. |
~/Library/Caches/dev.terminalis.app/last-cwd/ | Disposable remembered shell directories. |
The cache paths do not follow TERMINALIS_CONFIG_DIR. Sidebar pinning, width, recent selections, and last group tabs also use browser-owned local storage. They are not carried by a portable export. Deleting a profile cleans up its own history and cache data.
AI credentials follow the configuration directory override and are stored separately from
settings.yaml. Manage them through Settings → AI: Disconnect removes a connection's local
credentials; Remove also deletes its saved configuration. They are excluded from portable
.terminalis exports. See Command Assistant
for what a generation request sends to the provider.
Local diagnostics
Terminalis 3.7.0 records session details, warning/error logs, panic reports, and evidence of
interrupted runs locally. Help → Open Diagnostics Folder… opens the current instance's records.
The normal release location is ~/Library/Logs/Terminalis/; development builds use its
development/ subdirectory. With TERMINALIS_CONFIG_DIR, records are under that directory's
logs/release/ or logs/development/ instead.
Each run has a session.json and app.log, with app.previous.log after rotation and up to three
panic-*.txt reports when panics occur. A clean-exit marker records completed shutdown; an
interrupted marker is created on a later launch when normal shutdown was not recorded. It is not
proof of a specific crash.
The app retains ten runs plus any additional live runs. Each run has at most two 2 MiB log segments and three 256 KiB panic reports. Nothing is uploaded automatically. Command arguments, environment snapshots, and terminal output are not deliberately collected, but errors may contain paths or application data. Inspect reports before sharing. macOS retains responsibility for native crash reports in its DiagnosticReports directories.
Backups
Quit Terminalis before copying its configuration directory so definitions, histories, and import bookkeeping form a consistent snapshot. Include Fish's own history directory if you need its private sessions. Keep backups outside the app-owned directory and protect them like other local development data.
A full configuration backup can include AI sign-in credentials under ai/. Keep that backup private;
use a portable export when sharing terminal definitions.
A .terminalis export is convenient for sharing definitions and reviewing included environment values. It omits global commands, runtime state, personal preferences, and history, so it cannot replace a full local backup. Hidden values remain recoverable from configuration and exports; old backups may contain earlier plaintext values.