Concepts

Noodle is a terminal REST client built around a simple idea: HTTP requests are files on disk. Here are the concepts that make it work.

Collection

A collection is a directory of .yml request files on disk. Everything starts here.

my-collection/
├── list-users.yml
├── get-user.yml
├── auth/
│   ├── login.yml
│   └── refresh.yml
└── .environments/
    ├── development.env
    └── production.env

Point Noodle at a collection directory with --collection (default: ./collections) and it builds the TUI from whatever it finds on disk.

Collections are version-control friendly — every request is a text file, every environment is a .env file. Commit them, share them, diff them.

Request

A request is a single .yml file representing one HTTP call. Every request has an ID that matches its relative path: auth/login.yml becomes request "auth/login".

A minimal request file:

method: GET
url: https://api.example.com/users

Requests support headers, query parameters, body (JSON, form, text, binary), authentication, and settings like timeout.

The request file is the source of truth. Edit it in the TUI or open it in your editor — both work.

Folder

A folder is a subdirectory that groups related requests. Folders can optionally define overrides — headers and auth that propagate to all child requests.

my-collection/
├── auth/
│   ├── folder.yml     ← overrides: auth: { type: bearer, token: $TOKEN }
│   ├── login.yml      ← inherits bearer auth from folder
│   └── refresh.yml    ← inherits bearer auth from folder
└── public/
    └── status.yml     ← no folder.yml, no overrides

Folder overrides merge additively: a folder header only applies if the request doesn’t already define the same key. Requests can opt out by setting their own auth explicitly.

Folders are also how Noodle’s auth inheritance works — set auth once on a folder, and every request inside it picks it up.

Environment

An environment is a dotenv file (.env) under <collection>/.environments/. It holds key-value pairs for variable substitution.

.environments/development.env

API_URL=http://localhost:3000
API_KEY=dev-abc123
_color=green

.environments/production.env

API_URL=https://api.example.com
API_KEY=prod-xyz789
_color=red

The _color key is special — it sets the badge color in the sidebar. All other keys are available as $VARNAME templates.

Cycle between environments with Ctrl+P or open the environment editor with e.

Variable Substitution

Noodle replaces $VARNAME tokens in request fields with values from the active environment. Supported in:

• URL (url: "https://$API_URL/users")
• Headers (value: $TOKEN)
• Query parameters
• Request body
• Authentication fields
• File paths

This is how you keep secrets out of version control and reuse the same request across dev/staging/production.

Pane

The TUI is split into three panes:

• Sidebar — browse collection tree, select requests
• Request — inspect and edit the selected request
• Response — view response body, headers, and timing

Press Ctrl+L to toggle between stacked (vertical) and side-by-side layout.

Focus

Focus determines which pane receives keyboard input. The active pane gets a cyan border.

• Tab / Shift+Tab — cycle focus through sidebar → request → response
• Escape — return to browse mode
• Return — enter edit mode on the focused field

When focused on the request pane in browse mode, arrow keys navigate fields. Hit Return to edit a value, Escape to cancel, Space to toggle a header or param on/off.