Workspaces

A workspace is the root folder you open. Fetchpier remembers a list of recent workspaces; when no workspace is open, the sidebar offers entry points to open or create one and lists the recent workspaces for quick re-opening. Opening a recent entry that no longer exists — or that is no longer a Fetchpier workspace — does not silently recreate it: you get an explanatory message and the dead entry is dropped from the recent list. Reopening the last workspace at launch follows exactly the same rule — if that folder was emptied or deleted between sessions, Fetchpier writes nothing into it, says why, drops it, and starts with no workspace open. What makes a folder a workspace is the marker Fetchpier put there when it was created, not the folder merely existing. Creating a brand-new workspace is a separate, explicit action from opening an existing one. Each workspace contains:

• requests/ — the tree you author. Sub-folders are “collections”, .http files are individual requests, and folders nest arbitrarily to form sub-collections.
• environments/<name>/config.json — one folder per named environment, each with its own variable set. The folder is named after the environment.
• environments/<name>/.state/cookies.json — the cookie jar for that environment (it lives next to its config, so a rename or delete carries the cookies with it).
• requests/.runs/*.http — the per-send activity log (one .http record per request sent).
• requests/.state/ui-state.json — per-request UI state (which editor sub-tab and response sub-tab were last active), keyed by the request’s stable identifier.
• requests/.state/tree-state.json — which collection folders are expanded in the sidebar tree, so the layout is restored on the next launch.
• .fetchpier/.state/workspace-state.json — personal, machine-local workspace state: the set of open tabs (and which one is active) and the active-environment selection, so your working set and selected environment are restored on the next launch.
• .fetchpier/settings.json — workspace-level HTTP defaults that travel with the team.
• .fetchpier/certs/ — workspace-scoped TLS material (CAs and client certificates).
• .env (optional, at the workspace root) — dotenv file used as a source of values for {{$env.NAME}} references inside environment variables.

A brand-new workspace starts with one environment. Creating a workspace also creates an environment named Default holding a single baseUrl variable, and records it as the selected one, so you are already positioned in an environment: the selector shows it, {{baseUrl}} resolves, a cookie jar is in use, and a command-line run finds the environment it falls back to. It is an ordinary environment in every other respect — renamable, editable, deletable. Opening a workspace never does this: an existing workspace with no environments stays that way, and deleting the last environment is durable rather than undone at the next launch.

When a workspace has no .gitignore at open time, Fetchpier creates one with a sensible default — excluding the personal-state directories **/.state/, the per-send activity logs **/.runs/, and the optional .env — and shows a one-time toast about it. The workspace-shared .fetchpier/ directory is deliberately not ignored, so team-level HTTP defaults and TLS material travel with the workspace under version control. If the workspace already has a .gitignore — even an empty file — Fetchpier never modifies it: the file’s presence is your flag of ownership.

The workspace’s file layout is the source of truth. Renaming a folder renames a collection; deleting a .http file deletes a request; editing a .http file in another editor and saving it is reflected immediately in the UI thanks to a folder watcher.

The tree survives a broken watcher. File tracking can stop for reasons outside the app’s control — the watched folder is deleted or renamed from another program, the machine sleeps and wakes, or the workspace lives on a network share that never reports changes. None of these interrupt you: the tree is re-read whenever the window regains focus, so the ordinary rhythm of leaving to edit elsewhere and coming back is itself the refresh. Tracking is also re-established automatically after the machine resumes, and after a failure it is retried a few times. Only when those retries are exhausted does a notice appear, explaining that automatic tracking has stopped, that the tree still refreshes on focus, and that reopening the workspace restores it. A failure the app can fix on its own is never surfaced.

You can close the current workspace without opening another. Closing stops file watching and all further access to that folder, clears its tabs, and returns the app to the no-workspace state. If a tab has unsaved changes, the normal save/discard/cancel prompt runs before anything is closed.

What is shared and what stays local

Fetchpier has no embedded database. The workspace’s plain files are the durable data model:

Data	Location	Share it?
Requests	requests/**/*.http	Yes.
Environments	environments/<id>/config.json	Yes; secret values are ciphertext.
Workspace settings	.fetchpier/settings.json	Yes.
Secret manifest	.fetchpier/secrets.json	Yes; it contains no workspace key.
Workspace certificates	.fetchpier/certs/	Yes, subject to your security policy.
Cookies	environments/<id>/.state/cookies.json	No, ignored by default.
Activity records	requests/.runs/*.http	No, ignored by default.
Tab, tree, and per-request UI state	.state/ files	No, ignored by default.
.env values	.env at the workspace root	No, ignored by default.

Application settings, app-global certificates, window state, and the locally wrapped workspace key live in the application’s user-data folder rather than the workspace.

Workspace-content writes are atomic: Fetchpier replaces a file as a unit, so a crash, full disk, or power loss during a save leaves the complete prior version or the complete new version rather than a truncated file. User-selected export destinations and CLI report files are outside this guarantee. Importing a certificate likewise never overwrites a different certificate’s stored bytes: identical material is reused, and different material that would collide on its generated filename is stored alongside the existing one.

Back up a workspace by copying its folder. Audit it with Git history, and synchronize it with the file-sharing workflow your team controls.