Noodle Use

noodle-use

Terminal REST client. YAML files on disk. Dotenv environments. Prefer supported non-interactive automation commands; use file-level operations for richer collection edits. No Bun dependency.

Response files

Use noodle request run <id> --collection <dir> --output <file> --json to download any response into a new file, preserving original transport bytes after normal HTTP decompression. Choose a user-authorized destination; existing files are never overwritten. Completed responses are saved even when HTTP or response checks fail, and the failures remain nonzero. Pre-script/transport failures create no output. Downloads contain original server data without redaction. Binary JSON results contain metadata only (bodyKind, size, contentType, optional filename, and successful outputFile); never expect body text, bytes, or base64. JSON body captures/assertions fail for binary responses; metadata expressions still work. Binary TUI history and Runner details retain metadata without a downloadable body. Humans use Save file (Save As, initially Downloads) and Open in default app; only PNG/JPEG/static WebP/GIF first frame have native previews, with explicit activation above 5 MiB. See automation for exit and diagnostic behavior.

For human-readable single-request inspection, add --body, --headers, or --cookies to noodle request run. These details use the redacted result, escape terminal control characters, and mask received-cookie values. --json remains one envelope and includes received-cookie metadata; binary bodies are never printed.

Quick routing

When bundled references do not answer the question, consult the online documentation index. Start with its abridged documentation and fetch the complete documentation only if needed. Check noodle --version before relying on features described online, since the site may document a newer version. Routine collection tasks should use bundled references without requiring network access.

Critical rules

These apply to ALL operations. Read before any workflow.

Non-interactive CLI first

Do NOT import noodle's internal modules or run bun. Never run noodle in TUI mode; that's for humans. Use supported non-interactive commands (workspace list, collection ..., request ..., environment set, secret ..., cookie ..., import, and export) when they fully express the task. Use direct .yml, .env, and .js edits for folders, request bodies, auth, headers, params, inline or external pre/post scripts and tests, captures, assertions, new environment files, secret declarations, and conversions not supported by the CLI. Pass --json when output will be consumed programmatically.

Foreign scripts

Import preserves only scripts whose compatibility can be established by parsing JavaScript and checking free identifiers against Noodle's contract and a conservative ECMAScript allowlist. Read ordered data.warnings in --json: itemPath, original phase, format, code, reason, unsupportedGlobals, and safe message. Never reconstruct omitted scripts with regex replacements. Imports retaining scripts or tests require a new collection; current or existing targets are rejected before writes. Postman pre-request events map to collection/folder/request pre; only request test events map to tests. Insomnia preserves request pre/post hooks only. Foreign APIs, plugins, modules, duplicate Postman phases, disabled events, external Postman sources, API aliases, dynamic access, reflection, and async source are left unconverted. Script-free requests import normally. See import details.

Variable syntax

$VARNAME (no braces), where names match ^\w+$. Use $$ for a literal dollar: $$NAME sends $NAME, while $$$NAME sends a literal $ followed by the resolved value. Values resolve once; substituted values are not scanned again. In request YAML substitution applies to url; enabled header values; enabled query-param names and values; path_params names and values; body; enabled form_data names and values; file_path; supported auth string fields and enabled OAuth 2 additional parameters; and string values nested inside assertion expectations. Disabled entries are preserved exactly until enabled. Every evaluated reference must resolve from the selected environment or a committed capture/script RunScope value from an earlier request in the same collection run.

Random and time body values

Use $random.uuid, $random.email(), or $random.number({"min":18,"max":80}) in JSON, text/XML bodies and enabled text-valued form fields. Calls take JSON literals, generate once per occurrence before pre-scripts, and reuse the existing random catalog, except seed. JSON strings escape generated text; standalone placeholders preserve JSON types. $$random.uuid is literal. URLs, headers, auth, form names and file paths do not support these generators. See body templates for quoting, limits, and lifecycle rules.

Use $time.now for Unix milliseconds, $time.unix for Unix seconds, and $time.iso for an ISO timestamp in the same body fields. They share one instant per request execution. All existing noodle.time methods are available with JSON arguments, such as $time.format("2026-01-01", "YYYY-MM-DD"). The body editor and text form values autocomplete both namespaces with descriptions, signatures, and examples. See time body templates.

Response capture

Use a top-level capture mapping to pass response values to later requests in one ordered collection run:

capture:
  user_id:
    value: body.id
  access_token:
    value: body.access_token
    persist: secret
  optional_trace:
    value: headers.x-trace
    enabled: false

Names use ^\w+$. Every entry is an object with required value, optional persist: secret|environment, and optional enabled: false; scalar shorthand is invalid. Expressions use the same status, response.time, case-insensitive headers.<name>, and JSON body path grammar as assertions and are not variable-substituted. Disabled declarations produce no results, failures, summary counts, timeline outcomes, RunScope mutations, or writes. Environment values load first, RunScope values override them, and the latest successful capture or script write wins. Missing or invalid traversal fails without creating or replacing a variable. Successful values from the same block still commit before post and assertions, so the same request's post script can read them. On manual TUI sends and CLI request run, successful captures with persist update the active or selected environment even when HTTP status, post, or a later assertion fails, using the captured value rather than a post overwrite. Missing environments and write failures fail that capture while preserving the response and other successful writes. collection run and the TUI collection Runner always keep captures transient. Secret capture values and captures from sensitive response headers are fully redacted from TUI and JSON capture results. Human users edit persistence with the Capture row Select; Run Collection remains a transient result inspector.

Assertions and declarative execution

Use a top-level assert list for response contracts:

assert:
  - expression: status
    operator: equals
    value: 201
  - expression: body.user.id
    operator: isNumber
  - expression: headers.Content-Type
    operator: contains
    value: application/json
  - expression: response.time
    operator: lt
    value: 500

Operators without value: exists, notExists, isString, isNumber, isBoolean, isArray, isObject, isNull, notNull. Operators with value: equals, notEquals, gt, gte, lt, lte, contains, notContains, matches. Missing is distinct from JSON null. Timing uses milliseconds; headers are case-insensitive; strings and regex are case-sensitive. Equality is typed recursive JSON equality with no coercion, array order matters, and object key order does not. Regex uses JavaScript syntax without flags, is unanchored unless the pattern contains anchors, and rejects unsafe or unsupported constructs.

Every manual send, request run, collection run, and TUI Runner request uses this order:

1. Merge folder overrides.
2. Overlay the current RunScope for substitution.
3. Substitute the request once.
4. Run inherited and request pre blocks against a staged prepared copy.
5. Commit successful script request and RunScope mutations.
6. Send the prepared request.
7. Evaluate and commit captures.
8. Run optional post-response processing and atomically commit successful RunScope and URL-scoped cookie changes.
9. Evaluate assertions, including after post failure.
10. Run optional read-only scripted tests, including after HTTP, capture, post, or assertion failure.

Use scripts.pre for synchronous or async request preparation and scripts.post for response extraction or conditional processing that cannot be expressed declaratively. Script source is literal and never variable- substituted. Noodle readers and state APIs live under the frozen noodle namespace; bare reader aliases are unavailable. Only the tests phase adds global test and expect. Pre exposes noodle.request, noodle.env, noodle.run, noodle.crypto, noodle.random, noodle.time, and captured global console APIs. Pre/post support top-level await and Promise-returning noodle.runRequest(id) and noodle.sendRequest(options); await each call. Imports, raw fetch, host APIs, timers, and background work are unavailable. Script request mutations are in-memory only. Successful pre RunScope mutations commit before HTTP and are visible to later collection requests even if later phases fail. Read the complete API and limits in schema.md.

Both phases expose frozen noodle.random.*() English test-data generators with bounded options. Each invocation has independent Faker 10.6.0 state; noodle.random.seed resets only its sequence. Use noodle.run.set to share values, and an explicit refDate plus seed for reproducible relative dates. Passwords are automatically known secrets; other generated data stays visible. IDs and passwords are test data without cryptographic security or guaranteed uniqueness. Body templates use the same generators without sharing a script invocation's seeded sequence. See the catalog and options.

Both phases expose frozen noodle.time helpers for Unix milliseconds/seconds, ISO parsing and output, pattern formatting in named timezones, and elapsed-time arithmetic. UTC is the default; a day always means 24 hours. Use now() once when multiple values must share one instant, and pass dates with explicit offsets or date-only ISO strings (midnight UTC). See the methods, tokens, and limits.

Post sees captures and the completed response, including HTTP/capture failures. It adds bounded noodle.response.text/json, metadata, case-insensitive response headers, and optional final-URL-scoped noodle.cookies.get/set/delete. Request readers reflect the final prepared HTTP leg; all request mutations are rejected. Post failure rolls back only staged post RunScope/cookie changes, preserves captures and the response, and still runs assertions. Successful post values reach later collection requests even after assertion failure. Capture persistence uses the captured value, not post overwrites, and survives post failure. Cookie writes retain deferred durability. The capability is absent for unavailable/disabled jars and sendCookies: false; response Set-Cookie capture remains enabled.

Both phases support noodle.run.set(name, value, { persist: "environment" | "secret" }) and noodle.run.unset(name, { persist: "environment" | "secret" }). Manual sends and request run save to an existing active environment; collection runs and Runner keep changes transient and report suppression. No options keep old semantics. noodle.env.get remains an initial selected-environment snapshot; noodle.run.get sees scope writes. Persistent unset suppresses the baseline until a later set/capture and secret unset removes both the vault value and declaration. Environment targets cannot change declared secrets; secret set can promote ordinary entries. Explicit durable precedence is pre, capture, post. Later transient writes do not change a saved snapshot. VM failure discards intents; storage failure keeps runtime changes but fails automation with redacted persistence diagnostics.

Treat collections containing scripts as trusted code. A script can read selected-environment secrets with noodle.env.get and place them in the URL, headers, or body sent by the following HTTP request.

Manual timeline history retains bounded, redacted pre/post outcome summaries, persistence outcomes, script/test logs, and scripted test results/errors. Source code, capture results, and RunScope values remain excluded; oversized diagnostic text and logs use [TRUNCATED] markers. Automation runs do not create timeline entries.

Scripted response tests

Use an inline tests string or a collection-relative ./path/to/file.js reference for conditional checks, loops, and related JSON assertions. Use declarative assert for simple response contracts; use scripts.post for mutations. test(name, callback) and expect(actual) are global only in tests; readers remain noodle.response, noodle.request, noodle.env, noodle.run, and final-URL noodle.cookies when enabled. Crypto, random, time, and captured console helpers remain available.

tests: |
  test("successful response has an active user", () => {
    if (noodle.response.status < 400) {
      const user = noodle.response.json().user
      expect(user.id).toBeDefined()
      expect(user.status).toBe("active")
      expect(user.roles).toContain("member")
    }
  })

Supported matchers: toBe, toEqual, toBeTruthy, toBeFalsy, toBeDefined, toBeNull, toContain, toMatch, toBeGreaterThan, toBeGreaterThanOrEqual, toBeLessThan, toBeLessThanOrEqual, toMatchSchema, toHaveProperty, toHaveLength, toBeTypeOf, and toMatchObject. Each supports .not. See the matcher reference for exact types and limits.

Tests cannot mutate request, response, RunScope, environment, or cookies. Callbacks start immediately; returned Promises and thenables are awaited and results keep declaration order. Duplicate names remain separate. Failed callbacks do not stop later tests. Top-level errors and resource limits retain completed results. Network APIs and modules are unavailable in tests; external source files use the confined host resolver. Empty source is a no-op, source is never substituted, and non-string tests values are invalid.

Read data.result.tests or data.results[].tests: { evaluated, results, logs, error?, errors?, invocations? }, with { name, passed, message, durationMs } per test. Pre/transport failures leave tests unevaluated. Failure category test covers failed callbacks and top-level errors; collection summaries include testPasses, testFailures, and testScriptErrors when tests exist. Fail-fast waits for all diagnostics. Known secrets are redacted, and human output omits log text.

Redirect and timeout safety

Noodle rejects HTTPS-to-HTTP redirects. When a redirect changes origin, it removes sensitive headers and headers containing known secrets, disables request auth, and refuses to preserve a body containing a known secret. Redirects that discard the body may continue. A configured request timeout is a transport failure; caller-triggered cancellation remains owned by the caller. Keep credentials in declared secret variables so Noodle can apply these protections.

For chaining, place the producer before its consumers and use $captured_name in later request fields. collection run and the TUI Runner share one transient scope in collection order after target and tag filtering, with a fresh scope for each dataset row; request run and manual sends use isolated scopes. In the Runner, choose requests or folders, environment, Include tags, Exclude tags, fail-fast, delay, and an optional Data file, then inspect ordered Results. See automation and annotated create/fetch/delete and login examples.

File extension

.yml NOT .yaml. Requests are one-per-file. Folders use folder.yml.

ID convention

File at auth/login.yml → ID = "auth/login" (relative path minus .yml). Used for: tree navigation, file I/O, timeline storage, and UI state. Timeline YAML lives at .timeline/auth/login.yml; large bodies may be stored beside it in .timeline/auth/login.yml.bodies/. Treat both as generated, sensitive data and do not edit body references manually.

Environment format

Dotenv-style .env files in <collection>/.environments/. Variable names match ^\w+$; _color is reserved. KEY=value declares a public variable, preserving everything after the first = exactly, including trailing spaces. # KEY=value disables it. # @secret KEY immediately followed by a blank KEY= declares an enabled secure value; use a commented blank placeholder to disable it. Secret values live in the OS credential vault, with process.env.KEY taking precedence. On headless Linux, the vault requires a running Secret Service provider such as GNOME Keyring or KWallet, a user D-Bus session, and an unlocked keyring collection; see the Linux secret storage setup guide when secret set reports that the login collection is unavailable. For unattended automation, prefer the same-named process environment variable or an external secret manager. _color=<name> sets sidebar badge color. Valid colors: primary, secondary, accent, error, warning, success, info, text, textMuted, background, backgroundPanel, backgroundElement, border, borderActive, borderSubtle.

Folder inheritance

• folder.yml applies only inside its folder directory. A root-level folder.yml is ignored by the loader.
• Request and non-root folder tags are case-sensitive, non-empty trimmed strings. A request's effective tags are the union of its own tags and all ancestor folder tags. Tags cannot be removed downstream.
• Headers merge additively: folder header only applies if child request doesn't have the same header key.
• Auth: request with type: inherit uses nearest parent folder's auth override. Walk up the tree until a folder with an auth override is found.
• folder.yml format:

meta:
  name: Display Name
  seq: 5
tags:
  - smoke
  - users
headers:
  X-API-Key: $API_KEY
auth:
  type: bearer
  token: $TOKEN

meta and tags are optional. meta.seq controls sort order (lower = first, undefined = last). meta.name overrides display name (defaults to directory name).