Skip to content
NoodleNoodle
DocsRoadmapReleases

CLI Commands

TUI (default)

Section titled “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

A positional <path> overrides --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

Section titled “Path modes”

Existing collection roots open in full collection mode. Directories that contain request .yml files but no collection markers (.environments/, settings.yml) open in read-only browse mode. Empty directories open in read-only empty mode. Use the command palette (Ctrl+P) to initialize browse or empty directories before editing or sending.

Flag Short Default Description
--collection -c ./collections Path to request directory
--env -e None 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

--help and --version are available on every command.

Import

Section titled “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

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

Section titled “Import in the TUI”

From an open collection, press Ctrl+P and choose Import Collection. Pick whether the source should become a new collection or be added to the current one. Save pending changes before choosing the current collection.

Export

Section titled “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 openapi or postman
--output -o Output file for OpenAPI, or new/empty directory for Postman

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

Section titled “Export in the TUI”

Press Ctrl+P and choose Export Collection to select OpenAPI or Postman and preview the output target. When the usual Postman target directory is occupied, the TUI chooses the next numbered directory.

Update

Section titled “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.

Agent skill

Section titled “Agent skill”

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

noodle agent install
noodle agent install --json

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. JSON mode returns the action, managed path, and linked paths in one result envelope.

Automation commands

Section titled “Automation commands”

Use automation commands in scripts and agent workflows. They do not open the TUI. Collection paths are filesystem paths, and request IDs are collection-relative paths without the .yml extension (for example, users/list).

Command Purpose
noodle workspace list List collections registered in the global config.
noodle workspace audit [--fix] Validate registered collections; --fix removes stale paths.
noodle collection create <name> [-o <dir>] Create and register a starter collection.
noodle collection init <path> Bootstrap collection markers in an existing directory.
noodle collection list <path> Print a collection tree.
noodle collection inspect <path> Show collection metadata, environments, and its tree.
noodle collection format <path> Canonicalize request YAML and pretty-print valid JSON bodies.
noodle collection audit <path> [--fix] Validate collection files; --fix canonicalizes valid files.
noodle collection run <path> [-e <env>] [--noproxy] [--insecure] Run every request and fail if any request fails.
noodle request create <id> --url <url> [--method <method>] [--collection <dir>] Create a minimal request.
noodle request run <id> [--collection <dir>] [-e <env>] [--noproxy] [--insecure] Run one saved request.
noodle environment set <key> <value> --env <name> [--collection <dir>] Set and enable an environment variable.
noodle secret set <key> --env <name> [--collection <dir>] [--stdin] Declare and securely store an environment value.
noodle secret list --env <name> [--collection <dir>] List declared secret names and active sources.
noodle secret delete <key> --env <name> [--collection <dir>] Remove the local vault value but keep its declaration.
noodle cookie list [--collection <dir>] List collection cookies and storage health.
noodle cookie clear [--collection <dir>] Clear the collection jar or recover unreadable storage.

request run and collection run use --env when supplied. Otherwise, they use the environment named by the collection’s settings.yml. Add --noproxy to either run command to bypass saved and system proxy policy for that invocation. Add --insecure only when you intentionally want to disable TLS certificate verification for that run.

secret set prompts without echo in an interactive terminal. Use --stdin for automation so the value is not exposed in command arguments. secret list reports each declaration as process, keychain, missing, or disabled; process environment values take precedence over locally stored values.

On headless Linux, secret set also requires a user D-Bus session and an unlocked GNOME Keyring or KWallet collection. See Linux and headless environments for setup and troubleshooting.

cookie list includes every cookie value, host-only scope, storage state, and non-fatal storage warnings. Treat its output as sensitive. cookie clear backs up unreadable storage before creating a clean jar and reports the backup path. Request and collection runs can still succeed when the jar is unavailable; those runs report a warning and continue without jar cookies.

JSON output and exit status

Section titled “JSON output and exit status”

Every automation command accepts --json. It writes exactly one JSON object to stdout:

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

Successful commands exit with status 0. Invalid input and failed request or collection runs exit nonzero. Without --json, commands print concise, human-readable results; interactive terminals also show progress and status colors (honoring NO_COLOR).

Example workflow

Section titled “Example workflow”
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 --env development --json

For safety, request IDs cannot be absolute paths or contain traversal, backslashes, hidden segments, or empty path segments.