Core 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.

Folder overrides and active environment values enrich the selected request before it opens across Noodle's four panes. The collection cookie jar sends matching cookies and stores Set-Cookie values from responses.

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

Open a collection with noodle ./my-collection or --collection. Without an explicit path, Noodle uses the first existing registered collection, then the current directory. It builds the TUI from the files in that directory.

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

Press Ctrl+O to switch between previously-used collections at runtime.

Collection Modes

When you open a directory, Noodle determines its mode:

Collection mode: the directory has collection markers (.environments/ or settings.yml), or a request .yml file at its root. Full editing, sending, and saving is available.
Browse mode: the directory contains request .yml files only in subdirectories, with no root request or collection markers. Requests are visible and inspectable, but editing and sending are blocked. Initialize it from the command palette to enable collection mode.
Empty mode: no collection markers or request files were found. Same read-only restrictions as browse mode. Choose Initialize Collection in the command palette before creating or sending requests.

Use noodle collection init <path> to bootstrap collection markers from the CLI without opening the TUI.

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:

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

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

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
# @secret API_KEY
API_KEY=
_color=green

# .environments/production.env
API_URL=https://api.example.com
# @secret API_KEY
API_KEY=
_color=red

The _color key is special: it sets the badge color in the sidebar. Ordinary keys are stored in the file. # @secret NAME followed by a blank NAME= placeholder declares a secure value stored in the OS credential vault; a same-named process environment value takes precedence. Both kinds are available as $VARNAME templates.

Cycle between environments with Ctrl+U, search them with e, or open the full environment editor with F3.

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

Use secure declarations for tokens, passwords, and API keys so the values stay out of version control while the same request remains reusable across dev/staging/production.

Noodle can capture response cookies and send applicable cookies on later requests in the same collection. Open Cookies from Ctrl+P to inspect the jar. The Cookies guide covers editing, clearing, per-request controls, and storage.

Pane

The main TUI is split into four panes:

Sidebar: browse collection tree, select requests
URL bar: inspect and edit the selected request URL. Press Tab to switch between method selector and URL field.
Request: inspect and edit the selected request
Response: view response body, headers, network trace, timeline, and cookies

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 → URL bar → 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.

Command Palette

Press Ctrl+P to open the command palette: a fuzzy-filtered list of every action in Noodle. Start typing to narrow results by section, then navigate with ↑/↓ and press Return to execute.

The palette is contextual: it shows different commands depending on which view is active:

Main view (working with requests):

Section	Actions
Request	Find, new, clone, save, delete, edit, import cURL, generate code, send
Response	Copy body, switch Source/Visual, filter with JSONPath or text search
Environment	Cycle, open editor
Workspace	Switch collection, reload collection, new folder, initialize, Cookies
App	Help, theme picker, toggle layout, expand pane, undo all, about

Env editor view (when F3 is pressed):

Section	Actions
Environment	Save, new, clone, delete, cycle
App	Help, theme picker, undo all

Use it to discover features, or as a faster alternative to remembering every keybinding. It always reflects your current custom keybinds.