Skip to content

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.

KeyValueDefaultWhat 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_themea theme’s id, such as "nord""dark"The theme used in the dark colour scheme.
appearance.light_themea 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.
autostarttrue or falsefalseStart 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_parentstrue or falsetrueClose 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_icontrue or falsetrueShow the menu bar icon, with the number of waiting reviews.
sidebar.opentrue or falsetrueWhether 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_detailstrue or falsefalseShow a second line of details under each session in the sidebar.
sidebar.sessions.detailsa list of non-empty strings["activity","status"]The details on a session’s second line: activity, status, repo, branch and agent.
sidebar.sessions.show_reviewstrue or falsetrueList the reviews and questions that wait for you under their session in the sidebar.
sidebar.sessions.agentsa list of non-empty strings[]List only these agents’ sessions in the sidebar. An empty list shows every agent.
sidebar.sessions.reposa 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.statesa 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.archivedtrue or falsefalseList the archived sessions in the sidebar too.
sidebar.sessions.collapseda 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.enabledtrue or falsetrueAnnounce new reviews with a system notification.
notifications.paused_untilan RFC 3339 time, or nullnullNo notifications until this time. The menu bar and Settings pause them for a while.
notifications.soundtrue or falsetruePlay the system sound with each notification.
notifications.muted_pluginsa 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 nullnullNo notifications between from and to, local time. A review that arrives then is not announced later.
shortcut.globala 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.
porta port, 1 to 655354747The port of the server on 127.0.0.1. Takes effect after a restart; the CLI follows it.
history.keep_daysa number of days from 1 to 36500, or nullnullDelete ended reviews older than this many days. null keeps them forever.
agents.auto_updatetrue or falsefalseUpdate the pinrail skill of every connected agent when Pinrail starts, after an update of Pinrail changed the skill.
updates.checktrue or falsetrueLook 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.usagetrue or falsetrueSend 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.crashestrue or falsetrueSend 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_shownan RFC 3339 time, or nullnullWhen the notice about usage data was shown. Nothing is recorded or sent before it has been.
whats_new.seena version such as "0.3.0", or nullnullThe release of Pinrail whose notes were last shown. A newer release with notes shows them once when it first starts.
welcome.seentrue or falsefalseWhether the setup has been finished or skipped. While false, Pinrail opens on it.

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.

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.

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:

Terminal window
curl http://127.0.0.1:4747/api/v1/settings
curl -X PATCH http://127.0.0.1:4747/api/v1/settings \
-H 'content-type: application/json' -d '{"notifications": {"sound": false}}'