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.

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). Full editing, sending, and saving is available.
• Browse mode: the directory contains request .yml files but no 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: the directory is empty. Same read-only restrictions as browse mode. Initialize via command palette or save your first request to bootstrap the collection.

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:

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

Requests support headers, query parameters, body (JSON, form, text, 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.

Cookie Jar

Noodle keeps one cookie jar per collection. It captures Set-Cookie headers from responses and sends matching cookies on later requests and redirect hops. A Cookie header written in the request wins when it has the same cookie name.

Open Cookies from the command palette to inspect and manage jars by domain. The response pane’s Cookies tab separates cookies sent on the final request leg from Set-Cookie values received in the final response.

The jar is enabled by default. Disable it for a collection in Settings, or turn off Send Cookies for one request. The request control suppresses outgoing jar cookies but still captures response cookies. Jars use OS-vault-backed encryption under ~/.config/noodle/cookies/; when the vault is unavailable, Noodle uses a mode-0600 plaintext file and displays a persistent warning.

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, filter JSON with JSONPath
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 e 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.