Vibecode Insomnia

You are building a lean indie version of Insomnia.

Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt.

===== README.md =====
# Insomnia · indie build

A file-based API client for one developer, with a small local web UI: requests as YAML in git, secrets only from the shell, assertions and chaining, history with diffs, and an importer for Insomnia's v4 export. Bruno is the free open-source answer; this is the version you can read in an afternoon.

Estimated effort: **one sitting**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts.

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Runtime | Node 22, a CLI plus a localhost page | no cloud, no sync |
| Storage | YAML in git, SQLite history | diffable and disposable respectively |

## Before you start

Have every one of these ready. The plan assumes them from step one.

- [ ] **Node.js 22 or newer** · free
  - Why: Everything in this build runs on it: the server, the scripts, the tests.
  - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards.
  - Verify: node --version prints v22 or higher
- [ ] **A terminal and a code editor** · free
  - Why: Every step below is a command you type or a file you edit.
  - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal.
  - Verify: You can open a folder and run a command in its terminal
- [ ] **Git** · free
  - Why: History for your code, and the way most hosts deploy.
  - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists.
  - Verify: git --version prints a version
- [ ] **Try Bruno first** · free
  - Why: The fork that stayed file-based and offline. Use it unless you want your own.
  - Get it: usebruno.com
- [ ] **Your Insomnia export (v4 JSON)** · free
  - Why: Phase 5 imports it.
  - Get it: Insomnia > Preferences > Data > Export Data > Insomnia v4 JSON.

## Quick start

```sh
mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
mkdir -p requests environments && cp .env.example .env
```

Then copy `.env.example` to `.env` and fill in the values it documents.

## Honest limits

This build deliberately does not replace:

- Cloud sync, RBAC, mocks, gRPC: the seat price.
- the desktop GUI
- cloud projects and RBAC
- the mock server
- GraphQL and gRPC tooling

If one of those is essential to you, that is the reason to keep paying for Insomnia, and the README should say so rather than pretend.

===== BRIEF.md =====
# Build brief · Insomnia

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me a file-based API client to replace Insomnia for one developer. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. Bruno is the open-source answer and is free; use it unless you want a version you can read in an afternoon.

### Stack (fixed, do not substitute)

- Node 22, a CLI plus an optional local web UI served on localhost. Requests as YAML in git. No cloud.

### Data model (create this before Phase 1)

- requests/<name>.yaml (method, url, headers, query, body, auth, asserts), environments/<name>.yaml, history.sqlite.

### Phase 1 · Runner

Build: run one request with variable substitution from an environment, secrets from process env only, pretty output with latency.
Done when: GET and POST work, a missing variable fails naming itself, and no secret can be committed.
Do not build yet: UI.

### Phase 2 · Assertions and chaining

Build: status and JSON-path asserts with non-zero exit; capture a response value into a variable for later requests in a folder run.
Done when: a login feeds a token to the next call and a wrong status exits 1.

### Phase 3 · History

Build: every run to SQLite, list and diff commands.
Done when: diff shows a changed field between the last two runs.

### Phase 4 · Local UI

Build: a localhost page listing requests, running one, and showing the response with syntax highlighting. Server-rendered, minimal JS.
Done when: a request edited in the file appears in the UI on reload and runs from a button.

### Phase 5 · Import

Build: import an Insomnia export (v4 JSON) into the YAML layout.
Done when: an exported workspace runs unchanged.

### Out of scope (and why)

- Cloud sync, RBAC, mocks, gRPC. That is the seat price.

### README must contain

- Secrets never live in files.
- The import path.

===== AGENTS.md =====
# Agent instructions · Insomnia indie build

- Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Node 22, a CLI plus a localhost page, YAML in git, SQLite history. Do not substitute.
- Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes.
- Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name.
- Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced.
- Do not invent cryptography, security guarantees, APIs or compliance claims.
- Add a focused test for every destructive, security-sensitive or data-loss path the plan names.
- Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".


===== BUILD_PLAN.md =====
# Build plan · Insomnia

A file-based API client for one developer, with a small local web UI: requests as YAML in git, secrets only from the shell, assertions and chaining, history with diffs, and an importer for Insomnia's v4 export. Bruno is the free open-source answer; this is the version you can read in an afternoon.

Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note.

## Phase 1 · Runner

One request from YAML with substitution; secrets from the shell only.

### Steps

1. Create the CLI and define requests/*.yaml and environments/*.yaml

   ```sh
   mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
   mkdir -p requests environments && cp .env.example .env
   ```

2. Implement api run <file> --env <name> with {{var}} and {{env.NAME}} substitution and pretty output

### Done when

- [ ] GET and POST work
- [ ] A missing variable fails naming itself
- [ ] No secret can be committed

## Phase 2 · Assertions and chaining

Non-zero exit on failure; a token captured into the next call.

### Steps

1. Status and JSON-path asserts, exit 1 with a diff
2. capture into variables for later requests in a folder run

### Done when

- [ ] A login feeds a token to the next call
- [ ] A wrong status exits 1

## Phase 3 · History

Every run to SQLite; list and diff.

### Steps

1. Record runs with status, latency, size and body hash
2. api history and api diff commands

### Done when

- [ ] Diff shows a changed field between the last two runs

## Phase 4 · Local UI

A localhost page listing requests, running one, showing the response.

### Steps

1. Serve a server-rendered page on API_UI_PORT listing requests
2. Run from a button and show the highlighted response

### Done when

- [ ] A request edited in the file appears on reload and runs from a button

## Phase 5 · Import

Insomnia v4 becomes YAML.

### Steps

1. Parse the v4 export into requests and environments
2. Run an imported workspace unchanged

### Done when

- [ ] An exported workspace runs after import

## Not in this build

- Cloud sync, RBAC, mocks, gRPC: the seat price.

## After v1, if you want it

- OpenAPI import
- Response schema assertions

===== .env.example =====
# Copy to .env and fill in. Never commit .env; this file documents it.

# Optional. Localhost port for the small UI.
API_UI_PORT=4880

# Optional · secret. Example secret referenced as {{env.API_TOKEN}}.
API_TOKEN=...

You are building a lean indie version of Insomnia.

Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt.

===== README.md =====
# Insomnia · indie build

A file-based API client for one developer, with a small local web UI: requests as YAML in git, secrets only from the shell, assertions and chaining, history with diffs, and an importer for Insomnia's v4 export. Bruno is the free open-source answer; this is the version you can read in an afternoon.

Estimated effort: **one sitting**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts.

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Runtime | Node 22, a CLI plus a localhost page | no cloud, no sync |
| Storage | YAML in git, SQLite history | diffable and disposable respectively |

## Before you start

Have every one of these ready. The plan assumes them from step one.

- [ ] **Node.js 22 or newer** · free
  - Why: Everything in this build runs on it: the server, the scripts, the tests.
  - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards.
  - Verify: node --version prints v22 or higher
- [ ] **A terminal and a code editor** · free
  - Why: Every step below is a command you type or a file you edit.
  - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal.
  - Verify: You can open a folder and run a command in its terminal
- [ ] **Git** · free
  - Why: History for your code, and the way most hosts deploy.
  - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists.
  - Verify: git --version prints a version
- [ ] **Try Bruno first** · free
  - Why: The fork that stayed file-based and offline. Use it unless you want your own.
  - Get it: usebruno.com
- [ ] **Your Insomnia export (v4 JSON)** · free
  - Why: Phase 5 imports it.
  - Get it: Insomnia > Preferences > Data > Export Data > Insomnia v4 JSON.

## Quick start

```sh
mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
mkdir -p requests environments && cp .env.example .env
```

Then copy `.env.example` to `.env` and fill in the values it documents.

## Honest limits

This build deliberately does not replace:

- Cloud sync, RBAC, mocks, gRPC: the seat price.
- the desktop GUI
- cloud projects and RBAC
- the mock server
- GraphQL and gRPC tooling

If one of those is essential to you, that is the reason to keep paying for Insomnia, and the README should say so rather than pretend.

===== BRIEF.md =====
# Build brief · Insomnia

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me a file-based API client to replace Insomnia for one developer. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. Bruno is the open-source answer and is free; use it unless you want a version you can read in an afternoon.

### Stack (fixed, do not substitute)

- Node 22, a CLI plus an optional local web UI served on localhost. Requests as YAML in git. No cloud.

### Data model (create this before Phase 1)

- requests/<name>.yaml (method, url, headers, query, body, auth, asserts), environments/<name>.yaml, history.sqlite.

### Phase 1 · Runner

Build: run one request with variable substitution from an environment, secrets from process env only, pretty output with latency.
Done when: GET and POST work, a missing variable fails naming itself, and no secret can be committed.
Do not build yet: UI.

### Phase 2 · Assertions and chaining

Build: status and JSON-path asserts with non-zero exit; capture a response value into a variable for later requests in a folder run.
Done when: a login feeds a token to the next call and a wrong status exits 1.

### Phase 3 · History

Build: every run to SQLite, list and diff commands.
Done when: diff shows a changed field between the last two runs.

### Phase 4 · Local UI

Build: a localhost page listing requests, running one, and showing the response with syntax highlighting. Server-rendered, minimal JS.
Done when: a request edited in the file appears in the UI on reload and runs from a button.

### Phase 5 · Import

Build: import an Insomnia export (v4 JSON) into the YAML layout.
Done when: an exported workspace runs unchanged.

### Out of scope (and why)

- Cloud sync, RBAC, mocks, gRPC. That is the seat price.

### README must contain

- Secrets never live in files.
- The import path.

===== AGENTS.md =====
# Agent instructions · Insomnia indie build

- Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Node 22, a CLI plus a localhost page, YAML in git, SQLite history. Do not substitute.
- Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes.
- Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name.
- Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced.
- Do not invent cryptography, security guarantees, APIs or compliance claims.
- Add a focused test for every destructive, security-sensitive or data-loss path the plan names.
- Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".


===== BUILD_PLAN.md =====
# Build plan · Insomnia

A file-based API client for one developer, with a small local web UI: requests as YAML in git, secrets only from the shell, assertions and chaining, history with diffs, and an importer for Insomnia's v4 export. Bruno is the free open-source answer; this is the version you can read in an afternoon.

Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note.

## Phase 1 · Runner

One request from YAML with substitution; secrets from the shell only.

### Steps

1. Create the CLI and define requests/*.yaml and environments/*.yaml

   ```sh
   mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
   mkdir -p requests environments && cp .env.example .env
   ```

2. Implement api run <file> --env <name> with {{var}} and {{env.NAME}} substitution and pretty output

### Done when

- [ ] GET and POST work
- [ ] A missing variable fails naming itself
- [ ] No secret can be committed

## Phase 2 · Assertions and chaining

Non-zero exit on failure; a token captured into the next call.

### Steps

1. Status and JSON-path asserts, exit 1 with a diff
2. capture into variables for later requests in a folder run

### Done when

- [ ] A login feeds a token to the next call
- [ ] A wrong status exits 1

## Phase 3 · History

Every run to SQLite; list and diff.

### Steps

1. Record runs with status, latency, size and body hash
2. api history and api diff commands

### Done when

- [ ] Diff shows a changed field between the last two runs

## Phase 4 · Local UI

A localhost page listing requests, running one, showing the response.

### Steps

1. Serve a server-rendered page on API_UI_PORT listing requests
2. Run from a button and show the highlighted response

### Done when

- [ ] A request edited in the file appears on reload and runs from a button

## Phase 5 · Import

Insomnia v4 becomes YAML.

### Steps

1. Parse the v4 export into requests and environments
2. Run an imported workspace unchanged

### Done when

- [ ] An exported workspace runs after import

## Not in this build

- Cloud sync, RBAC, mocks, gRPC: the seat price.

## After v1, if you want it

- OpenAPI import
- Response schema assertions

===== .env.example =====
# Copy to .env and fill in. Never commit .env; this file documents it.

# Optional. Localhost port for the small UI.
API_UI_PORT=4880

# Optional · secret. Example secret referenced as {{env.API_TOKEN}}.
API_TOKEN=...

You are building a production product version of Insomnia.

Create the following project files first, then implement the application by following them. Keep the files updated as decisions change. Do not collapse this into a single README or prompt.

===== PRODUCT.md =====
# Insomnia · product brief

## Problem

Insomnia went cloud-first and the open-source fork Bruno exists because of it. A file-based client with environments and assertions is a sitting, and the free tier already covers most solo use. The seat price is for teams and RBAC.

## Product outcome

API tests in the repo, run in CI, with no synced workspace to leak a secret.

## Target user

A builder who needs a maintainable product foundation, not a one-off demo.

## Required capabilities

- Node

## Explicit non-goals for v1

- Cloud sync, RBAC, mocks, gRPC: the seat price.
- the desktop GUI
- cloud projects and RBAC
- the mock server
- GraphQL and gRPC tooling

## Success criteria

- No secrets in files
- CI passes on a real collection

===== BRIEF.md =====
# Build brief · Insomnia

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me a file-based API client to replace Insomnia for one developer. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. Bruno is the open-source answer and is free; use it unless you want a version you can read in an afternoon.

### Stack (fixed, do not substitute)

- Node 22, a CLI plus an optional local web UI served on localhost. Requests as YAML in git. No cloud.

### Data model (create this before Phase 1)

- requests/<name>.yaml (method, url, headers, query, body, auth, asserts), environments/<name>.yaml, history.sqlite.

### Phase 1 · Runner

Build: run one request with variable substitution from an environment, secrets from process env only, pretty output with latency.
Done when: GET and POST work, a missing variable fails naming itself, and no secret can be committed.
Do not build yet: UI.

### Phase 2 · Assertions and chaining

Build: status and JSON-path asserts with non-zero exit; capture a response value into a variable for later requests in a folder run.
Done when: a login feeds a token to the next call and a wrong status exits 1.

### Phase 3 · History

Build: every run to SQLite, list and diff commands.
Done when: diff shows a changed field between the last two runs.

### Phase 4 · Local UI

Build: a localhost page listing requests, running one, and showing the response with syntax highlighting. Server-rendered, minimal JS.
Done when: a request edited in the file appears in the UI on reload and runs from a button.

### Phase 5 · Import

Build: import an Insomnia export (v4 JSON) into the YAML layout.
Done when: an exported workspace runs unchanged.

### Out of scope (and why)

- Cloud sync, RBAC, mocks, gRPC. That is the seat price.

### README must contain

- Secrets never live in files.
- The import path.

===== ARCHITECTURE.md =====
# Architecture · Insomnia

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Runtime | Node 22, a CLI plus a localhost page | no cloud, no sync |
| Storage | YAML in git, SQLite history | diffable and disposable respectively |

## Modules

Each module has one owner concern and a documented way to replace it.

| Module | Owns | How to replace it |
| --- | --- | --- |
| Runner | substitution and fetch | The core |
| Asserts | status and paths | Add schemas |
| UI | the localhost page | Optional |
| Import | Insomnia v4 | Add Postman v2.1 |

## Configuration

Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists.

- `API_UI_PORT` · optional · Localhost port for the small UI.
- `API_TOKEN` · optional, secret · Example secret referenced as {{env.API_TOKEN}}.

## Production baseline

- Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives.
- Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised.
- Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts.
- Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists.
- Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path.

## Decision records

For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it.

===== AGENTS.md =====
# Agent instructions · Insomnia product build

- Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Node 22, a CLI plus a localhost page, YAML in git, SQLite history.
- Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit.
- Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present.
- Never invent cryptography or silently weaken a requirement to make a check pass.
- Put every external service behind an interface with a deterministic fake for tests.
- Add migrations and rollback or recovery notes for every persistent data change.
- Log useful operational context without credentials, tokens, passwords or personal data.
- Update documentation and run every check before completing a milestone.


===== MILESTONES.md =====
# Delivery milestones · Insomnia

Estimated effort: **one sitting** for the indie phases; the production-only milestones add the trust and operability layer.

## M1 · Runner

One request from YAML with substitution; secrets from the shell only.

### Steps

1. Create the CLI and define requests/*.yaml and environments/*.yaml

   ```sh
   mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
   mkdir -p requests environments && cp .env.example .env
   ```

2. Implement api run <file> --env <name> with {{var}} and {{env.NAME}} substitution and pretty output

### Done when

- [ ] GET and POST work
- [ ] A missing variable fails naming itself
- [ ] No secret can be committed

## M2 · Assertions and chaining

Non-zero exit on failure; a token captured into the next call.

### Steps

1. Status and JSON-path asserts, exit 1 with a diff
2. capture into variables for later requests in a folder run

### Done when

- [ ] A login feeds a token to the next call
- [ ] A wrong status exits 1

## M3 · History

Every run to SQLite; list and diff.

### Steps

1. Record runs with status, latency, size and body hash
2. api history and api diff commands

### Done when

- [ ] Diff shows a changed field between the last two runs

## M4 · Local UI

A localhost page listing requests, running one, showing the response.

### Steps

1. Serve a server-rendered page on API_UI_PORT listing requests
2. Run from a button and show the highlighted response

### Done when

- [ ] A request edited in the file appears on reload and runs from a button

## M5 · Import

Insomnia v4 becomes YAML.

### Steps

1. Parse the v4 export into requests and environments
2. Run an imported workspace unchanged

### Done when

- [ ] An exported workspace runs after import

## M6 · Share with a team (production only)

Publish the CLI and run the collection in CI.

### Steps

1. Publish privately or as a git dependency
2. Run in CI with secrets from the CI store

### Done when

- [ ] A teammate runs the collection
- [ ] CI fails on a failed assertion

===== OPERATIONS.md =====
# Operations · Insomnia

## Backup

The repo.

## Restore

Clone.

Do a restore drill before the first real user, and write the date here when it passes.

## Monitoring

CI status.

## Incident checklist

Rotate a leaked secret at its source.

1. Contain the issue without destroying evidence or user data.
2. Record the timeline and affected scope.
3. Rotate exposed secrets and revoke compromised sessions or credentials.
4. Restore from a verified backup when needed.
5. Document the root cause, the remediation and the regression test.

## Release gate

- [ ] No secrets in files
- [ ] CI passes on a real collection

## Launch constraint

Do not market omitted Insomnia capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered.

===== .env.example =====
# Copy to .env and fill in. Never commit .env; this file documents it.

# Optional. Localhost port for the small UI.
API_UI_PORT=4880

# Optional · secret. Example secret referenced as {{env.API_TOKEN}}.
API_TOKEN=...

# Insomnia · indie build

A file-based API client for one developer, with a small local web UI: requests as YAML in git, secrets only from the shell, assertions and chaining, history with diffs, and an importer for Insomnia's v4 export. Bruno is the free open-source answer; this is the version you can read in an afternoon.

Estimated effort: **one sitting**. Work `BUILD_PLAN.md` top to bottom · every phase ends in a check that has to pass before the next one starts.

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Runtime | Node 22, a CLI plus a localhost page | no cloud, no sync |
| Storage | YAML in git, SQLite history | diffable and disposable respectively |

## Before you start

Have every one of these ready. The plan assumes them from step one.

- [ ] **Node.js 22 or newer** · free
  - Why: Everything in this build runs on it: the server, the scripts, the tests.
  - Get it: Download the LTS installer from nodejs.org, or install with your package manager (brew install node, or nvm install 22). Restart the terminal afterwards.
  - Verify: node --version prints v22 or higher
- [ ] **A terminal and a code editor** · free
  - Why: Every step below is a command you type or a file you edit.
  - Get it: VS Code (code.visualstudio.com), Cursor or Zed. Open a folder for the project and use the editor's built-in terminal.
  - Verify: You can open a folder and run a command in its terminal
- [ ] **Git** · free
  - Why: History for your code, and the way most hosts deploy.
  - Get it: Install from git-scm.com or with your package manager, then run git init in the project folder once it exists.
  - Verify: git --version prints a version
- [ ] **Try Bruno first** · free
  - Why: The fork that stayed file-based and offline. Use it unless you want your own.
  - Get it: usebruno.com
- [ ] **Your Insomnia export (v4 JSON)** · free
  - Why: Phase 5 imports it.
  - Get it: Insomnia > Preferences > Data > Export Data > Insomnia v4 JSON.

## Quick start

```sh
mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
mkdir -p requests environments && cp .env.example .env
```

Then copy `.env.example` to `.env` and fill in the values it documents.

## Honest limits

This build deliberately does not replace:

- Cloud sync, RBAC, mocks, gRPC: the seat price.
- the desktop GUI
- cloud projects and RBAC
- the mock server
- GraphQL and gRPC tooling

If one of those is essential to you, that is the reason to keep paying for Insomnia, and the README should say so rather than pretend.

# Build brief · Insomnia

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me a file-based API client to replace Insomnia for one developer. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. Bruno is the open-source answer and is free; use it unless you want a version you can read in an afternoon.

### Stack (fixed, do not substitute)

- Node 22, a CLI plus an optional local web UI served on localhost. Requests as YAML in git. No cloud.

### Data model (create this before Phase 1)

- requests/<name>.yaml (method, url, headers, query, body, auth, asserts), environments/<name>.yaml, history.sqlite.

### Phase 1 · Runner

Build: run one request with variable substitution from an environment, secrets from process env only, pretty output with latency.
Done when: GET and POST work, a missing variable fails naming itself, and no secret can be committed.
Do not build yet: UI.

### Phase 2 · Assertions and chaining

Build: status and JSON-path asserts with non-zero exit; capture a response value into a variable for later requests in a folder run.
Done when: a login feeds a token to the next call and a wrong status exits 1.

### Phase 3 · History

Build: every run to SQLite, list and diff commands.
Done when: diff shows a changed field between the last two runs.

### Phase 4 · Local UI

Build: a localhost page listing requests, running one, and showing the response with syntax highlighting. Server-rendered, minimal JS.
Done when: a request edited in the file appears in the UI on reload and runs from a button.

### Phase 5 · Import

Build: import an Insomnia export (v4 JSON) into the YAML layout.
Done when: an exported workspace runs unchanged.

### Out of scope (and why)

- Cloud sync, RBAC, mocks, gRPC. That is the seat price.

### README must contain

- Secrets never live in files.
- The import path.

# Agent instructions · Insomnia indie build

- Read `README.md` and `BUILD_PLAN.md` before writing code. The stack is fixed: Node 22, a CLI plus a localhost page, YAML in git, SQLite history. Do not substitute.
- Work one phase at a time, in order. Do not start a phase until every "Done when" item of the previous one passes.
- Prefer the fewest moving parts that satisfy the step. No frameworks, services or dependencies the plan does not name.
- Secrets live in `.env`, never in source or logs. Keep `.env.example` current when a variable is introduced.
- Do not invent cryptography, security guarantees, APIs or compliance claims.
- Add a focused test for every destructive, security-sensitive or data-loss path the plan names.
- Run the project checks before declaring a phase complete, and record any deliberate shortcut in the README under "Tradeoffs".

# Build plan · Insomnia

A file-based API client for one developer, with a small local web UI: requests as YAML in git, secrets only from the shell, assertions and chaining, history with diffs, and an importer for Insomnia's v4 export. Bruno is the free open-source answer; this is the version you can read in an afternoon.

Phases are in dependency order. Each ends in a "Done when" list; treat an unticked item as a blocker, not a note.

## Phase 1 · Runner

One request from YAML with substitution; secrets from the shell only.

### Steps

1. Create the CLI and define requests/*.yaml and environments/*.yaml

   ```sh
   mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
   mkdir -p requests environments && cp .env.example .env
   ```

2. Implement api run <file> --env <name> with {{var}} and {{env.NAME}} substitution and pretty output

### Done when

- [ ] GET and POST work
- [ ] A missing variable fails naming itself
- [ ] No secret can be committed

## Phase 2 · Assertions and chaining

Non-zero exit on failure; a token captured into the next call.

### Steps

1. Status and JSON-path asserts, exit 1 with a diff
2. capture into variables for later requests in a folder run

### Done when

- [ ] A login feeds a token to the next call
- [ ] A wrong status exits 1

## Phase 3 · History

Every run to SQLite; list and diff.

### Steps

1. Record runs with status, latency, size and body hash
2. api history and api diff commands

### Done when

- [ ] Diff shows a changed field between the last two runs

## Phase 4 · Local UI

A localhost page listing requests, running one, showing the response.

### Steps

1. Serve a server-rendered page on API_UI_PORT listing requests
2. Run from a button and show the highlighted response

### Done when

- [ ] A request edited in the file appears on reload and runs from a button

## Phase 5 · Import

Insomnia v4 becomes YAML.

### Steps

1. Parse the v4 export into requests and environments
2. Run an imported workspace unchanged

### Done when

- [ ] An exported workspace runs after import

## Not in this build

- Cloud sync, RBAC, mocks, gRPC: the seat price.

## After v1, if you want it

- OpenAPI import
- Response schema assertions

# Copy to .env and fill in. Never commit .env; this file documents it.

# Optional. Localhost port for the small UI.
API_UI_PORT=4880

# Optional · secret. Example secret referenced as {{env.API_TOKEN}}.
API_TOKEN=...

# Insomnia · product brief

## Problem

Insomnia went cloud-first and the open-source fork Bruno exists because of it. A file-based client with environments and assertions is a sitting, and the free tier already covers most solo use. The seat price is for teams and RBAC.

## Product outcome

API tests in the repo, run in CI, with no synced workspace to leak a secret.

## Target user

A builder who needs a maintainable product foundation, not a one-off demo.

## Required capabilities

- Node

## Explicit non-goals for v1

- Cloud sync, RBAC, mocks, gRPC: the seat price.
- the desktop GUI
- cloud projects and RBAC
- the mock server
- GraphQL and gRPC tooling

## Success criteria

- No secrets in files
- CI passes on a real collection

# Build brief · Insomnia

The one-shot brief this plan expands. `BUILD_PLAN.md` (or `MILESTONES.md`) is the same sequence broken into steps and checks; where the two disagree, the plan wins.

Build me a file-based API client to replace Insomnia for one developer. Build it in phases, in the order below. Do not write the whole thing in one pass. Finish a phase, run its "Done when" check, fix what fails, and only then start the next phase. Bruno is the open-source answer and is free; use it unless you want a version you can read in an afternoon.

### Stack (fixed, do not substitute)

- Node 22, a CLI plus an optional local web UI served on localhost. Requests as YAML in git. No cloud.

### Data model (create this before Phase 1)

- requests/<name>.yaml (method, url, headers, query, body, auth, asserts), environments/<name>.yaml, history.sqlite.

### Phase 1 · Runner

Build: run one request with variable substitution from an environment, secrets from process env only, pretty output with latency.
Done when: GET and POST work, a missing variable fails naming itself, and no secret can be committed.
Do not build yet: UI.

### Phase 2 · Assertions and chaining

Build: status and JSON-path asserts with non-zero exit; capture a response value into a variable for later requests in a folder run.
Done when: a login feeds a token to the next call and a wrong status exits 1.

### Phase 3 · History

Build: every run to SQLite, list and diff commands.
Done when: diff shows a changed field between the last two runs.

### Phase 4 · Local UI

Build: a localhost page listing requests, running one, and showing the response with syntax highlighting. Server-rendered, minimal JS.
Done when: a request edited in the file appears in the UI on reload and runs from a button.

### Phase 5 · Import

Build: import an Insomnia export (v4 JSON) into the YAML layout.
Done when: an exported workspace runs unchanged.

### Out of scope (and why)

- Cloud sync, RBAC, mocks, gRPC. That is the seat price.

### README must contain

- Secrets never live in files.
- The import path.

# Architecture · Insomnia

## Stack

| Part | Choice | Why |
| --- | --- | --- |
| Runtime | Node 22, a CLI plus a localhost page | no cloud, no sync |
| Storage | YAML in git, SQLite history | diffable and disposable respectively |

## Modules

Each module has one owner concern and a documented way to replace it.

| Module | Owns | How to replace it |
| --- | --- | --- |
| Runner | substitution and fetch | The core |
| Asserts | status and paths | Add schemas |
| UI | the localhost page | Optional |
| Import | Insomnia v4 | Add Postman v2.1 |

## Configuration

Every runtime setting is an environment variable documented in `.env.example`, validated at startup, with a safe local default wherever one exists.

- `API_UI_PORT` · optional · Localhost port for the small UI.
- `API_TOKEN` · optional, secret · Example secret referenced as {{env.API_TOKEN}}.

## Production baseline

- Security: least privilege, input validation at every boundary, secret redaction in logs, rate limits on abuse-prone paths, no invented security primitives.
- Data: explicit schema and migrations, transactional writes where integrity matters, backup and restore procedures that have been exercised.
- Integrations: adapters around third-party providers, idempotent webhook or job processing, bounded retries, timeouts.
- Observability: structured logs with request or operation ids, an error-tracking hook, and health and readiness checks where a server exists.
- Quality: unit tests for domain rules, integration tests at module boundaries, one end-to-end test of the critical path.

## Decision records

For each dependency in the stack table, keep a short note: why it was chosen, its failure mode, and how it is replaced. Do not add infrastructure until a requirement in `PRODUCT.md` justifies it.

# Agent instructions · Insomnia product build

- Read `PRODUCT.md` and `ARCHITECTURE.md` before changing code. The stack is fixed: Node 22, a CLI plus a localhost page, YAML in git, SQLite history.
- Implement milestone by milestone from `MILESTONES.md`; keep each change reviewable and leave the application runnable at every commit.
- Treat authentication, payments, encryption, imports, webhooks and destructive actions as high-risk boundaries when present.
- Never invent cryptography or silently weaken a requirement to make a check pass.
- Put every external service behind an interface with a deterministic fake for tests.
- Add migrations and rollback or recovery notes for every persistent data change.
- Log useful operational context without credentials, tokens, passwords or personal data.
- Update documentation and run every check before completing a milestone.

# Delivery milestones · Insomnia

Estimated effort: **one sitting** for the indie phases; the production-only milestones add the trust and operability layer.

## M1 · Runner

One request from YAML with substitution; secrets from the shell only.

### Steps

1. Create the CLI and define requests/*.yaml and environments/*.yaml

   ```sh
   mkdir api-cli && cd api-cli && git init && npm init -y && npm pkg set type=module && npm install yaml@2
   mkdir -p requests environments && cp .env.example .env
   ```

2. Implement api run <file> --env <name> with {{var}} and {{env.NAME}} substitution and pretty output

### Done when

- [ ] GET and POST work
- [ ] A missing variable fails naming itself
- [ ] No secret can be committed

## M2 · Assertions and chaining

Non-zero exit on failure; a token captured into the next call.

### Steps

1. Status and JSON-path asserts, exit 1 with a diff
2. capture into variables for later requests in a folder run

### Done when

- [ ] A login feeds a token to the next call
- [ ] A wrong status exits 1

## M3 · History

Every run to SQLite; list and diff.

### Steps

1. Record runs with status, latency, size and body hash
2. api history and api diff commands

### Done when

- [ ] Diff shows a changed field between the last two runs

## M4 · Local UI

A localhost page listing requests, running one, showing the response.

### Steps

1. Serve a server-rendered page on API_UI_PORT listing requests
2. Run from a button and show the highlighted response

### Done when

- [ ] A request edited in the file appears on reload and runs from a button

## M5 · Import

Insomnia v4 becomes YAML.

### Steps

1. Parse the v4 export into requests and environments
2. Run an imported workspace unchanged

### Done when

- [ ] An exported workspace runs after import

## M6 · Share with a team (production only)

Publish the CLI and run the collection in CI.

### Steps

1. Publish privately or as a git dependency
2. Run in CI with secrets from the CI store

### Done when

- [ ] A teammate runs the collection
- [ ] CI fails on a failed assertion

# Operations · Insomnia

## Backup

The repo.

## Restore

Clone.

Do a restore drill before the first real user, and write the date here when it passes.

## Monitoring

CI status.

## Incident checklist

Rotate a leaked secret at its source.

1. Contain the issue without destroying evidence or user data.
2. Record the timeline and affected scope.
3. Rotate exposed secrets and revoke compromised sessions or credentials.
4. Restore from a verified backup when needed.
5. Document the root cause, the remediation and the regression test.

## Release gate

- [ ] No secrets in files
- [ ] CI passes on a real collection

## Launch constraint

Do not market omitted Insomnia capabilities as implemented. The non-goals in `PRODUCT.md` remain user-visible limitations until they are deliberately delivered.

# Copy to .env and fill in. Never commit .env; this file documents it.

# Optional. Localhost port for the small UI.
API_UI_PORT=4880

# Optional · secret. Example secret referenced as {{env.API_TOKEN}}.
API_TOKEN=...

$ choose a build depth, inspect the files, then open the complete pack in your agent