Creating a basic HTTP client using Vim, cURL and JQArjun Aravind • 20 August 2023 • 6 min read Anyone who's worked with me closely enough knows that when I'm on the computer, I tend to avoid using the mouse as much as possible. It's just a habit that I've developed over the last few years ever since I started getting wrist pains from using the mouse too much.
I follow this to the extent that, these days, I browse the internet, watch YouTube, use Teams, write code,
Calling and testing APIs, however, has been a thorn in my side for too long a time.
Mainstream API tools (like Postman and Insomnia) don't seem to be for me as there are just way too many shortcuts to remember, plus the options for manipulating responses are limited.
cURL + JQ is a particularly good combo though! The disadvantage with this method is that it's cumbersome to save and view the resultant response. It's also not possible to save the cURL request itself.
And that's when it hit me!Yes, I know, there's already a ton of HTTP plugins out there for Vim. But I felt like making my own and, if you'd like to have the same setup, you can recreate this without any plugins or installations. Let's check it out!
I like using Vim. I like using cURL and JQ. Why not just use them all together?
Open up your
and paste the following key mappings in it.
cmap <C-E> t.-1 \ \| '<,'>s/<<\([a-zA-Z_]*\)>>/\=get(http_client_environment,submatch(1))/g \ \| echo "Query generated!" <Enter> cmap <C-X> w !bash <Enter>
Save the file and enter the following command:
Open three files (
) in three different windows like in the GIF above.
Paste the text in this link in
and the text in this link in
. Save both the files and enter the following command:
, visually select the entirety of the first cURL command and enter command mode (press
). You should see
appear. Now enter
Ctrl + E
A cURL query with the substituted variables should appear.
And now, for the final act, visually select the entirety of the generated cURL query and press
, again following which
should appear. Now enter
Ctrl + X
Assuming it all went right, Vim should ask you if you want to "load" a file. We want this so press
- Open the
file and you should have your response!
Tip 1: Try doing the same for the second cURL query as well.
Tip 2: If you have any questions, try looking at the GIF to see what the workflow looks like.
Note 1: If you're having issues, check out the "Troubleshooting" section below.
contains a dictionary that stores all the necessary environment variables. Using the same format shown in the example, you can add a variable of your choice.
, you can refer to a variable by enclosing the variable in double angular brackets like this:
- The dictionary should always be called
- The variable names should only contain alphanumeric and underscore characters.
- Everytime you make a change to
, you will need to reload the changes by entering
When you visually select a query with variables in
, a valid cURL query with the substituted variables is generated.
Ctrl + E
When you visually select this generated query and then press
, Vim executes the cURL query in a bash shell. That's it, just a bash shell. No fancy stuff.
Ctrl + X
You might have noticed that the cURL output is being redirected to the
file. You don't have to do this but, this way, you may find that you can inspect both the request and response in Vim itself.
Finally, JQ is a really helpful CLI tool for processing JSON output. Using JQ, it's possible to format, parse and process JSON. In the sample
file, you can see that we parse the response and extract only the fields that we want using JQ.
- Learning JQ is outside the scope of this article but I would really recommend just skimming through all the functionality that it provides.
- Once you know what's possible with it, you can always refer the docs to see how to implement them whenever needed.
- Ensure that you stick to the
format when adding an environment variable. Remember to add a comma at the end of every dictionary line.
- If any changes are made to
, always enter
to load the changes.
- After adding the
Ctrl + E
key mappings to your
Ctrl + X
, make sure you've loaded the changes by entering
. You only have to do this the first time.
- When visually selecting a query but before pressing either
Ctrl + E
, ensure you enter command mode (by pressing
) and the
- If the response isn't showing in the file you've redirected the cURL output too, make sure that the filepath specified in
is that of the correct file.
For the environment variables, we make use of Vimscript. It's a small scripting language that can be used to extend Vim's capabilities. You can do all sorts of things from using variables to defining functions. Vim even provides a standard library with a set of helpful functions!
- The dictionary in
is a Vimscript dictionary that allows us to store key-value pairs.
The key mapping that we're using to generate the cURL queries is just a simple matter of finding a variable in the visually selected range and replacing it with the value from the dictionary.
- You might have heard of Ranges in Vim which let you specify a text ranges to perform various operations on. Similarly, the
that we see is a range too!
- To be more precise, it is the range which is used to refer to all the characters that have been visually selected in the editor.
As mentioned before, the second key mapping that we're using to run the cURL + JQ query basically just executes the query in a bash shell.
Hopefully, this article was interesting to read. Let me know if you did actually go ahead and use this setup. Contact me if you have any criticisms or improvements. Cheers!