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.

Quick routing

| Intent | Read |

|--------|------|

| Create new collection, request, folder, or environment | [workflows/create.md](workflows/create.md) |

| Configure collection metadata, history, cookies, proxy, or TLS | [workflows/create.md](workflows/create.md#configure-collection-settings) |

| Script collection discovery, validation, execution, or simple mutations | [workflows/automation.md](workflows/automation.md) |

| Refactor, rename, restructure existing collection | [workflows/organize.md](workflows/organize.md) |

| Audit collection for REST best practices and security | [workflows/evaluate.md](workflows/evaluate.md) |

| Import or export OpenAPI, Swagger, Postman, or Insomnia collections via CLI | [workflows/import.md](workflows/import.md) |

| Convert a cURL command or unsupported format at file level | [workflows/convert.md](workflows/convert.md) |

| Understand file formats, schemas, field rules | [schema.md](schema.md) |

| Understand naming conventions, ID rules, variable syntax | [reference/conventions.md](reference/conventions.md) |

| Read/write ~/.config/noodle/ settings | [reference/config.md](reference/config.md) |

| See annotated example files | [reference/examples.md](reference/examples.md) |

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 and .env edits for folders, request bodies, auth, headers, params, inline pre-request scripts, captures, assertions, new environment files, secret declarations, and conversions not supported by the CLI. Pass --json when output will be consumed programmatically.

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 successful capture from an earlier request in the same collection run.

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 wins. Missing or invalid traversal fails without creating or replacing a variable. Successful values from the same block still commit before assertions. On manual TUI sends and CLI request run, successful captures with persist update the active or selected environment even when HTTP status or a later assertion fails. 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 the request-level inline pre-script against a staged prepared copy.
5. Commit successful script request and RunScope mutations.
6. Send the prepared request.
7. Evaluate and commit captures.
8. Evaluate assertions.

Use top-level scripts.pre only for synchronous request preparation that cannot

be expressed declaratively. Script source is literal and never variable-

substituted. The sandbox exposes only request, env, run, crypto, and

captured console APIs. Imports, network calls, host APIs, timers, returned

Promises, and queued async work are unsupported. Script request mutations are

in-memory only. Script 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](schema.md#inline-pre-request-script).

Treat collections containing scripts as trusted code. Although the sandbox has

no network API, a script can read selected-environment secrets with env.get

and place them in the URL, headers, or body sent by the following HTTP request.

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; request run and manual sends use isolated scopes. In the Runner, choose requests or folders, environment, Include tags, Exclude tags, fail-fast, and delay, then inspect ordered Results. See [automation](workflows/automation.md) and [annotated create/fetch/delete and login examples](reference/examples.md#chained-requests-with-response-capture).

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

Collection settings

settings.yml at collection root supports generated collection_id plus optional

name, multiline description, timeline_max_entries, environment, cookies,

proxy, and tls fields.

Timeline retention defaults to 50 responses per request; 0 disables history.

Collection proxy mode is inherit, off, or custom. A custom proxy uses a

credential-free HTTP(S) URL plus an optional bypass list. Authentication is

configured in Settings; config stores only auth: true, while the username and

optional password live in the OS vault. URLs containing credentials or variables

are invalid. --noproxy overrides every saved policy for one TUI, `collection

run, or request run` invocation.

TLS settings support verification, a custom PEM CA bundle, and exact-host PEM

client certificates. Enter encrypted-key passphrases in Settings; config retains

only a generated secret_id. --insecure disables verification for one run.

Collection cookies are enabled by default and stored per collection. Use the

non-interactive cookie list command to inspect cookies plus storage warnings;

use cookie clear for explicit recovery because it backs up unreadable state

before resetting the jar. Plaintext fallback is mode 0600 and always reported.

Request sendCookies: false suppresses jar cookies on the outgoing request but

still captures response cookies. Cookie values are sensitive, and cookie list

includes them in both human and JSON output; never expose that output in logs.

Settings parsing is strict: malformed YAML, unknown keys, wrong types, and

invalid proxy/TLS/cookie blocks fail collection opening, auditing, and execution.

Path safety

When creating/deleting files, only operate within the collection directory. Never create files outside the collection root. IDs must not contain .., leading /, backslashes, empty path segments, or hidden path segments.

Authorization

Auth types: none, inherit, bearer, basic, ntlm, api_key, aws_sigv4, oauth1, oauth2.

• none: No auth. Omit the auth field entirely (don't write { type: none }).
• inherit: Use parent folder's auth override. Only valid when a parent folder defines auth.
• bearer: { type: bearer, token: "$TOKEN" }
• basic: { type: basic, user: "$USER", pass: "$PASS" }
• api_key: { type: api_key, key: "X-API-Key", value: "$KEY", placement: "header" }. Placement is "header" or "query".
• ntlm: { type: ntlm, username: "$NTLM_USERNAME", password: "$NTLM_PASSWORD", domain: "$NTLM_DOMAIN", workstation: "$NTLM_WORKSTATION" }. Domain and workstation are optional. Noodle supports connection-bound server NTLMv2 authentication only; keep the password in a secret environment variable.
• aws_sigv4: { type: aws_sigv4, access_key: "$AWS_ACCESS_KEY_ID", secret_key: "$AWS_SECRET_ACCESS_KEY", region: "us-east-1", service: "execute-api", session_token: "$AWS_SESSION_TOKEN" }. session_token is optional. Signing uses headers and supports text, JSON, URL-encoded, and binary bodies; multipart is not supported.
• oauth1: Start with { type: oauth1, consumer_key: "$OAUTH1_CONSUMER_KEY", consumer_secret: "$OAUTH1_CONSUMER_SECRET", access_token: "$OAUTH1_ACCESS_TOKEN", access_token_secret: "$OAUTH1_ACCESS_TOKEN_SECRET", signature_method: "HMAC-SHA1", placement: "header" }. Supported methods are HMAC-SHA1/256/512, RSA-SHA1/256/512, and PLAINTEXT. Placement is header, query, or body; body placement requires URL-encoded form data. RSA keys may be inline text or a collection-relative or @/ file path.
• oauth2: Start with { type: oauth2, grant_type: authorization_code, discovery_url: "https://identity.example", client_id: "$OAUTH2_CLIENT_ID", client_secret: "$OAUTH2_CLIENT_SECRET", scope: "openid profile", redirect_uri: "http://127.0.0.1:8765/oauth/callback" }. discovery_url accepts an OIDC issuer; set discovery_url_kind: document for an exact discovery-document URL. Explicit authorization_url and access_token_url values remain authoritative. Supported grants are authorization_code, client_credentials, implicit, and password; authorization code defaults to S256 PKCE. Read [schema.md](schema.md) before authoring advanced token, client assertion, or additional-parameter fields.

Keep OAuth consumer secrets, token secrets, client secrets, passwords, and private signing keys in secret environment variables. OAuth 2 token responses live in the OS credential vault, with a session-only memory fallback if the vault is unavailable; never write tokens, authorization codes, PKCE verifiers, or generated state into collection files. Browser authorization is a TUI-only human workflow. Non-interactive request run and collection run may reuse or refresh stored browser credentials, and may acquire client-credentials or password tokens directly, but never open a browser.

Noodle cannot generate client-code snippets for NTLM, AWS SigV4, OAuth 1.0a, or OAuth 2.0 requests. Keep these requests in the collection and run them with noodle instead.