Settings reference
Every key in settings.json, the file in your data directory that the app’s Settings writes. Keys are dotted paths into the file: appearance.theme is {"appearance": {"theme": …}}. For what each section of Settings does, see Settings.
| Key | Value | Default | What it does |
|---|---|---|---|
appearance.theme | "system", "dark", "light" | "system" | The colour scheme of the app and of every plugin view. system follows the operating system. |
appearance.dark_theme | a theme’s id, such as "nord" | "dark" | The theme used in the dark colour scheme. |
appearance.light_theme | a theme’s id, such as "nord" | "light" | The theme used in the light colour scheme. |
appearance.text_size | "small", "default", "large" | "default" | The size of the interface’s text. |
autostart | true or false | false | Start Pinrail when you log in. |
close_window | "hide", "quit" | "hide" | What closing the window does: hide it and keep running in the menu bar, or quit. |
inbox.open_in | "panel", "page" | "panel" | Where the inbox opens a review: in a panel beside the list, or as a page of its own. |
inbox.layout | "project", "repository", "list" | "repository" | How the inbox lists what waits: grouped by project, grouped by repository, or in one list, newest first. |
sessions.layout | "project", "repository", "list" | "list" | How the Sessions page lists the sessions: grouped by project, grouped by repository, or in one list. |
items.layout | "project", "repository", "list" | "project" | How the Work items page lists the items: grouped by project, grouped by repository, or in one list. |
items.nesting | "nested", "flat" | "nested" | How the Work items page shows sub-items: nested under their parent, or each as a row of its own. |
items.close_parents | true or false | true | Close a work item when its last open sub-item is done or cancelled and at least one of them is done, unless someone works on it or something of it waits for you. |
items.ordering | "oldest", "newest", "updated", "status", "title" | "oldest" | The order of the Work items page within each group, and of sub-items under their parent: oldest or newest first, recently updated first, by status, or by title. |
menu_bar_icon | true or false | true | Show the menu bar icon, with the number of waiting reviews. |
sidebar.open | true or false | true | Whether the sidebar is open. The app keeps it, so a new window matches the last. |
sidebar.sessions.grouping | "project", "repository", "status", "updated", "none" | "repository" | How the sidebar groups the sessions: by project, by repository, by status, by when they were last updated, or not at all. |
sidebar.sessions.ordering | "status", "updated" | "status" | How the sidebar orders the sessions: what waits first, then by status, or the most recently updated first. |
sidebar.sessions.show_details | true or false | false | Show a second line of details under each session in the sidebar. |
sidebar.sessions.details | a list of non-empty strings | ["activity","status"] | The details on a session’s second line: activity, status, repo, branch and agent. |
sidebar.sessions.show_reviews | true or false | true | List the reviews and questions that wait for you under their session in the sidebar. |
sidebar.sessions.agents | a list of non-empty strings | [] | List only these agents’ sessions in the sidebar. An empty list shows every agent. |
sidebar.sessions.repos | a list of non-empty strings | [] | List only these repositories’ sessions in the sidebar, with - for none, and a project’s as project:<id>. An empty list shows every one. |
sidebar.sessions.states | a list of non-empty strings | [] | List only the sessions in these states in the sidebar: working, quiet and done. An empty list shows every state. |
sidebar.sessions.archived | true or false | false | List the archived sessions in the sidebar too. |
sidebar.sessions.collapsed | a list of non-empty strings | [] | The sidebar’s groups that are collapsed, each as its grouping and its key, such as repository:acme/api. |
notifications.enabled | true or false | true | Announce new reviews with a system notification. |
notifications.paused_until | an RFC 3339 time, or null | null | No notifications until this time. The menu bar and Settings pause them for a while. |
notifications.sound | true or false | true | Play the system sound with each notification. |
notifications.muted_plugins | a list of non-empty strings | [] | Plugins whose reviews are not announced. They are still counted in the menu bar. |
notifications.quiet_hours | {"from": "HH:MM", "to": "HH:MM"}, or null | null | No notifications between from and to, local time. A review that arrives then is not announced later. |
shortcut.global | a non-empty string | "alt+shift+w" | The shortcut that brings Pinrail forward from any app. |
shortcut.global_opens | "oldest", "inbox" | "oldest" | What the global shortcut opens: the oldest pending review, or the inbox. |
port | a port, 1 to 65535 | 4747 | The port of the server on 127.0.0.1. Takes effect after a restart; the CLI follows it. |
history.keep_days | a number of days from 1 to 36500, or null | null | Delete ended reviews older than this many days. null keeps them forever. |
agents.auto_update | true or false | false | Update the pinrail skill of every connected agent when Pinrail starts, after an update of Pinrail changed the skill. |
updates.check | true or false | true | Look for a new version of Pinrail at start and every few hours, and download it in the background. It is installed when Pinrail restarts. |
telemetry.usage | true or false | true | Send anonymous usage data: which features are used and how often, never what you review. DO_NOT_TRACK or PINRAIL_TELEMETRY, set to any value, turns it off. |
telemetry.crashes | true or false | true | Send a report when Pinrail crashes, with file paths and quoted text removed. DO_NOT_TRACK or PINRAIL_TELEMETRY, set to any value, turns it off. |
telemetry.notice_shown | an RFC 3339 time, or null | null | When the notice about usage data was shown. Nothing is recorded or sent before it has been. |
whats_new.seen | a version such as "0.3.0", or null | null | The release of Pinrail whose notes were last shown. A newer release with notes shows them once when it first starts. |
welcome.seen | true or false | false | Whether the setup has been finished or skipped. While false, Pinrail opens on it. |
Plugin settings
Section titled “Plugin settings”Under plugins.<name>, each plugin keeps the settings its manifest declares in settings_schema, checked against that schema. See Settings and keys of a plugin.
Link permissions
Section titled “Link permissions”Under links.<name>, Pinrail keeps the sites a plugin may open without asking: source, where the plugin was installed from when the sites were allowed, and origins, such as ["https://github.com"]. The permission applies only while the plugin is installed from that source, and removing the plugin removes it. The app writes it when you allow a site, and a plugin’s view cannot change it.
Changing settings
Section titled “Changing settings”The app writes the file as settings change, and notices an edit made outside it. A key it does not know is kept as it is. A script can read and change settings through the local API, which checks every change the same way:
curl http://127.0.0.1:4747/api/v1/settingscurl -X PATCH http://127.0.0.1:4747/api/v1/settings \ -H 'content-type: application/json' -d '{"notifications": {"sound": false}}'