sonde

module
v1.0.0-rc.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 27, 2026 License: Apache-2.0

README

Sonde

Sonde (pronounced "sond") is a fast, single-binary CLI that runs and tests HTTP requests written in plain text. It reads Hurl files (.hurl, and .sonde for the same syntax) and adds OpenAPI contract checks, data-driven runs, sonde.yaml environments, importers from curl, Postman, Bruno and .http files, and editor support (sonde lsp).

GET https://httpbin.org/status/200
HTTP 200
sonde --test health.hurl

Install

Homebrew (macOS/Linux):

brew install nhtera/tap/sonde

Scoop (Windows):

scoop bucket add nhtera https://github.com/nhtera/scoop-bucket
scoop install sonde

Go:

go install github.com/nhtera/sonde/cmd/sonde@latest

Release archives: signed, checksummed binaries for macOS, Linux and Windows are on the releases page. Every release ships a checksums.txt, a checksums.txt.sigstore.json cosign bundle and an SBOM; see docs/release.md to verify one.

30-second tour

Write a request file:

GET https://httpbin.org/uuid
HTTP 200
[Captures]
id: jsonpath "$.uuid"
[Asserts]
jsonpath "$.uuid" matches /^[0-9a-f-]{36}$/

GET https://httpbin.org/anything/{{id}}
HTTP 200
[Asserts]
jsonpath "$.url" contains "{{id}}"

Run it, in test mode, with an HTML report:

sonde --test --report-html reports uuid.hurl

Point the same file at a different target without editing it, with a sonde.yaml next to it:

version: 1
environments:
  staging:
    variables:
      base_url: https://staging.example.internal
defaults:
  env: staging

Or start from what you already have:

sonde import postman collection.json -o requests/
sonde import curl commands.sh -o requests/
sonde import openapi petstore.yaml -o requests/

Full walkthrough: docs/getting-started.md.

Features

Documentation

Start at docs/README.md, or jump to getting started, the CLI reference, or what v1 promises to keep working.

License

Apache License 2.0. See NOTICE and TRADEMARKS.md for use of the name.

Directories

Path Synopsis
cmd
sonde command
Command sonde runs and tests HTTP requests written in plain text.
Command sonde runs and tests HTTP requests written in plain text.
Package engine runs request files: it renders each entry, sends the request, and evaluates captures and asserts on the response.
Package engine runs request files: it renders each entry, sends the request, and evaluates captures and asserts on the response.
Package exchange is the transport-neutral model of an HTTP exchange: the request that was sent and the response that was received, with the helpers evaluation needs (decoded body, text, cookies).
Package exchange is the transport-neutral model of an HTTP exchange: the request that was sent and the response that was received, with the helpers evaluation needs (decoded body, text, cookies).
internal
charset
Package charset looks up text encodings by their WHATWG labels and decodes bytes strictly.
Package charset looks up text encodings by their WHATWG labels and decodes bytes strictly.
cli
Package cli implements the sonde command line: cobra commands, flag mapping and output wiring.
Package cli implements the sonde command line: cobra commands, flag mapping and output wiring.
config
Package config builds the run configuration a command line assembles before an entry ever runs: typed variables and secrets from the command line, properties files and environment variables, plus the small set of options read from a config file.
Package config builds the run configuration a command line assembles before an entry ever runs: typed variables and secrets from the command line, properties files and environment variables, plus the small set of options read from a config file.
convert
Package convert is the shared writer importers (curl, Postman, OpenCollection, .http, OpenAPI) use to turn generated request files into files on disk: path sanitizing, collision handling, a sandboxed atomic write and a sonde.yaml skeleton that is never overwritten.
Package convert is the shared writer importers (curl, Postman, OpenCollection, .http, OpenAPI) use to turn generated request files into files on disk: path sanitizing, collision handling, a sandboxed atomic write and a sonde.yaml skeleton that is never overwritten.
convert/curl
Package curl imports curl command lines into Sonde request files, and (see engine/curl_export.go, internal/cli/export.go) supports exporting entries back to curl.
Package curl imports curl command lines into Sonde request files, and (see engine/curl_export.go, internal/cli/export.go) supports exporting entries back to curl.
convert/httpfile
Package httpfile imports ".http" files, the plain-text request format shared (with minor dialect differences) by the JetBrains HTTP Client and the VS Code REST Client extension, into Sonde request files.
Package httpfile imports ".http" files, the plain-text request format shared (with minor dialect differences) by the JetBrains HTTP Client and the VS Code REST Client extension, into Sonde request files.
convert/opencollection
Package opencollection imports a Bruno OpenCollection YAML collection — a single file or a directory — into Sonde request files, through the shared internal/convert writer.
Package opencollection imports a Bruno OpenCollection YAML collection — a single file or a directory — into Sonde request files, through the shared internal/convert writer.
convert/postman
Package postman imports a Postman Collection v2.1 (or v2.0, which the same schema also parses) into Sonde request files: folders become directories, collection and environment variables become a sonde.yaml skeleton, and pre-request/test scripts are kept as comments, never executed.
Package postman imports a Postman Collection v2.1 (or v2.0, which the same schema also parses) into Sonde request files: folders become directories, collection and environment variables become a sonde.yaml skeleton, and pre-request/test scripts are kept as comments, never executed.
dataset
Package dataset streams the rows of a data file (`--data`): a CSV file with a header row, or a JSON array of objects.
Package dataset streams the rows of a data file (`--data`): a CSV file with a header row, or a JSON array of objects.
datefmt
Package datefmt reproduces the date/time formatting and parsing semantics of the Rust chrono crate (v0.4.44, built with default-features = false, features = ["clock"], i.e.
Package datefmt reproduces the date/time formatting and parsing semantics of the Rust chrono crate (v0.4.44, built with default-features = false, features = ["clock"], i.e.
docs
Package docs holds Sonde's single compatibility doc-data source (table.yaml) and its typed accessors.
Package docs holds Sonde's single compatibility doc-data source (table.yaml) and its typed accessors.
enginex
Package enginex builds engine result values from internal types, for internal tests that need results without running a file.
Package enginex builds engine result values from internal types, for internal tests that need results without running a file.
filter
Package filter applies filters (`count`, `jsonpath`, `toInt`, …) to the value of a query.
Package filter applies filters (`count`, `jsonpath`, `toInt`, …) to the value of a query.
httpx
Package httpx executes requests: it builds the HTTP request from a RequestSpec, applies the transport options, follows redirects manually and keeps the cookie store of a run unit.
Package httpx executes requests: it builds the HTTP request from a RequestSpec, applies the transport options, follows redirects manually and keeps the cookie store of a run unit.
jsonpath
Package jsonpath implements JSONPath (RFC 9535): parsing a query with Parse and evaluating it against a decoded JSON document with Eval.
Package jsonpath implements JSONPath (RFC 9535): parsing a query with Parse and evaluating it against a decoded JSON document with Eval.
lsp
Package lsp implements `sonde lsp`, a Language Server Protocol server over stdio for .hurl and .sonde files: diagnostics, completion, hover and formatting.
Package lsp implements `sonde lsp`, a Language Server Protocol server over stdio for .hurl and .sonde files: diagnostics, completion, hover and formatting.
openapi
Package openapi validates responses against an OpenAPI 3.x description (the engine.ResponseValidator of --openapi) and generates request files from one (sonde import openapi).
Package openapi validates responses against an OpenAPI 3.x description (the engine.ResponseValidator of --openapi) and generates request files from one (sonde import openapi).
predicate
Package predicate evaluates assert predicates (`==`, `contains`, `isInteger`, …, optionally negated with `not`).
Package predicate evaluates assert predicates (`==`, `contains`, `isInteger`, …, optionally negated with `not`).
query
Package query evaluates queries (`status`, `header`, `jsonpath`, …) on the responses of an entry.
Package query evaluates queries (`status`, `header`, `jsonpath`, …) on the responses of an entry.
redact
Package redact holds a per-run, append-only registry of secret values and masks them, and their predictable encoded variants, out of text before it is printed, logged, or written to a report.
Package redact holds a per-run, append-only registry of secret values and masks them, and their predictable encoded variants, out of text before it is printed, logged, or written to a report.
regex
Package regex holds the regular expression rules shared by the parser and evaluation: patterns must be valid for the Go engine and must not rely on its leniencies (a `{` that is not a counted repetition).
Package regex holds the regular expression rules shared by the parser and evaluation: patterns must be valid for the Go engine and must not rely on its leniencies (a `{` that is not a counted repetition).
runerr
Package runerr defines the runtime error raised while evaluating a request file: templates, queries, filters, predicates and captures.
Package runerr defines the runtime error raised while evaluating a request file: templates, queries, filters, predicates and captures.
sandbox
Package sandbox confines the files a request file may read or write to a file root.
Package sandbox confines the files a request file may read or write to a file root.
styled
Package styled builds text made of styled runs, printed either plain or with ANSI escape codes.
Package styled builds text made of styled runs, printed either plain or with ANSI escape codes.
syntax
Package syntax parses .hurl/.sonde files into a lossless AST, prints it back byte for byte, formats it canonically and renders diagnostics.
Package syntax parses .hurl/.sonde files into a lossless AST, prints it back byte for byte, formats it canonically and renders diagnostics.
template
Package template evaluates `{{ }}` expressions and renders templates with typed variables.
Package template evaluates `{{ }}` expressions and renders templates with typed variables.
value
Package value is the typed value model of evaluation: what queries return, filters transform, predicates compare and templates render.
Package value is the typed value model of evaluation: what queries return, filters transform, predicates compare and templates render.
xpath
Package xpath evaluates XPath 1.0 expressions on HTML and XML documents.
Package xpath evaluates XPath 1.0 expressions on HTML and XML documents.
scripts
bench command
server is a minimal HTTP server used only by scripts/bench.sh: it binds an ephemeral port (never 8000-8003, reserved for the conformance harness), answers every request with a small fixed JSON body, and prints "PORT=<n>" on its own line to stdout so the caller can read it back.
server is a minimal HTTP server used only by scripts/bench.sh: it binds an ephemeral port (never 8000-8003, reserved for the conformance harness), answers every request with a small fixed JSON body, and prints "PORT=<n>" on its own line to stdout so the caller can read it back.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL