Automation

A Noodle collection does not need a second representation before it can run in automation. The same request files you inspect in the TUI can be audited, selected, and sent from the command line.

That keeps the feedback loop close to the collection. A small change can run one request or one folder, while a broader check can run every request in collection order.

Automation building blocks

• Run collections with request targets, folders, tags, fail-fast execution, or the TUI Runner.
• Capture values from one response and reuse them in later requests.
• Assert behavior against status, response time, headers, and JSON body values.
• Consume results through exit status, human-readable output, or a stable JSON envelope.

Choose the requests that matter

Run one saved request by its collection-relative ID. The ID omits the .yml extension:

noodle request run users/get --collection ./api --env staging

Use collection run when a check spans more than one request. Targets can mix request IDs with folder paths that end in /:

noodle collection run ./api smoke/ health users/get --env staging

A folder target includes its nested requests. Noodle validates every target before sending anything, removes overlaps, and runs the final selection once in collection order. Omit targets to run the whole collection:

noodle collection run ./api --env staging

Request IDs cannot be absolute paths or contain traversal, backslashes, hidden segments, or empty path segments.

Build dynamic suites with tags

Requests and non-root folders can declare case-sensitive tags. Folder tags apply to every descendant request, so a workflow can define a suite once:

# users/folder.yml
tags:
  - smoke

# users/delete.yml
tags:
  - destructive

Run every request with the effective smoke tag while keeping destructive requests out:

noodle collection run ./api --tag smoke --exclude-tag destructive --env staging

Repeat --tag to require every listed tag. Repeat --exclude-tag to remove a request when any listed tag matches. Duplicate filters have no additional effect.

Tag values must be non-empty and already trimmed. A root-level folder.yml is ignored, and descendants cannot remove inherited tags. Noodle resolves and validates positional targets first, then applies inclusion and exclusion before loading environment, proxy, TLS, cookies, or sending requests. Exclusion wins when both filters match. A filtered selection with no requests is a configuration failure.

Add --fail-fast when later requests would add no useful signal after the first failure. Completed requests stay in data.results; every remaining selected request appears in order under data.skipped with reason fail-fast. Requests removed by tag filters appear in neither list and cannot change run-scoped captures.

Run the same workflow in the TUI

Open the command palette and choose Run Collection to configure a transient run without leaving the TUI. Select requests or whole folders, choose an environment, add Include and Exclude tags, and enable fail-fast before starting. The Runner shows progress, keeps ordered results in memory, and expands request details with response, assertion, and capture outcomes. A folder context menu opens the same workspace scoped to that folder.

Runner options are local to that workspace. It does not create another runner file, edit request declarations, persist captures, or write timeline entries.

Pass response values forward

A request can capture a value from its response for later requests in the same ordered collection run:

# users/create.yml
name: Create User
method: POST
url: $base_url/users
capture:
  created_user_id:
    value: body.id
  access_token:
    value: body.access_token
    persist: secret
  optional_trace:
    value: headers.x-trace
    enabled: false

# users/get.yml
name: Get Created User
method: GET
url: $base_url/users/$created_user_id

Every capture entry is an object with required value, optional enabled: false, and optional persist: secret or persist: environment. Scalar shorthand is invalid. Disabled captures remain in the request but do not resolve, change RunScope, produce results, or write values.

Capture expressions inspect status, response time, case-insensitive headers, or JSON body paths. Noodle loads environment and secret values first, then overlays successful captures. The latest successful value with a given name wins. Strings substitute verbatim; other JSON-compatible values use their JSON representation.

Captures follow collection order, including when a run selects only a few requests or folders. Successful values commit before assertions. A failed capture fails that request and the final command, but the collection keeps running and an earlier successful value is not replaced.

One collection run shares a transient scope across its ordered requests. The TUI Runner uses the same transient rule. A manual TUI send or CLI request run uses an isolated scope and can persist a successful capture to the active or selected environment when persist is set. Secret values are stored in the OS vault and fully redacted from capture results. See the response capture reference for the exact expression, persistence, and failure behavior.

Put success criteria beside the request

An HTTP response only says what happened. Assertions let the request declare what a useful response looks like:

name: Get User
method: GET
url: $base_url/users/:userId
assert:
  - expression: status
    operator: equals
    value: 200
  - expression: body.id
    operator: isNumber
  - expression: headers.Content-Type
    operator: contains
    value: application/json
  - expression: response.time
    operator: lt
    value: 500

Manual TUI sends, request run, and collection run evaluate enabled checks after the response arrives. The TUI shows the outcome in Results. Failed assertions make automation commands fail. An HTTP status of 400 or higher also fails a run command, even when a status assertion passes.

Assertion expressions can inspect status, response time, case-insensitive headers, and JSON body paths. Expected string values support environment substitution at any depth. Values resolved from declared secrets are redacted from assertion results, while actual values remain raw response data. See the response assertion reference for every expression and operator.

Let the exit status make the first decision

Every automation command accepts --json and writes exactly one result envelope to stdout:

{
  "status": "success",
  "data": {},
  "errors": []
}

Successful commands exit with status 0. A collection run exits 1 when an executed request fails and 2 when target, tag, environment, proxy, TLS, cookie, or other pre-run configuration fails. This makes the exit status enough for a simple gate, while JSON provides the detail needed for reports or follow-up steps.

For request run, the request result is in data.result. For collection run, the ordered results are in data.results, fail-fast skips are in data.skipped, and data.summary counts selected, executed, skipped, successful, and failed requests plus assertion, capture, duration, and failure-category totals. Each request result also lists any execution, transport, http, capture, or assertion failure categories; pre-run failures use configuration. Capture and assertion results include whether evaluation happened and each individual result. JSON run output also contains response headers, bodies, and successful capture values unless they match a known environment or settings secret, so treat it as sensitive server data.

Without --json, Noodle prints a concise result for each request and a collection summary. Human output reports capture and assertion pass and fail counts without printing raw captured or actual response values.

Maintain collections without the TUI

Automation covers the collection lifecycle, not only request execution. These commands can build, inspect, and repair the files before a run:

Task	Command
List registered collections	noodle workspace list
Find or remove stale registered paths	noodle workspace audit [--fix]
Create a starter collection	noodle collection create <name> [-o <dir>]
Initialize an existing directory	noodle collection init <path>
Print the request tree	noodle collection list <path>
Inspect metadata, environments, and requests	noodle collection inspect <path>
Canonicalize request YAML and valid JSON bodies	noodle collection format <path>
Validate or repair valid collection files	noodle collection audit <path> [--fix]
Create a minimal request	noodle request create <id> --url <url> [--method <method>] [--collection <dir>]
Set an environment value	noodle environment set <key> <value> --env <name> [--collection <dir>]
Store, inspect, or delete a secret	noodle secret <set|list|delete> ... --env <name> [--collection <dir>]
Inspect or clear collection cookies	noodle cookie <list|clear> [--collection <dir>]

collection format and the --fix audit variants modify files. Review their diffs before committing the collection.

Keep credentials and local state out of logs

Run commands use --env when supplied. Otherwise, they use the environment named in the collection’s settings.yml.

secret set prompts without echo in an interactive terminal. In unattended workflows, pass the value through standard input so it never appears in command arguments:

noodle secret set API_TOKEN \
  --env staging \
  --collection ./api \
  --stdin

On headless Linux, OS-vault storage requires a user D-Bus session and an unlocked GNOME Keyring or KWallet collection. A same-named process environment variable can supply the value when an external secret manager owns the credential. The headless environment reference covers setup and troubleshooting.

cookie list includes live cookie values and should not be copied into shared logs. Request and collection runs can continue without jar cookies when storage is unavailable, and report a warning instead.

Use --noproxy only when one run must bypass saved and system proxy policy. Use --insecure only when that run intentionally disables TLS certificate verification.

A reviewable workflow

The smallest useful automated workflow creates files, validates them, and runs only the affected request:

noodle collection create demo
noodle request create users/list \
  --url https://api.example.com/users \
  --collection ./demo
noodle environment set base_url https://api.example.com \
  --env development \
  --collection ./demo
noodle collection audit ./demo
noodle collection run ./demo users/list --env development --json

The result remains a normal Noodle collection. Open it in the TUI for interactive work, commit the request files for review, and use the same commands again when the collection changes.