Workspace

A workspace is one folder. Everything you create lives inside it as plain files: collections, environments, globals, history, cookies and settings. There is no account, no database and no cloud copy. Back it up or version it like any other folder.

Choosing a workspace

Postguy picks the workspace at start, in this order:

1. postguy --workspace DIR
2. ./postguy-workspace, if that folder exists in the launch directory
3. ~/postguy-workspace (%USERPROFILE%\postguy-workspace on Windows)

• Postguy creates the folder on first use.
• There is no in-app workspace switcher. To use another workspace, quit and start Postguy with a different --workspace.
• The header shows the folder name.
• If the workspace can't be opened (for example a permission error), the window opens without it. The status text at the bottom right shows the error.

What is inside

Opening a workspace creates collections/, environments/, protos/, files/, .trash/ and .postguy/. Postguy's own settings and session live in .postguy-config/. The complete tree, file schemas and read limits are in Workspace format.

Saving

• Every file is written atomically. Postguy writes a temporary file in the same folder, then renames it over the old one. It keeps the previous version as <file>.bak (one generation). A failed save leaves the old file in place.
• Environment and collection edits autosave shortly after you stop typing.
• Save a request with Save or Cmd/Ctrl+S. The dot on its tab shows unsaved changes.

If a file can't be parsed when it loads:

• Postguy renames it to <file>.corrupt-<time>, continues without it and reports it. Nothing is deleted.
• A corrupt settings.json falls back to defaults.
• A corrupt session.json starts a fresh session.

The workspace lock

Only one process can open a workspace at a time. Postguy writes .postguy/lock with the process id and a start time. It removes the file on a clean exit.

• If another live process holds a fresh lock, opening fails with workspace already open by pid N; close that instance or remove <path> if it is gone.
• Postguy takes over a lock whose process is gone, or whose start time is more than 3 minutes old.

Postguy doesn't renew the lock while it runs. It guards against accidental double opens but is not a hard guarantee. A second process that starts more than 3 minutes after the first can take the lock over. Don't open the same workspace in two processes at once.

The app, postguy-cli and the automation tools share the lock. Close the app before you run the CLI against the same workspace. See Troubleshooting.

Trash

Deleting a collection or environment:

• moves its file to .trash/ together with a small metadata file (original path, kind, deletion time);
• removes its secrets.

The Trash tab (bottom bar, or the command Open trash) lists those entries with Restore. A restore puts the file back at its original path. If that path is taken, it adds restored to the name.

Deleting a folder or request writes a record to .trash/item-<time>.json. The record holds the item, its collection id and the deletion time. The Trash tab doesn't list these records yet. To recover one, copy the item value from that file back into the collection by hand.

• Collections and folders ask you to type delete before they are removed.
• Requests and environments are removed immediately. They still go to the trash.

Undo

• Cmd/Ctrl+Z in the sidebar undoes the last rename or move of a tree item.
• Cmd/Ctrl+Shift+Z redoes it.
• Deletes are not undone this way. Use the trash.

Session restore

Postguy saves the open tabs and the sidebar section state and heights to .postguy-config/session.json. It saves at most once a second and only when something changed. On the next start:

• The tabs are restored. Tabs whose collection, request or environment no longer exists are closed with a status note.
• After an unclean exit, the status text says Session restored after an unexpected exit.

Window position and size, expanded folders and the two-pane toggle are not restored.

Secrets

A variable marked Secret keeps only its name in the environment, globals or collection file. The value is stored in .postguy/secrets.json (mode 0600 on Unix) and loaded back into memory when the file is read. OAuth 2.0 access and refresh tokens are stored there too. Deleting an environment or a collection removes its secrets.

Secret values are masked in history, the console and generated snippets. They are left out of exports unless you choose to include them.

History

• Each send from the request builder is appended to history.jsonl, one JSON object per line.
• Collection runs do not write history.
• The file is capped at 5000 entries. When it grows past that, the oldest entries are dropped.
• Save response bodies in history (Settings › General) also caches each response body under .postguy/responses/.

See HTTP requests for what an entry stores.

Export and restore

To back up a workspace, copy the folder.

For a portable archive, use the command Export all workspace data…. It writes a zip (default name Workspace.zip).

• The zip holds the collections, environments, globals, protos/, files/, assets/, history.jsonl and postguy.json.
• It leaves out everything whose path starts with .postguy (secrets, cookies, cached responses, runs, lock, and .postguy-config/), .trash/ and .bak files.
• It skips symbolic links.
• It holds at most 50,000 files and 1 GiB.

Restore is documents-only. Importing the zip reads only its .json entries (collections, environments, globals) and merges them through the normal import rules. Files such as assets and .proto sets are not extracted. See Import and export.