Guide
Settings
The Settings screens, every settings.json key with its default, and what happens to a corrupt settings file.
Open Settings with Cmd/Ctrl+, or the command Open settings. It opens as a tab with a navigation column. Every change is saved at once. There is no Save button.
Pages
| Page | Rows |
|---|---|
| General | Request: HTTP version, Request timeout, Max response size, SSL certificate verification, Automatically follow redirects, Disable cookies, Send no-cache header. Working directory: Location, Read files outside the working directory. History: Save response bodies in history. Scripts: Disable scripts. |
| Themes | Theme (Dark, Light, System), Interface zoom, Code font size. |
| Shortcuts | A read-only list of every registered shortcut, grouped. See Keyboard shortcuts. |
| Data | Reset settings. It restores every setting to its default. Collections, environments and history are not touched. |
| Certificates | Custom CA bundle (PEM), Certificate chain (PEM), Private key (PEM). |
| Proxy | Proxy mode. With Custom proxy: Protocol, Host, Port, Username, Password, Apply to HTTP, Apply to HTTPS, Bypass list. |
| About | Version, licence (MIT OR Apache-2.0), privacy note (Offline. No telemetry, no update check), pointer to the third-party notices. |
Where the file lives
Settings are per workspace, in <workspace>/.postguy-config/settings.json. The same folder holds session.json and recent.json. See Workspace and the workspace format.
- Keys are camelCase.
- Unknown keys, including ones written by newer versions, are kept and written back.
- A missing file means all defaults.
- Postguy reads up to 8 MiB of the file. If it cannot parse the file, it renames it to
settings.json.corrupt-<number>in the same folder and starts with defaults. - The app rewrites the file on every change. Edit it by hand only while Postguy is closed.
Global settings keys
The Shown column says which Settings page shows the key. Keys marked No are stored in the file and survive a reload. No code in the app acts on them today.
| Key | Default | Values and notes | Shown |
|---|---|---|---|
httpVersion | auto | auto, http1, http2. Used when a request's own setting is auto. | General › HTTP version |
requestTimeoutMs | 0 | 0 means no timeout. The screen accepts 0 to 3,600,000. Used when the request's own timeout is 0. | General › Request timeout |
maxResponseMb | 50 | 0 means unlimited. The screen accepts 0 to 1,024. Used when the request's own value is the default 50. | General › Max response size |
verifySsl | true | Off if either this or the request's switch is off. | General › SSL certificate verification |
caBundlePath | "" | PEM file added to the system roots. | Certificates |
clientCertPath | "" | PEM certificate chain. | Certificates |
clientKeyPath | "" | PEM private key (PKCS#8, PKCS#1 or SEC1). | Certificates |
disableCookies | false | ORed with each request's Disable cookie jar. | General › Disable cookies |
followRedirects | true | Redirects are followed only if the request's switch is on too. | General › Automatically follow redirects |
sendNoCacheHeader | true | Adds Cache-Control: no-cache to every request. | General › Send no-cache header |
workingDirectory | "" | Empty means <workspace>/files. Base folder for file paths in request bodies. | General › Working directory › Location |
allowFilesOutsideWorkingDirectory | false | Lets request bodies read any file on the computer. | General › Read files outside the working directory |
saveHistoryResponses | false | Caches response bodies under .postguy/responses/ for History. | General › Save response bodies in history |
disableScripts | false | Skips pre-request and post-response scripts for every request and run. | General › Disable scripts |
theme | system | system, light, dark. | Themes › Theme |
uiZoom | 1.0 | Clamped to 0.8 to 2.0. The screen offers 80, 90, 100, 110, 125, 150, 175 and 200 %. Cmd/Ctrl plus = and - step by 10 %. | Themes › Interface zoom |
editorFontSize | 13.5 | Pixels. The screen accepts 9 to 24. | Themes › Code font size |
proxy | see below | Object. | Proxy |
trimKeysAndValues | false | No | |
responseFormatDetection | auto | auto or forceJson. | No |
alwaysOpenInNewTab | false | No | |
alwaysAskOnClose | true | No | |
showIconsWithTabNames | true | No | |
twoPaneLayout | false | The Toggle two-pane layout command keeps its own state and does not read this key. | No |
variableAutocomplete | true | No | |
autosave | false | No | |
editorIndentJson | 2 | No | |
editorIndentOther | 4 | No | |
editorSpaces | true | No | |
editorAutoClose | true | No | |
editorWordWrap | false | No | |
historyCap | 5000 | History is trimmed to a fixed 5,000 entries. This key does not change that. | No |
proxy object
| Key | Default | Values |
|---|---|---|
mode | system | system (environment variables) or custom |
protocol | http | http, socks5, socks5h |
host | "" | An empty host with custom means no proxy |
port | 8080 | 1 to 65,535 on the screen |
username | "" | Proxy Basic auth |
password | "" | Proxy Basic auth. Redacted in logs. |
applyToHttp | true | |
applyToHttps | true | |
bypass | "" | Comma-separated hosts or patterns, for example localhost, *.internal.example |
For how the proxy is used, see Cookies, proxy and certificates.
Per-request settings
Each HTTP request also has a Settings tab. It holds HTTP version, SSL verification, redirect options, Encode URL automatically, Disable cookie jar, timeout and max response size. When you send a request, the global and per-request values combine like this:
| Setting | Rule |
|---|---|
| SSL verification, follow redirects | Both must be on. |
| Disable cookies | Either one disables the jar. |
| Timeout | The request's value if not 0, otherwise the global one. |
| Max response size | The request's value if it differs from 50, otherwise the global one. |
| HTTP version | The request's choice, or the global one when the request says Auto. |
See HTTP requests.
Headless
No automation tool edits settings. Tools that depend on them (for example request_send and collection_run) read them from the opened workspace's .postguy-config/settings.json.