Skip to content

cli.md

Latest commit

 

History

History
290 lines (215 loc) · 10.6 KB

cli.md

File metadata and controls

290 lines (215 loc) · 10.6 KB

Resterm CLI

Resterm has two commandline entry points:

  • resterm opens the interactive TUI and also exposes import, update, history, and collection tooling.
  • resterm run executes the same .http / .rest files headlessly without opening the TUI.

Use this guide for commandline behavior. For request syntax, directives, workflows, auth, and UI behavior, see resterm.md. For RestermScript, see restermscript.md.

Command Overview

Command What it does
resterm [file] Open the TUI in the current workspace or a specific request file.
resterm run [flags] <file|-> Execute request files, workflows, compare runs, or profile runs without the TUI.
resterm init [dir] Bootstrap a new Resterm workspace.
resterm collection ... Export, import, pack, and unpack portable request bundles.
resterm history ... Export, import, inspect, compact, and verify persisted history.
resterm --from-curl ... Convert curl commands into .http files.
resterm --from-openapi ... Generate .http collections from OpenAPI documents.
resterm --check-update, resterm --update, resterm --version Inspect or update the installed binary.

Shared Execution Flags

These flags are shared by resterm and resterm run when request execution is involved.

Flag Description
--workspace <dir> Workspace root used for file discovery and relative resolution.
--recursive Recursively scan the workspace for request files.
--env <name> Select an environment explicitly.
--env-file <path> Use an explicit environment JSON file.
--timeout <duration> Default HTTP timeout.
--insecure Skip TLS certificate verification.
--follow Follow redirects. Pass --follow=false to disable it.
--proxy <url> HTTP proxy URL.
--compare <envs> Default comma/space-delimited compare targets.
--compare-base <env> Baseline environment for compare runs.
--trace-otel-endpoint <url> OTLP collector endpoint used by @trace.
--trace-otel-insecure Disable TLS for OTLP trace export.
--trace-otel-service <name> Override the exported service.name.

resterm run

resterm run is the headless execution path. It parses a request file, selects one or more targets, runs them with the same engine used by the TUI, and writes the result to stdout.

resterm run [flags] <file|->
  • Pass a file path to execute a request document from disk.
  • Pass - to read the request file from stdin.

Selecting What To Run

If you do not pass a selector:

  • a file with one request runs that request automatically
  • a file with multiple requests prompts for a choice when stdin/stdout are TTYs
  • a file with multiple requests prints a numbered list and exits with code 2 in non-interactive use

Selection flags:

Flag Description
--request <name> / -r <name> Run one named request.
--workflow <name> Run one named workflow.
--tag <tag> Run every request tagged with the given tag.
--line <n> Run the request or workflow whose source range contains line n.
--all Run every request in the file.
--profile Force profile mode for the selected request.

Selector rules:

  • --request cannot be combined with --tag or --line
  • --all cannot be combined with --request, --tag, or --line
  • --line cannot be combined with other selectors
  • --workflow cannot be combined with request selectors
  • --workflow cannot be combined with --compare or --profile

Output Formats

resterm run supports the following output modes:

Format Behavior
auto For exactly one request result, render a human request view similar to the TUI. Otherwise, fall back to the text report.
text Stable human-readable summary for requests, workflows, compare runs, and profiles.
json Machine-readable JSON report.
junit JUnit XML report for CI systems.
pretty Force the single-request Pretty view. Requires exactly one request result.
raw Force the single-request Raw view. Requires exactly one request result.

Related flags:

Flag Description
--format <mode> One of auto, text, json, junit, pretty, or raw.
--body Print only the response body for exactly one request result.
--headers Include request and response headers when a single-request view is rendered.
--color <mode> Pretty-output color mode: auto, always, never.

Output rules worth knowing:

  • --body only works with --format auto, --format pretty, or --format raw
  • --body still preserves exit status; a failing run can print only the body and still exit 1
  • --format pretty, --format raw, and --body all require exactly one request result
  • --color auto enables ANSI output only when stdout is a TTY and the terminal supports color
  • --color always forces pretty color even when output is piped

Artifacts And Persisted State

resterm run can write execution artifacts and optionally persist runtime state between invocations.

Flag Description
--artifact-dir <dir> Write artifacts produced by the run.
--state-dir <dir> Root directory for persisted runner state.
--persist-globals Persist captured globals between runs.
--persist-auth Persist cached auth state between runs.
--history Persist run history to the state directory.

Behavior:

  • stream transcripts are written under <artifact-dir>/streams/
  • trace summaries are written under <artifact-dir>/traces/
  • when persistence is enabled and --state-dir is omitted, Resterm uses <config-dir>/runner
  • --persist-globals writes runtime.json
  • --persist-auth writes auth.json
  • --history writes history.db
  • JSON output includes artifact paths such as transcriptPath and artifactPath when those files are written

Exit Codes

Exit code Meaning
0 All selected results passed.
1 Execution completed, but at least one result failed. This includes request failures, test failures, and trace budget breaches.
2 Usage or selection error. This includes invalid flag combinations, parse errors, unsupported formats, ambiguous selection, and missing request files.

Examples

Run a single request file headlessly:

resterm run ./requests.http

Run a named request and print the TUI-style pretty view:

resterm run --request login --format pretty ./requests.http

Run a workflow:

resterm run --workflow smoke ./requests.http

Run every request tagged smoke and write JSON:

resterm run --tag smoke --format json ./requests.http > run.json

Print only the raw response body from one request:

resterm run --request create-user --body ./requests.http

Read the request document from stdin:

cat ./requests.http | resterm run - --request health

Persist globals, auth, and history between invocations:

resterm run \
  --request login \
  --persist-globals \
  --persist-auth \
  --history \
  --state-dir ./.resterm-run \
  ./requests.http

Write stream and trace artifacts:

resterm run --request events --artifact-dir ./artifacts ./streams.http

Force profile mode for a request:

resterm run --request health --profile ./requests.http

resterm

Use resterm without subcommands when you want the TUI:

resterm
resterm --workspace ./api-tests
resterm --file ./requests.http

Top-level flags also expose a few CLI-only workflows:

Flag Description
--from-curl <command|path> Convert curl commands into a .http file.
--from-openapi <spec> Generate a .http collection from an OpenAPI document.
--http-out <file> Output path for generated .http files.
--openapi-base-var <name> Override the generated base URL variable name.
--openapi-resolve-refs Resolve external $ref values during OpenAPI import.
--openapi-include-deprecated Keep deprecated operations during OpenAPI generation.
--openapi-server-index <n> Pick the preferred server entry from the OpenAPI document.
--check-update Check for a newer release and exit.
--update Download and install the latest release when supported.
--version Print version, commit, build date, and checksum.

resterm init

resterm init bootstraps a workspace with starter files such as requests.http, resterm.env.json, and the optional standard template helpers.

resterm init
resterm init ./api-tests
resterm init --template minimal

See Initializing a Project for templates and flag details.

resterm collection

The collection commands package a workspace so it can be copied or shared safely.

Command What it does
resterm collection export --workspace <dir> --out <dir> Export a Git-friendly bundle directory.
resterm collection import --in <dir> --workspace <dir> Import a bundle into another workspace.
resterm collection pack --in <dir> --out <file.zip> Pack a bundle directory into a zip archive.
resterm collection unpack --in <file.zip> --out <dir> Unpack and validate a bundle archive.

See Collection Sharing for safety and manifest behavior.

resterm history

The history commands operate on persisted history storage.

Command What it does
resterm history export --out <path> Export persisted history as JSON.
resterm history import --in <path> Import history from JSON.
resterm history backup --out <path> Create a SQLite-consistent backup.
resterm history stats Print schema version, row counts, and sizes.
resterm history check [--full] Run integrity checks.
resterm history compact Checkpoint and compact history.db.

Import Examples

Convert curl into Resterm request files:

resterm --from-curl "curl https://example.com -H 'X-Test: 1'" --http-out example.http
resterm --from-curl ./requests.curl --http-out requests.http
cat requests.curl | resterm --from-curl - --http-out requests.http

Generate a collection from OpenAPI:

resterm \
  --from-openapi openapi.yml \
  --http-out openapi.http \
  --openapi-resolve-refs \
  --openapi-server-index 1

Related Docs

  • Main reference: resterm.md
  • RestermScript reference: restermscript.md
  • Examples: _examples/basic.http, _examples/workflows.http, _examples/compare.http, _examples/streaming.http