CLI commands

Look up command syntax, flags, and defaults here. For an interactive walkthrough, use Your first request. For scripts and CI, use CLI automation and CI.

<value> denotes a required argument; [value] denotes an optional one. Use noodle --version for the installed version and --help on a command for its usage, for example noodle collection run --help.

TUI (default)

Launches the terminal interface.

noodle                                  # first registered collection, or current directory
noodle .                                # open current directory
noodle --collection ./api --env prod    # explicit collection + env
noodle -c ./my-requests -e staging      # shorthand
noodle --collection ./api --noproxy     # force direct connections
noodle --collection ./api --insecure    # disable TLS verification once

Choose a positional <path> or --collection; supplying both is invalid. Without either, Noodle uses the first existing collection registered in ~/.config/noodle/config.yml, falling back to the current directory.

Path modes

A directory with .environments/, settings.yml, or a request .yml file at its root opens in full collection mode. If requests exist only in subdirectories and there are no collection markers, it opens in read-only browse mode. Without any recognized requests or markers, it opens in read-only empty mode. Use Initialize Collection in the command palette (Ctrl+P) before editing or sending in browse or empty mode.

Flag	Short	Default	Description
--collection	-c	Registered collection, then current directory	Path to request directory
--env	-e	Saved collection default, then first available environment	Environment to activate. Exits with error if not found
--noproxy		false	Force direct connections for this invocation
--insecure		false	Disable TLS certificate verification for this invocation

This fallback applies to opening the TUI. The automation commands documented below that accept --collection default to ./collections; they do not reuse the TUI’s registered-collection fallback.

Import

Converts an OpenAPI 3.0 or Swagger 2.0 specification, Postman collection, or Insomnia v4/v5 JSON export into noodle .yml files. Format is auto-detected from file contents.

noodle import ./api-spec.json                           # auto-detect
noodle import ./postman_collection.json -i postman      # force format
noodle import ./insomnia-export.json -i insomnia        # force format
noodle import ./spec.json -o ./my-apis                  # custom output dir

Argument	Description
source	OpenAPI/Swagger JSON or YAML spec, or Postman/Insomnia JSON export

Flag	Short	Default	Description
--format	-i	auto-detect	openapi, swagger, postman, or insomnia
--output	-o	./collections	Output directory
--json		false	Write a JSON result envelope

After writing the collection, import canonicalizes each request’s YAML and pretty-prints valid JSON bodies. Its JSON result includes the number of formatted bodies in data.formattedJsonBodies.

Import in the TUI

See Import for the interactive workflow and format limitations.

Export

Exports a Noodle collection as an OpenAPI 3.0.3 document or Postman Collection v2.1 bundle.

noodle export ./collections --format openapi --output ./specs/openapi.yml
noodle export ./collections --format postman --output ./exports/postman --json

Argument	Description
collection	Noodle collection directory

Flag	Short	Description
--format		Required. openapi or postman
--output	-o	Required. Output file for OpenAPI, or new/empty directory for Postman
--json		Write a JSON result envelope

The output path must be outside the collection. OpenAPI includes enabled parameters and headers, supported auth, request-body examples, folders as tags, and enabled nonempty environment base_url values as servers. Postman creates collection.postman_collection.json plus a redacted environment file for every Noodle environment. Literal request values are preserved in both formats, so review exports for secrets before sharing them.

Export in the TUI

See Export for the interactive workflow and format limitations.

Download a response

Use request run --output/-o <file> to save the original response bytes. See request run for options and download behavior for validation, failures, and binary diagnostics. For the TUI workflow, see Inspect and save responses.

Update

Updates noodle to the latest version. Homebrew installs run brew upgrade noodle instead. Standalone binaries use Noodle’s update manifest and verify the downloaded SHA-256 checksum before replacement.

noodle update
noodle update --force       # bypass the one-hour release-check cache
noodle update --json        # emit one JSON result envelope

Non-Homebrew installs cache validated release metadata for one hour. If the manifest is temporarily unavailable, Noodle can use a valid cached release for up to seven days. When a managed noodle-use skill is already installed, a successful standalone, Homebrew, or TUI update refreshes it with the new Noodle version. Skill refresh failure does not roll back the Noodle update and reports noodle agent install as the retry.

On Windows x64 beta, updates stage the verified executable and apply it after Noodle exits. Close and reopen Noodle when prompted. JSON output reports restart_required, version, and log_path; an installed skill refresh remains pending until replacement succeeds. See Windows installation and updates.

Agent skill

Installs or updates Noodle’s embedded noodle-use skill without a network request:

noodle agent install
noodle agent install --json
noodle agent install --force

The command writes the managed copy to ~/.agents/skills/noodle-use and links detected Claude, Cursor, Codex, and OpenCode skill directories to it. It refuses to replace unmanaged directories at those paths and reports all conflicts before changing anything. Use --force only when every reported copy should be replaced; the installer keeps backups until all targets succeed and rolls back completed replacements if a later target fails. JSON mode returns the action, managed path, and linked paths in one result envelope.

Automation

Every workspace, collection, request, environment, secret, and cookie command below accepts optional --json (default false). It writes one { status, data, errors } envelope to stdout. Without it, output is human-readable. See results and exit statuses.

For commands that accept --collection, supply the path explicitly in scripts. Their default is ./collections, and -c is a TUI-only alias.

Workspace

Command	Arguments and options	Behavior
noodle workspace list	--json	List registered collections
noodle workspace audit	--fix, --json	Validate registrations; --fix removes invalid registered paths

--fix defaults to false and modifies the saved registration list, not the collection directories.

Collection management

Command	Arguments and options	Behavior
noodle collection create <name>	--output/-o <dir> (default .), --json	Create <dir>/<name> with settings, a development environment, and a starter request; register it
noodle collection init <path>	--json	Add collection markers to an existing directory and register it
noodle collection list <path>	--json	Print the collection tree
noodle collection inspect <path>	--json	Inspect metadata, environments, and requests
noodle collection format <path>	--json	Canonicalize request YAML and pretty-print valid JSON bodies
noodle collection audit <path>	--fix, --json	Validate files; optionally rewrite supported fixable content

create requires a new destination. init requires an existing directory that is not already a collection. format modifies request files; invalid JSON body text is preserved. Audit --fix defaults to false. Review changes from format and fix commands before committing.

Collection run

noodle collection run <path> [<target>...] [options]

path is required. Targets are request IDs without .yml or folder paths ending in /; omitting them selects the whole collection. Overlapping targets run once in collection order. Folder targets include descendants.

Option	Default	Behavior
--env/-e <name>	Collection settings.yml environment	Select the environment
--tag <tag>	No include filter	Repeatable; every include tag must match
--exclude-tag <tag>	No exclude filter	Repeatable; any matching tag excludes
--fail-fast	false	Skip remaining selected requests after a failure
--delay <milliseconds>	0	Wait between selected requests, including iteration boundaries; non-negative safe integer
--data <file.csv|file.json>	No data	Validate the file and run selected requests once per row
--noproxy	false	Force direct connections for this invocation
--insecure	false	Disable TLS certificate verification for this invocation
--json	false	Write a JSON result envelope

Tags are case-sensitive, inherited from non-root folders, and exclusion wins. An empty filtered selection is a configuration failure. Captures and script writes remain transient across one ordered run.

noodle collection run ./my-api users/ health --env staging --tag smoke --exclude-tag destructive --fail-fast --delay 500

Use Collection Runner for the TUI equivalent.

Request create

noodle request create <id> --url <url> [options]

The required ID is a collection-relative path without .yml, for example users/list. IDs reject absolute paths, traversal, backslashes, hidden segments, and empty segments. On Windows, names also reject forbidden filename characters, trailing dots/spaces, and reserved device names such as CON or NUL, including with extensions. Keep forward slashes in request IDs. The target collection must exist and be initialized.

Option	Default	Behavior
--url <url>	Required	Request URL
--method <method>	GET	GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS
--collection <dir>	./collections	Destination collection
--json	false	Write a JSON result envelope

Request run

noodle request run <id> [options]

The required ID addresses a saved request relative to its collection, without the .yml extension.

Option	Default	Behavior
--collection <dir>	./collections	Collection containing the request
--env/-e <name>	Collection settings.yml environment	Select the environment
--output/-o <file>	No file	Save original received bytes to a new destination
--body	false	Include the redacted response body in human output
--headers	false	Include redacted response headers in human output
--cookies	false	Include received-cookie metadata with masked values in human output
--noproxy	false	Force direct connections for this invocation
--insecure	false	Disable TLS certificate verification for this invocation
--json	false	Write a JSON result envelope

Each invocation has an isolated run scope and honors explicit capture/script persistence. Existing or invalid output destinations fail before HTTP. See download behavior for completed-response failures and output metadata.

Opt into response details without changing the run’s success criteria:

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

These flags only add human-readable sections. Known secrets and sensitive headers are redacted, received-cookie values are masked, and terminal controls are escaped. Unknown server payload data remains visible. Binary bodies show a reminder to use --output instead. --json still writes one envelope, including received-cookie metadata with masked values when present, regardless of these flags.

Environment set

noodle environment set <key> <value> --env <name> [--collection <dir>] [--json]

key, value, and --env are required. --collection defaults to ./collections. This saves an enabled public value; it cannot replace a declared secret. Use Environments and secrets for setup and secret set for credentials.

Secrets

Command	Required	Optional
noodle secret set <key>	--env <name>	--collection <dir>, --stdin, --json
noodle secret list	--env <name>	--collection <dir>, --json
noodle secret delete <key>	--env <name>	--collection <dir>, --json

--collection defaults to ./collections. set prompts without echo in a TTY; --stdin reads the value from standard input and removes one final line ending. It stores the value in the OS vault, with a blank declaration in the environment file. list returns names and status without values. delete removes the local vault value but retains its declaration; a process environment value can still resolve it. No secret value is accepted as a positional command argument.

Cookies

noodle cookie list [--collection <dir>] [--json]
noodle cookie clear [--collection <dir>] [--json]

--collection defaults to ./collections. list includes live cookie values, grouped by domain. clear empties the collection jar. Use the Cookies guide for the TUI and storage behavior.

See CSV/JSON iteration data for formats, path resolution, limits, variable/cookie isolation, and result metadata.