unkn0wn-root/resterm v1.10.0

on GitHub

v1.10.0

Update: 1.10.1 names a command auth definition with name=, as in # @auth global command name=gh cmd="gh auth token". The examples below use the 1.10.0 form without name=, which has been changed (name is now explicit auth named definiton) in patch version 1.10.1. See the 1.10.1 release notes.

Command auth now takes a command line with cmd=, and a named definition runs the command once and shares the token with every request that uses it. Options written with spaces around = are now errors, because in 1.9.1 they could turn on a setting the line meant to turn be off. The Headers tab has a one-line summary and shows repeated headers the way they were received.

Command lines with cmd=

# @auth file command cmd="gh auth token"

cmd takes the command as you would type it. argv=["gh","auth","token"] still works.

• The value is split into arguments like a shell would split it, but no shell runs. Pipes, redirects, globs, $VAR, and $(...) reach the command as plain text.
• Single quotes keep everything inside them as written. Double quotes group words and accept \" and \\.
• Outside quotes, a backslash escapes a space, a quote, or another backslash. Any other backslash stays, so C:\tools\gh.exe works unquoted.
• Templates expand after the split. A {{...}} value with spaces stays one argument.

Wrap cmd in the quote kind the command line does not use:

# @auth command cmd="gcloud auth print-access-token --account 'me@example.com'"
# @auth command cmd='mycli --name "David Resterm"'

Without quotes, cmd=gh auth token is an error:

error[parse]: @auth expects key=value options but got "auth". Quote a value that has spaces

Named command auth

Define a command auth once with a name, then pick it per request with use=:

# @auth global command gh cmd="gh auth token"

### User
# @auth use=gh
GET https://api.github.com/user

### Same token in a custom header
# @auth use=gh header=X-GitHub-Token
GET https://api.github.com/rate_limit

The command runs once and both requests use the same token.

• Use @auth file for one file or @auth global for the whole workspace. A file definition wins over a global one with the same name.
• Resterm finds a global definition only in files it scans. If the definition is in a subdirectory, run Resterm with -R.
• Any request can run first. With cache_key, the request that seeded the key had to run before the others.
• The token is cached for the session, per environment and workspace. ttl, expiry_path, or expires_in_path make it expire sooner, and editing the definition runs the command again. resterm run --persist-auth keeps the token between runs.
• A named definition is not inherited. Only requests with use= get it.
• use= accepts only header, scheme, and timeout. Everything else belongs to the definition.
• A use= name that no file or global definition has fails the request.

When the command does not print an expiry, set ttl a little below the token's real lifetime. gcloud tokens last one hour:

# @auth file command gcloud cmd="gcloud auth print-access-token" ttl=50m

cache_key still works and keeps its key format, so tokens saved with --persist-auth are still reused. For new files, named definitions are simpler.

The editor suggests cmd= and completes definition names after use=. See _examples/auth_command.http or :help authentication.

Options with spaces around =

Write options as key=value, with no spaces around =. In most directives a key on its own is a switch set to true, so in 1.9.1 a spaced option could do the opposite of what it said:

### Staging health
# @settings http-insecure = false
GET https://staging.example.com/health

In 1.9.1, this request skipped TLS certificate verification. http-insecure was read as true, and false was dropped. Now the line is an error and the option is not set:

error[parse]: @settings option "http-insecure" has spaces around =. Write it as key=value
--> api.http:2:13
     |
   2 | # @settings http-insecure = false
     |             ^

• This covers every directive that takes options, including @settings, @ssh, @k8s, @websocket, @auth, @workflow, @step, and workflow branches.
• key = value, key =value, key= value, and =value are all errors.
• An empty value such as strict_hostkey= is still allowed at the end of the line or before another key=value option.
• A global or file @ssh or @k8s profile written this way is not available to requests. An @ssh profile is reported as not found, and a @k8s profile reports the error to every request that uses it.

Two more cases from 1.9.1: # @settings timeout = 5s failed the request with invalid timeout "true", and # @default fail = "unexpected status" failed the workflow with the message true.

Stricter @auth lines

@auth command now accepts only its documented options. In 1.9.1, a typo such as cahce_key=gh was ignored, so the command ran for every request. Now it is an error:

error[parse]: @auth command does not accept cahce_key

The same applies to {auth: {type: "command", ...}} in @apply and @patch.

An @auth line with an error no longer lets a request go out with other auth or none. A request that takes its auth from that line, directly, by inheritance, or through use=, fails with the line's error. Requests with their own @auth or @auth none are not affected.

For example, with this line in defs.http:

# @auth global bearer 'unclosed

In 1.9.1, requests in other files inherited it and sent Authorization: Bearer unclosed. Now they fail and point to the line:

error[auth]: @auth is missing a closing "'" (/work/api/defs.http:1)

Headers tab

• The top of the tab is one summary line, such as 200 OK · time 143ms · size 9 B. The request side shows the method, URL, and request size.
• The Response / Request switch shows the header count, such as ● Response │ Request 4.
• Repeated headers show each value on its own line.

In 1.9.1, repeated values were sorted and joined with a comma. That breaks Set-Cookie, because its Expires date has a comma of its own:

Set-Cookie: a=1, b=2; Expires=Wed, 21 Oct 2026 07:28:00 GMT

Now each cookie has its own line:

Set-Cookie: b=2; Expires=Wed, 21 Oct 2026 07:28:00 GMT
Set-Cookie: a=1

The same applies to headers in the Workflow step detail and in resterm run --headers.

Workflow tab

Space now works like Enter on the step list. It opens the selected step's detail and returns to the list.

Changed

These changes may affect existing request files:

• A word after @auth file command or @auth global command is now the name of a named definition. In 1.9.1 it was ignored.
• Options with spaces around = are errors, and the option is not set.
• Unknown @auth command options and unclosed quotes in @auth lines are errors.
• A request whose @auth line has an error fails instead of being sent.

The first change can turn auth off without an error. In 1.9.1, this line gave every request below it a token:

# @auth file command gh argv=["gh","auth","token"]

Now gh is the name of the definition. Named definitions are not inherited, so the requests below it are sent without auth. With @auth global, the same happens to every request in the workspace. Remove gh to keep the line as the default, or add # @auth use=gh to each request that needs the token.