Workspace and Git

The API client keeps everything in a workspace: a folder of small, pretty-printed JSON files with one file per request. Because the files are plain text and change one at a time, a workspace diffs and merges cleanly in Git, so a team can share collections through a repository instead of a cloud account. The Git section commits, pulls, pushes and switches branches without leaving the app.

Where the workspace lives

By default the workspace is in:

~/Library/Application Support/CloakProxy/Workspace

The app saves about half a second after each change. Files whose content didn’t change aren’t rewritten, so Git and your editor see no churn.

The app also watches the folder. Every three seconds it checks for files changed by something else (a git pull in Terminal, an editor, cloakctl, an AI assistant using the MCP server) and reloads the workspace when it finds one.

Use a different folder

Keep the workspace in a Git repository you already have, or anywhere you like.

1. Click Git in the rail.

2. Click Change Folder… and choose a folder. New Folder in the panel creates one.

3. The app writes the current workspace into that folder and switches to it.

   If the folder already holds a workspace (it has a cloak-workspace.json), the app still writes the current workspace into it first, so choose an empty folder or one you’ve committed.

Show in Finder opens the current workspace folder. The folder you pick is remembered, and cloakctl uses it too unless you pass --workspace DIR.

Changing folders writes into the new folder

Change Folder… saves your current collections, environments and other files into the folder you pick before loading it. Commit or back up a folder that already has a workspace before you point the app at it.

Folder layout

• cloak-workspace.json workspace name, order of collections and environments, active environment, globals
• .gitignore, with .cloak/ added if it isn’t already listed
• Directorycollections/

  • DirectoryPetstore/

    • collection.json docs, auth, scripts, variables, docs branding, order of items
    • List pets.request.json
    • Get pet.request.json
    • DirectoryAdmin/

      • folder.json docs, auth, scripts, order of items
      • Delete pet.request.json
• Directoryenvironments/

  • Staging.environment.json
  • Production.environment.json
• Directoryspecs/

  • Petstore.yaml the spec text, as YAML or JSON
  • Petstore.meta.json
• Directoryflows/

  • Sign up.flow.json
• Directorydatasets/

  • Logins.csv
• Directorypackages/

  • helpers.js
  • npm-dayjs@1.11.13.js
• monitors.json
• comments.json only when there are comments
• Directory.cloak/ git-ignored, stays on this Mac

  • secrets.json values of secret variables
  • trash.json Recently Deleted
  • history.json request history

File or folder	Contents
cloak-workspace.json	The workspace name, the order of collections, environments, specs and flows, the active environment, and the global variables (secret values removed).
collections/<collection>/collection.json	The collection’s documentation, auth, scripts, variables (secret values removed), docs branding and the display order of its folders and requests.
<folder>/folder.json	A folder’s documentation, auth, scripts and the order of its items. Folders nest as directories.
<request>.request.json	One saved request of any protocol: method, URL, params, path variables, headers, body, auth, scripts, settings, saved examples, docs, and the protocol settings for non-HTTP requests.
environments/<name>.environment.json	An environment’s variables (secret values removed).
specs/	Each spec’s text in its own .yaml or .json file, plus a .meta.json with its name, format and linked collection.
flows/<name>.flow.json	A flow.
datasets/<name>.csv	A dataset, as CSV with a header row.
packages/<name>.js	A script package. The first line is // cloak-package: <name>.
monitors.json	Your monitors and their run history.
comments.json	Comment threads. The file is removed when the last comment is deleted.
.gitignore	Cloak Proxy makes sure it lists .cloak/: it creates the file if the folder has none, and adds the line to an existing one that doesn’t ignore .cloak/ yet. Your other lines are left alone.
.cloak/	Local state that never goes in Git: secret values, Recently Deleted and History.

How files are named

File and folder names come from the item’s name. The characters / \ : * ? " < > |, line breaks and tabs become -, leading and trailing dots and spaces are trimmed, and names are cut to 80 characters. Two items with the same name at the same level get Get user and Get user 2. Renaming or deleting an item renames or removes its file.

Each collection.json and folder.json records the order of its children. Request files and folders that aren’t in that list, such as ones added by a teammate’s merge, still load: they go after the listed items, alphabetically.

Secrets and the .cloak folder

Variables in the collection Variables tab, in environments and in Globals can be marked secret with the lock icon. When the workspace is saved:

1. Each secret variable is written to the shared JSON files with an empty value.
2. Its real value goes to .cloak/secrets.json, keyed by the collection or environment it belongs to (or globals) and the variable name.
3. .cloak/secrets.json is readable only by your macOS user (permissions 600).
4. When the workspace loads, the values are put back.

Because .cloak/ is git-ignored, a teammate who clones the repository gets the variable names with empty values. Each person fills in their own values once, and they stay on their Mac.

.cloak/ also holds trash.json (Recently Deleted) and history.json (the last 300 sent requests), which are personal and stay local for the same reason.

For credentials, the Vault is safer still: values live in the macOS Keychain, not in any file, and requests reference them as {{vault:name}}.

Only variables marked secret are kept out of Git

Anything typed directly into a request is saved in its .request.json file and committed with it. That includes header values, bodies, URLs and every field on the Authorization tab, even fields that show as dots, and access tokens fetched with Get New Access Token. Put credentials in a secret variable or the Vault and reference them as {{token}} or {{vault:api_key}} instead.

The Vault view lists API keys and tokens it finds hardcoded in your requests, collection variables and environments, so you can move them before you commit.

Version the workspace with Git

The Git section runs the system’s Git (/usr/bin/git) in the workspace folder.

123

The Git view before the workspace folder is a repository.

1. The workspace folder
2. Show in Finder and Change Folder…
3. Initialize Repository runs git init here

×

1. Click Git in the rail.

   If Git isn’t installed, the view says so. Install the Xcode Command Line Tools:

   Terminal

   xcode-select --install

2. If the folder isn’t a repository yet, click Initialize Repository.

3. To push to a remote, add one in Terminal. The app has no control for adding remotes.

   Terminal

   cd ~/Library/Application\ Support/CloakProxy/Workspace
   git remote add origin git@github.com:example/api-workspace.git

4. Make changes in the client. They appear under Changes.

5. Type a Commit message and click Commit All. Without a message the commit is named “Update API workspace”.

6. Click Push.

Git view controls

Control	What it does
Branch menu	Shows the current branch (“No commits yet” before the first commit). Pick another branch to switch to it (git checkout); the workspace reloads from that branch’s files.
New Branch…	Asks for a name, then Create & Switch branches off the current branch (git checkout -b). Uncommitted changes come along.
Pull	Runs git pull --rebase, then reloads the workspace.
Push	Runs git push.
Refresh	Reads the status, branches and history again.
Changes (n)	Every changed file from git status, with its status code: orange for modified, green ?? for new, red for deleted.
Selecting a file	Shows its diff, with added lines in green and removed lines in red. A new file shows its whole content.
Discard Changes	Restores the committed version of the selected file (git checkout HEAD -- file), or deletes it if Git doesn’t track it yet (git clean -f -- file), then reloads the workspace.
Commit message and Commit All	Stages everything (git add -A) and commits. Disabled when there are no changes.
History	The last 30 commits: short hash, date, author and subject. Shown when no file is selected.

Git’s output appears under the view after each command.

Signing in to your Git host

The app runs Git with terminal prompts turned off, so it can’t ask for a username or password. Use an SSH key, or a credential helper such as the macOS Keychain helper, that already works with git push in Terminal.

Discard Changes can't be undone

Discard Changes replaces your edits to that file with the last committed version, and deletes files Git doesn’t track. Check the diff first.

Working with a team

• Each request is its own file, so two people editing different requests never conflict. Conflicts only happen when both change the same request, folder order or environment.
• Resolve a conflict in the JSON file with your usual tool, then go back to the app. It reloads when the file changes.
• Comments in comments.json travel with the repository, so reviews and questions reach whoever pulls next.
• Secret values, history and Recently Deleted don’t travel. Everyone keeps their own.

Related

Variables and environmentsSecret variables and the Keychain Vault.

CommentsReview threads that travel with Git.

cloakctlRun the same workspace from the command line.

Security and privacyWhat stays on your Mac.