hitspec import

Import API specifications from various formats and convert them to hitspec .http files.

hitspec import <format> <source> [flags]

Supported Formats

Format	Description
`openapi`	OpenAPI 3.0/3.1 specs (YAML or JSON, local file or URL)
`postman`	Postman Collection v2.1 JSON files
`curl`	curl commands (inline or from a file)
`insomnia`	Insomnia export files (v4 format)

Nothing is dropped silently

Anything an importer cannot carry over is reported on stderr as warning: .... When the problem belongs to one request, it is also left in the generated file as a # TODO: comment above that request (for example an untranslated Postman test script or an unsupported curl flag). Every importer output passes hitspec validate. -o accepts a file or a directory (a trailing /, or an existing directory). For a directory, openapi writes one file per tag and the other formats write <source-name>.http.

hitspec import openapi

Import from an OpenAPI/Swagger specification.

hitspec import openapi <spec-file-or-url> [flags]

Flags

Flag	Short	Description	Default
`--output`	`-o`	Output file, or a directory for one file per tag	stdout
`--base-url`		Override the base URL from the spec
`--tags`		Filter operations by tags (comma-separated)	all
`--no-tests`		Skip generating test assertions	`false`

Path parameters

/users/{id} becomes {{id}}, and the file defines @id with the parameter’s example, then default, then first enum value, then a value for its type (1, example, a fixed UUID, …). If two operations use the same parameter name with different defaults, the second gets its own variable named <operationId>_<param>.

One file per tag

With -o tests/ (or any existing directory) each tag becomes tests/<tag>.http. Operations without tags are grouped by their first path segment. Each file carries the @baseUrl and the path variables its own requests use.

Examples

hitspec import openapi api-spec.yaml -o tests/api.http

hitspec import openapi api-spec.yaml -o tests/

hitspec import openapi https://petstore.swagger.io/v2/swagger.json -o petstore.http

hitspec import openapi spec.yaml --tags users,auth -o api.http

hitspec import openapi spec.yaml --base-url http://localhost:3000 -o api.http

hitspec import openapi spec.yaml --no-tests -o api.http

hitspec import postman

Import from a Postman Collection v2.1 file.

hitspec import postman <collection.json> [flags]

Flags

Flag	Short	Description	Default
`--output`	`-o`	Output file or directory path	stdout

Features

Converts Postman folders into request groups
Maps Postman dynamic variables to hitspec built-in functions ({{$guid}} becomes {{$uuid()}})
Collection variables become @name = value lines
A Postman environment export becomes an environments: entry in hitspec.yaml (written next to the output, or printed when writing to stdout)
Converts Bearer, Basic, API Key and Digest authentication to @auth, honoring the request, folder and collection levels (other types are reported)
Supports raw, URL-encoded, form-data (>>>multipart), GraphQL and file bodies
Translates pm.test scripts for the common patterns: pm.response.to.have.status(N), pm.expect(pm.response.code).to.eql(N), response time, header checks and pm.expect(jsonData.x).to.eql(y) (becomes expect body.x == y). Everything else is kept as # TODO: untranslated test: .... Requests without tests get no assertions.

Examples

hitspec import postman collection.json -o tests/api.http

hitspec import postman collection.json

hitspec import curl

Convert curl commands to hitspec format.

hitspec import curl <command-or-file> [flags]

Flags

Flag	Short	Description	Default
`--output`	`-o`	Output file or directory path	stdout
`--no-tests`		Skip generating test assertions	`false`

Supported curl flags

curl Flag	Result
`-X, --request`	HTTP method
`-H, --header`	Request header (command-line order is kept)
`-d, --data, --data-ascii, --data-binary`	Request body. Repeated flags are joined with `&`; `-d @file` becomes `< ./file`
`--data-raw`	Request body (a leading `@` is literal)
`--data-urlencode`	Percent-encoded body part (`name=value`, `=value`, `value`)
`--json`	JSON body plus `Content-Type` and `Accept: application/json`
`-F, --form`	`>>>multipart` block (`name=value`, `name=@file`)
`-G, --get`	Sends the data as a query string
`-I, --head`	`HEAD` request
`-T, --upload-file`	`PUT` with a `< ./file` body
`-u, --user`	`# @auth basic user, password` (`--digest` gives `digest`)
`--oauth2-bearer`	`# @auth bearer <token>`
`-m, --max-time`	`# @timeout <ms>`
`-A, --user-agent`	User-Agent header
`-e, --referer`	Referer header
`-b, --cookie`	Cookie header
`-k, --insecure`	Warning only: set `validateSSL: false` in `hitspec.yaml`

Flags that only change how curl prints or transfers (-s, -S, -v, -i, -f, --compressed, …) are ignored. Any other flag produces a warning, and a # TODO: above the request. Browser “Copy as cURL” commands (with $'...' quoting) are supported.

An uploaded file field keeps its form field name: -F avatar=@me.png becomes file avatar @me.png. The Postman, Insomnia and OpenAPI importers do the same. A field name that contains a space cannot be written that way; it falls back to file @path (field name file) with a warning.

Examples

hitspec import curl "curl -X POST https://api.example.com/users -H 'Content-Type: application/json' -d '{\"name\":\"John\"}'"

hitspec import curl @commands.txt -o tests/api.http

hitspec import curl @commands.txt --no-tests -o tests/api.http

Use @filename syntax to read curl commands from a file. The file supports line continuations with \.

hitspec import insomnia

Import from an Insomnia export file (v4 format).

hitspec import insomnia <export-file> [flags]

Flags

Flag	Short	Description	Default
`--output`	`-o`	Output file or directory path	stdout
`--no-tests`		Skip generating test assertions	`false`

Features

Request folders as name prefixes
Environments: a lone base environment becomes @name = value lines. When sub environments exist, all variables go to a hitspec.yaml environments: section (a base entry plus one per sub environment, each merged over the base), written next to the output, or printed to stderr when writing to stdout. An existing hitspec.yaml is never overwritten (hitspec.imported.yaml is written instead). hitspec finds hitspec.yaml from the working directory upward, so for a file written elsewhere pass it explicitly: hitspec run tests/api.http --config tests/hitspec.yaml --env dev.
Authentication (Bearer, Basic, API Key, Digest) as @auth
Request bodies (JSON, raw, form-urlencoded, multipart, GraphQL, file)
Headers and query parameters
Insomnia template tags ({% ... %}) are reported, not translated

Examples

hitspec import insomnia insomnia-export.json -o tests/api.http

hitspec import insomnia insomnia-export.json --no-tests -o tests/api.http

hitspec export

Export hitspec requests as runnable commands or client code.

hitspec export [format] <file> [flags]
hitspec export --format <format> <file> [flags]

Formats

The same names the Studio export action uses.

Format	Output
`curl` (default)	curl commands
`fetch`	JavaScript `fetch` (aliases: `javascript`, `js`)
`wget`	wget commands
`python`	Python `requests`
`httpie`	HTTPie commands
`go`	Go `net/http`
`ruby`	Ruby `Net::HTTP`

Query parameters (? key = value lines) and @auth (bearer, basic, API key) are included in every format. A form block (& key = value lines) is exported as the percent-encoded body the client sends (name=John%20Smith&e=a%26b), in curl and in the snippet formats. A request a format cannot express (multipart or file bodies outside curl) is skipped with a warning: on stderr and a SKIPPED comment in the output; if no request can be exported the command fails.

Flags

Flag	Short	Description	Default
`--format`	`-f`	Export format (when not given as the first argument)	`curl`
`--name`	`-n`	Filter by request name (glob pattern)	all
`--tags`	`-t`	Filter by tags (comma-separated)	all
`--output`	`-o`	Output file path	stdout
`--env`	`-e`	Environment for variable resolution	none
`--exec`		Execute the curl command directly (curl only)	`false`
`--verbose`	`-v`	Include `-v` in curl output (curl only)	`false`

The exported command is run through sh (on Windows, the sh from Git for Windows, or cmd when there is none), so bash is not required. curl itself must be installed.

The --exec flag requires exactly one matching request. Use --name to filter to a single request when using --exec.

Auth Conversion (curl)

hitspec	curl
`@auth bearer <token>`	`-H 'Authorization: Bearer <token>'`
`@auth basic <user>, <pass>`	`-u '<user>:<pass>'`
`@auth apiKey <header>, <key>`	`-H '<header>: <key>'`
`@auth digest <user>, <pass>`	`--digest -u '<user>:<pass>'`

Examples

hitspec export curl tests/api.http

hitspec export --format python tests/api.http

hitspec export fetch tests/api.http -o snippets.js

hitspec export curl tests/api.http --name "Login*"

hitspec export curl tests/api.http --tags smoke,auth

hitspec export curl tests/api.http --name "Login" --exec

hitspec export curl tests/api.http --env staging

Sample Output

# Request: Login
curl -X POST 'https://api.example.com/auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"username": "john", "password": "secret"}'

# Request: Get Profile
curl -X GET 'https://api.example.com/profile' \
  -H 'Authorization: Bearer {{login.token}}'

Use Cases

Debug failing tests by running the raw curl command
Share API calls with teammates who do not use hitspec
Use exported commands in shell scripts or other tools
Quickly test an endpoint outside the test framework

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

hitspec import & export

hitspec import

Supported Formats

Nothing is dropped silently

hitspec import openapi

Flags

Path parameters

One file per tag

Examples

hitspec import postman

Flags

Features

Examples

hitspec import curl

Flags

Supported curl flags

Examples

hitspec import insomnia

Flags

Features

Examples

hitspec export

Formats

Flags

Auth Conversion (curl)

Examples

Sample Output

Use Cases