CLI automation and CI

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.

For interactive runs, start with the Collection Runner. For CI setup, jump to Run in GitHub Actions CI.

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.
• Prepare requests with a synchronous or async sandboxed script when declarative fields are not enough.
• 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:

In users/folder.yml:

tags:
  - smoke

In users/delete.yml, alongside the request fields:

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.

Use --delay <milliseconds> when an API needs breathing room between requests:

noodle collection run ./api --delay 500 --env staging

The delay must be a non-negative safe integer. Noodle waits after a completed request only when another selected request remains. Failed requests are followed by the delay when execution continues; fail-fast skips it.

Run the same workflow in the TUI

Press F5 to open or resume the Collection Runner. Inspect completed responses, Results, and Console while later requests run. Press s or click Stop to cancel; Escape leaves the workspace and F5 returns to it.

Prepare requests before HTTP with a script

Use Scripting for pre-request preparation and post-response processing. Inline scripts and collection-relative JavaScript files run in the TUI and CLI. Sources for every selected request are checked before HTTP; invalid or missing sources are configuration failures (exit 2). Collection runs keep script writes transient.

Inspect a response in the terminal

Single-request runs show a summary by default. Add only the response details you need:

noodle request run users/get --collection ./api --body --headers --cookies

The sections use the existing redacted response result: known secrets and sensitive headers are masked, received-cookie values are always hidden, and terminal control characters are escaped. Unknown server payload fields remain visible. Binary bodies show a reminder to use --output. These flags do not change success criteria or the single --json envelope; JSON response results also include received-cookie metadata with masked values when present.

Download a response

noodle request run files/download --collection ./api --output ./downloads/file.bin --json

request run --output/-o <file> saves original received bytes after normal HTTP decompression, independently of redacted diagnostics. The destination must be new: invalid or existing paths exit 2 before sending. Completed responses are saved even after HTTP, post-script, capture, assertion, or test failures, which still exit 1. Pre-script and transport failures create no file. Later write failures retain response diagnostics and exit 1; successful saves report outputFile. Downloads contain unredacted server data.

Binary JSON results omit body text and bytes and report bodyKind, byte size, normalized contentType, and optional filename. Collection runs and Runner details retain binary metadata only. Status/header/time expressions still work; JSON body captures and assertions fail clearly for binary responses.

Pass response values forward

Use Capture and reuse values to pass IDs or tokens between requests in one ordered run. Separate manual sends require explicit persistence to share values.

Put success criteria beside the request

Add Response assertions to check status, headers, JSON fields, and timing. Failed assertions make a run command fail.

Add programmable response checks

Use Scripted tests for conditional checks with test() and expect(). Tests run after declarative assertions when a response exists; fail-fast waits for these diagnostics.

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. Both request run and collection run exit 1 when an executed request fails and 2 when environment, proxy, TLS, cookie, target, tag, or other applicable 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. CLI collection interruption exits 130 with partial results.

For request run, the request result is in data.result. For collection run, the ordered results are in data.results, fail-fast or cancellation skips are in data.skipped, and data.summary counts selected, executed, skipped, successful, and failed requests plus assertion, capture, duration, and failure-category totals. When test groups are present, it also includes testPasses, testFailures, and testScriptErrors. There are no aggregate pre/post script counters. Each request result also lists any execution, script, transport, http, capture, assertion, or test failure categories; pre-run failures use configuration. Script, capture, assertion, and test groups include whether evaluation happened and each individual result. Script rows include phase, scope, source kind, status, duration, redacted logs, an optional normalized error, and optional persistence outcomes. Test groups retain ordered named results, redacted logs, and an optional top-level script error; they are separate from pre/post results. Human output distinguishes Pre-script/Post-script labels. JSON run output redacts known environment, proxy, TLS, request-credential, cookie, script-created, and secret RunScope values from response data and results. Sensitive response headers are masked, and captures from those headers are fully redacted. Arbitrary server payload fields remain visible, so treat JSON output as sensitive server data.

Without --json, Noodle prints a concise result for each request and a collection summary. Human output reports capture, assertion, and test pass and fail counts without printing raw captured or actual response values. It reports script status, duration, log count, and redacted failures without printing console messages. It also names failure categories such as configuration error, script failure, transport error, HTTP error, capture failure, assertion failure, and test failure.

Interrupt a collection run

Press Ctrl+C (SIGINT) or send SIGTERM to stop noodle collection run. Noodle cancels the active HTTP or OAuth operation, script, child request, or inter-request delay, closes the run’s cookie jars, and returns partial human or JSON output with exit status 130. A second interruption forces exit 130.

Completed rows stay in data.results. An interrupted execution carries cancelled: true; unstarted selections appear in data.skipped with reason: "cancelled". The run itself has data.cancelled: true. data.summary includes completed, cancelled, and unstarted, with:

selected = completed + cancelled + unstarted
executed = completed + cancelled

Cancelled executions do not count as request failures. Finished response phases and redacted diagnostics remain available; unfinished script writes roll back and later phases remain unevaluated. Cancellation cannot undo HTTP effects already sent. Request and script timeouts remain ordinary failures. With iteration data, results and skips keep their zero-based iteration.

This signal workflow applies to CLI collection runs. Use the Collection Runner guide for F5 controls.

Maintain collections without the TUI

Use the CLI command reference to create, initialize, inspect, format, and audit collections. It also covers workspace registrations, request creation, environment variables, secrets, and cookie management. collection format and audit --fix modify files; review their diffs before committing.

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. For unattended workflows that have a working vault, use --stdin so the value 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.

Run in GitHub Actions CI

This example runs a saved health check on pushes to main or a manual workflow dispatch. It uses a reachable staging API with bearer authentication. Replace the example URL and /health path with your API’s endpoint, which should return HTTP 200 when healthy. Only run trusted collection files with credentials.

Commit these three collection files. In my-api/settings.yml:

environment: ci
cookies:
  enabled: false

In my-api/.environments/ci.env:

BASE_URL=https://api.example.com
# @secret API_TOKEN
API_TOKEN=

In my-api/health.yml:

name: Health check
method: GET
url: $BASE_URL/health
auth:
  type: bearer
  token: $API_TOKEN
assert:
  - expression: status
    operator: equals
    value: 200

Add a repository Actions secret named NOODLE_API_TOKEN containing the staging token. Create .github/workflows/api-checks.yml in the repository containing my-api:

name: API checks
on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read

jobs:
  api-checks:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Install Noodle
        env:
          NOODLE_VERSION: v0.10.2
        run: |
          curl -fsSL "https://raw.githubusercontent.com/wilfredinni/noodle/$NOODLE_VERSION/scripts/install.sh" -o "$RUNNER_TEMP/noodle-install.sh"
          bash "$RUNNER_TEMP/noodle-install.sh"
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Validate collection
        run: noodle collection audit ./my-api

      - name: Run API checks
        env:
          API_TOKEN: ${{ secrets.NOODLE_API_TOKEN }}
        run: |
          test -n "$API_TOKEN" || { echo "NOODLE_API_TOKEN is not configured" >&2; exit 2; }
          noodle collection run ./my-api --env ci --fail-fast

The installer pins Noodle to v0.10.2 and verifies its binary checksum. Change that version deliberately when upgrading the workflow. The Actions secret supplies the declared API_TOKEN through the process environment, so this example needs no interactive keyring. Cookies are disabled because this bearer health check does not need a session jar.

The job fails on an audit error or a nonzero run exit status. Human output gives request results, failed checks, and a summary in the Actions log. To process structured results instead, use --json and inspect data.results; do not swallow the command’s exit status. Known secrets are redacted, but arbitrary server data can remain in JSON, so review reports before sharing them.

This example intentionally runs the committed collection only on trusted pushes or manual dispatch. If you extend it to pull requests, account for which events can access your staging credentials. See GitHub’s workflow syntax and checkout action for platform setup.

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.