~jisifu

notebook · envs.net
no framework, no fonts

post2 minnushellapitooling

Nushell as an API client

The worst part of an API call is never the HTTP. It is building the request in a language that only has strings. In curl, a JSON body is a string you escape, and a secret is a variable that must survive two layers of quoting without being word- split or expanded.

Nushell’s values are data, so a request is assembled as data and serialised once, at the end.

The shape of a call#

An authenticated read, from the script that drives my task list:

def "todoist get" [] {
  let url = "https://api.todoist.com/api/v1/tasks"
  let blob = http get -H ["Authorization" $"Bearer ($env.TODOIST_API_TOKEN)"] ($url)
  let tasks = ($blob | get results)
  $tasks | input list
}

Three things are doing work here. The response is a table before it is anything else, so get results is a field access rather than a jq pipeline. The header is a list of two strings, not a quoted argument. And the token comes from the environment of the shell that already loaded it — there is no $TOKEN interpolated into a command line where ps could read it.

A write is the mirror image:

{ content: $body, due_string: "today" }
| to json -r
| http post -H ["Content-Type" "application/json"]
           -H ["Authorization" $"Bearer ($env.TODOIST_API_TOKEN)"]
           ($url)

The body is a record until to json -r turns it into bytes, and the record is checked before it is sent: a missing field is a missing field, not a JSON body that happens to be malformed.

Query strings#

Where curl wants --data-urlencode and a prayer, nushell has url build-query:

{ user: "username", data: "mydata" } | url build-query
# user=username&data=mydata

Percent-encoding is not something to remember. The structure is the source, the query string is derived, and there is no second hand-written copy of the data to drift out of sync.

A local build that fetches#

The same commands turn a remote asset into a file, which is useful when a local tool cannot fetch:

http get $signature_url | save -f coverletter_signature.png

Typst will not download an image from a URL, but nushell will, and save -f is the whole bridge. That pattern replaced a manual download step in a document build that runs on demand.

The signed upload, and why bash is the wrong shape#

A signed upload is the case that made this click. The signature is not the payload alone: it is the payload string with the API secret appended, hashed, and sent back as a parameter. In bash that means a string built by concatenation, then hashed, then interpolated into a command line that already has quotes inside the payload — three layers of escaping where one wrong character silently produces a valid request with an invalid signature.

In nushell the payload is a record, the signature is a value computed from it, and the request is the record plus the signature. Nothing is escaped by hand because nothing is ever a string until the last step, and the secret stays in the environment rather than on a command line.

That is the argument, and it is not about taste. A shell that cannot represent a record will always make you encode one, and the encoding is where the bugs live.