Open a workspace

A workspace is just a folder on disk. Bandura reads and writes files only inside the folder you open: flows, your .env, the optional bandura.json manifest, and anything else that lives there.

First launch

If no workspace is open, the Open Folder dialog appears on its own. From there:

1. Click Browse… and pick any folder. An existing repository or an empty directory both work.
2. Or click an entry in the Recent list (Bandura remembers your last eight folders across restarts).

Alongside the dialog, a short first-run checklist walks the five things worth doing once: open a folder, open a flow, run it, add an environment value, and skim the keyboard shortcuts. It remembers what you have done and stays out of the way afterwards.

Explore examples

If you would rather read working flows than start from an empty folder, Explore examples on that checklist opens a workspace of them: use-case flows, more complex ones, and a collection, with a README that walks through them in order.

The examples are built into the app, so nothing is downloaded and you are never asked where to put them. They are written into Bandura’s own storage rather than into your Documents folder, and rewritten fresh every time you open them. That is deliberate: you can edit and run them freely to see what happens, without your experiments becoming the version you read next time. It also means an app update that ships new examples simply shows them. When you want to keep something, copy it into a workspace of your own.

Later, File → Open Recent lists the same folders right in the menu, VS Code-style. More… brings the dialog back, and Clear Recently Opened empties the list. Switching folders resets the file tree and open tabs to the new location.

What a typical workspace contains

my-api-tests/
├── auth-and-orders.aether   # a flow: one file, one scenario
├── smoke.aether             # another flow
├── bandura.json             # optional: named environments + required env vars
└── .env                     # your secrets; git-ignored, never leaves your machine

None of these are required to start. An empty folder plus one .aether file is a complete setup.

The File Explorer

The File Explorer is the default sidebar view (reveal it with ⌘⇧E, toggle the sidebar with ⌘B). It shows the full workspace tree, and it stays in sync; files changed outside Bandura appear automatically.

• Create by right-clicking a folder (or the empty background) and choosing New File or New Folder. Type the name in the inline input; Enter confirms, Esc cancels. Name a file with the .aether extension and it opens straight in the flow editor.
• Rename / Delete are also on the right-click menu. Deleting asks for confirmation first; deleting a folder removes everything inside it.
• Navigate by keyboard: ↑/↓ move through rows, → expands a folder, ← collapses or steps to the parent, Home/End jump to the top/bottom.

Three buttons appear in the explorer header on hover: New file, New folder, and ＋ New project. The last of those creates a subfolder with a starter .aether file inside. Everything else lives in the File menu and the command palette (⌘⇧P): generating a flow with AI, starting from a template, and importing Postman / OpenAPI / curl.

Search & replace across the workspace

Because a flow is plain YAML, “which flows call /v1/orders?” is a text search, not a feature someone has to build into a proprietary format. Open the Search view from the Activity Bar or press ⌘⇧F.

• What it searches: .aether files and every other text file in the workspace. node_modules, .git, dist, build, out, .turbo, .next, and coverage are skipped.
• Toggles for match case, whole word, and regular expressions. A malformed regex reports the error instead of quietly showing zero results.
• Files to include takes a comma-separated list of suffixes, e.g. .aether, .yaml, to narrow the sweep.
• Results group by file with line numbers; click one to open the file, on the matching line for plain-text files.
• Replace All rewrites the matched files on disk. It asks for confirmation first, and $-sequences in the replacement are inserted literally rather than treated as capture-group references.

Renaming a header everywhere, repointing a host across a suite, updating a path after an API change. Each is one edit, then a normal Git diff to review it.

Opening files

• Click a .aether file → the flow editor (graph + code).
• Click anything else → a text editor with syntax highlighting picked by extension.
• If a file changes on disk while you have unsaved edits, Bandura never overwrites silently; a banner offers Reload or Keep my edits.

Next: Your first flow. Once the folder is a Git repository, the workspace is also the unit a teammate clones: share flows with Git. Values that differ per machine belong in variables and environments, not in the flow file.