Reference
Settings & shortcuts
Choose a theme and customize document display, query preferences, tool paths and workspace restoration.
Open Settings
Choose Settings from the top-right application menu. Changes apply immediately and are saved on this device. Sections are arranged in tabs; use Left/Right arrows or Home/End while a tab is focused.
Appearance and document display
- Appearance: theme, UI font size, result font size, row density and BSON type badges.
- Explorer: single/double-click actions, Follow active tab in Explorer, and wrapping or truncation of collection/view names.
- Documents: single-line string truncation, legacy UUID representation, the default Immediate save behaviour, quote markers, natural/alphabetical property order, object summary templates, date format and relative times.
- Value colours: per-BSON-type colour overrides using hex values or preset swatches.
Under Settings → Explorer, Single-click a collection or view can select only (default), activate an existing tab without opening one, or open/activate a tab. Double-click a collection or view can open/activate a tab (default) or always open a new tab. Ctrl+click on Linux/Windows or Command+click on macOS always opens a new tab. A double-click creates at most one new tab, including when single-click opening is enabled.
Tab reuse matches the exact connection, database and collection in document-query tabs, preserving filters, edits and loaded results. It searches both split panes, preferring the active pane and then the most recently used match within that pane. Recency is session-only. Aggregation and Shell tabs are not reused. Opening a tab never runs a query automatically. Reset display defaults restores select-only single-click and open/activate double-click.
Follow active tab in Explorer is enabled by default. Switching a collection or aggregation tab selects its collection on the left, expands its database and connection section, and scrolls it into view without moving keyboard focus. This also follows the active split-editor group. A search that hides the collection is cleared; workspace namespace filters remain respected. Tabs without a collection, such as Shell, leave Explorer where it was. Disable this option to browse Explorer independently of tab changes. Reset display defaults enables it again.
Explorer collection and view names defaults to Wrap onto multiple lines. Choose Truncate with ellipsis for single-line names ending in an ellipsis when they do not fit. Hover over an entry to see its full name; view icons and View badges remain visible. The choice applies immediately to direct-connection and named-workspace Explorers and is saved on this device. Reset display defaults restores wrapping.
Object summary templates can show the field count and literal top-level fields:
{$fieldCount} fields {Name} ({_id})
Names are case-sensitive. In this template, dots are literal characters rather than nested paths; missing values are omitted. Relation display templates use the same formatting conventions but allow nested paths such as {profile.name}. These presentation settings do not change database values.
Colour themes
Choose Appearance → Theme to switch between Default (dark teal), Light, Tokyo Night, Gruvbox Dark, Catppuccin Mocha and custom themes. Changes apply immediately to the interface, BSON values and source editors, and are remembered on this device. Open editors retain their text and undo history.
The additional bundled palettes are Palryn adaptations of Tokyo Night's Night variant with blue accents, Gruvbox's medium-contrast dark palette with green accents, and Catppuccin's Mocha flavour with mauve accents. Each themes the complete interface, BSON values and source syntax; no extra files are required.
In the desktop app, choose Open themes folder, add a UTF-8 .json file, then choose Reload themes. The folder is normally ~/.config/app.palryn.desktop/themes on Linux (or under $XDG_CONFIG_HOME), %APPDATA%\app.palryn.desktop\themes on Windows, and ~/Library/Application Support/app.palryn.desktop/themes on macOS. Settings shows the resolved path. Themes are also scanned at startup and when opening Settings.
This example overrides a few colours; everything else inherits from its dark or light base:
{
"version": 1,
"id": "midnight",
"name": "Midnight",
"scheme": "dark",
"colors": {
"background": "#10141c",
"surface": "#192130",
"accent": "#72c7ff",
"accentHover": "#a4dbff",
"accentText": "#a4dbff",
"onAccent": "#10141c",
"accentSurface": "#1d3042",
"accentSurfaceHover": "#29445e",
"accentBorder": "#4d7ea6",
"focus": "#72c7ff"
},
"valueColors": { "string": "#f2b5cf" }
}
Use a stable ID of 1–64 lowercase letters, digits or hyphens, beginning with a letter or digit, and a non-empty name of at most 80 characters without control characters. Version must be 1; scheme must be dark or light. UI colours accept #RRGGBB or #RRGGBBAA; BSON value colours accept #RRGGBB. Files must be at most 64 KiB. Comments, trailing commas, unknown keys and duplicate IDs are reported in Settings. For duplicate IDs, the first filename in sorted order wins. Only ordinary JSON files directly in the folder are scanned; subdirectories and symlinks are skipped.
Available colour roles
- Surfaces:
background,surface,panel,editorPanel,input,output,elevated. - Text:
text,textStrong,textSecondary,textMuted,textSubtle. - Borders and controls:
border,borderControl,borderStrong,button,buttonHover,buttonHoverBorder,hover,switchTrack,switchThumb. - Accents:
accent,accentHover,accentText,onAccent,accentSurface,accentSurfaceHover,accentBorder,focus. - Status and overlays:
info,infoSurface,warning,warningSurface,error,errorBorder,errorSurface,viewIcon,shadow,backdrop. - Source editors:
editorBackground,editorText,editorGutter,editorSelection,editorActiveLine,syntaxKeyword,syntaxName,syntaxProperty,syntaxString,syntaxNumber,syntaxType,syntaxFunction,syntaxComment,syntaxOperator. - The separate
valueColorsobject acceptsstring,boolean,int32,long,double,decimal128,objectId,uuid,legacyUuid,md5,binary,date,timestamp,regex,null,minKey,maxKey,objectandarray.
If a selected file disappears or becomes invalid, Default is used and Settings explains why. Restoring the file and reloading restores the saved selection. Invalid files do not prevent other themes from loading. Value colours overrides take precedence over the theme; resetting one type returns to the selected theme's colour. Reset display defaults selects Default without deleting theme files.
String display
Documents → Truncate string values to one line is enabled by default. Strings in document tables and trees stay on one line and end with an ellipsis when they exceed the available width. Hover over a string to see its complete text. Turn this option off to wrap long strings. The choice applies immediately and is saved on this device; resetting display defaults enables truncation again. Copying, editing, exports and JSON source retain the complete original string.
Legacy UUID representation
Choose C#, Java or Python under Documents → Legacy UUID representation. C# is the initial and reset default. This controls display of binary subtype 3, marked luuid, and encoding of plain GUID input and LUUID("…"). Standard UUID() values use subtype 4 and are unaffected.
Changing the setting reinterprets the displayed GUID without changing stored bytes. MongoDB does not record which legacy encoding produced those bytes. Use CSUUID(), JUUID() or PYUUID() to choose an encoding explicitly. All four legacy names accept lowercase aliases. An overridden value still displays using your preference afterwards, so its GUID text may look different.
Query and notification preferences
Queries selects enabled filter modes, the default for new editors and the maximum result size per query. Keep at least one filter mode enabled. A new result-size limit applies to queries run after the change; each tab keeps its own results in memory.
Notifications sets the toast position and a timeout between 1 and 60 seconds. Hovering or focusing a notification pauses its countdown. Save confirmations are temporary; query/editor status continues to report conflicts or uncertain outcomes.
Configure external tools
Under Tools, set an executable name on PATH or a full executable path, without arguments:
mongoshfor Shell tabs.mongodumpandmongorestorefrom Database Tools 100.3+ for backup and restore.
These tools are installed separately. Document JSON/CSV transfers use Palryn's own implementation and do not need them.
What Remember saves
Workspace → Remember workspace state controls local restoration of workspaces and their drafts. Turning it off clears saved workspace state while retaining the current session in memory.
| Saved with Remember | Not saved in workspace state |
|---|---|
| Workspace names, connection memberships and visibility filters. | Database results and execution errors. |
| Query filters, sort/projection, tabs and layouts. | Unsaved document and insertion drafts. |
| Aggregation drafts, Shell scripts and relation definitions. | Connection credentials, which use the OS keychain separately. |
Workspace storage is local and not encrypted. Query literals and Shell scripts may contain values you entered. On restoration, selecting the active workspace can connect using saved profiles, but queries and scripts require an explicit run.
Updates and release notes
Updates controls automatic update checking. Click the version in the status area to open release information and available update actions. Choose Download update to download and verify an available update while continuing to work. The verified download is kept for this app session; installation requires a separate Install and restart action.
Save or discard unsaved work and finish or stop running jobs before installation. Palryn checks again when you choose Install and restart, including work started during the download. Installation blocks new interaction until it finishes or fails. If automatic restart fails, restart Palryn manually as instructed. Checking or downloading never installs an update automatically.
The version screen shows release highlights and categorized changes, with earlier versions in collapsible sections. It opens automatically after an upgrade, once per version on this device. Choose View Licence Agreement to read the bundled terms; Close returns to release history. Licence access is here rather than in the top-right application menu.
With automatic checks enabled, Palryn checks shortly after startup and periodically afterwards, sending its version, operating system and architecture to the update service.
DEB/RPM builds instead show package-manager update instructions and an Open downloads button. They do not contact the AppImage update service or replace system-managed files. Download a newer native package and install it with apt/dnf; local package installation does not configure a Palryn repository. See native Linux installation.
Keyboard reference
| Action | Shortcut |
|---|---|
| Run the current query, pipeline or Shell script from its editor | Ctrl/Command + Enter |
| Request query suggestions | Ctrl/Command + Space |
| Accept a selected query suggestion | Tab |
| Next / previous tab | Ctrl/Command + Alt + Right / Left |
| Close a tab | Ctrl/Command + Alt + W |
| Switch editor group | Ctrl/Command + Alt + Down |
| Open the focused item's context menu | Shift + F10 or Context Menu key |
| Move through menu items | Up / Down, Home / End |
| Enter / leave a submenu | Right / Left |
| Cancel inline value input | Escape |
Reset preferences
Reset display defaults restores display, query, notification and update preferences. It retains workspace state, Immediate save behaviour and tool paths. Backup tool paths have their own reset action in Tools.