Persisting and sharing Insomnia projects using Git

Insomnia is by far my favorite REST (and GraphQL) client. It's fast and lightweight; perfect for testing and toying with APIs.

A common use-case when working with a client like Insomnia is to share your collection of requests (your Insomnia project) with others for collaboration, or simply "sharing" with yourself for use with multiple machines/setups.

Insomnia supports sharing of ones project by using a 90s style "export everything into a single file" -button, accompanied by an "import everything from a single file" one. Excellent for some, far from ideal for others.

Having knowledge of Git, the 90s approach seems ripe for replacing with a Git-powered solution. So I decided to tackle this.

Controlling where Insomnia stores its data

Insomnia uses a database structure internally to store the project data (i.e. request collection). Usefully, we can instruct Insomnia where to look for and save said data manually, using the INSOMNIA_DATA_PATH environment variable.

Using this, we can launch Insomnia with a custom data path like so:

$ INSOMNIA_DATA_PATH=~/.insomnia path/to/insomnia

NOTE: In my case (on MacOS), I had to point to Insomnia at: /Applications/Insomnia.app/Contents/MacOS/Insomnia

If successful, you should see a fresh Insomnia when launching, seen as it no longer points to the default data path.

NOTE: If you wish to retain your old project, simply use the 90s style import/export from the original data path.

Using Git to control the data

Now that Insomnia stores its data in a controlled directory, pushing said data to a Git repository is trivial. We can simply initialize a new Git repository in the data directory:

$ cd ~/.insomnia
$ git init

We can then use our favorite Git remote provider (e.g. GitHub, Bitbucket) and connect it to the repository.

Automatically pulling and pushing changes

While you could manually commit the changes in the data directory every time you finish using Insomnia, I prefer to have it done automatically, as otherwise my human brain will forget. To achieve this, I simply run Insomnia along with a few Git commands:

cd ~/.insomnia &&
git pull &&
INSOMNIA_DATA_PATH=~/.insomnia path/to/insomnia &&
git commit -am :robot: &&
git push

I simply wrap the above commands in an alias, and add it to my .*rc -file, in my case, .zshrc:

alias insomnia=" cd ~/.insomnia && git pull && INSOMNIA_DATA_PATH=~/.insomnia path/to/insomnia && git commit -am :robot: && git push"

This, of course, completely ignores any merge conflicts that may occur if sharing the repository with someone else who pushes changes to it. As I'm only using this to back up my Insomnia project, I will leave handling merge conflicts as a reader assignment 😗

(Optional) Running in the background using tmux

The last icing on top of this solution is running the Insomnia process in the background. When using the alias from before, it will occupy a terminal until Insomnia exits. This is no big deal, but in the interest of keeping things clean, I've opted to run the command in a tmux session. Out of sight, out of mind.

To achieve, this, the alias is simply extended to run inside a detached tmux session, like so:

tmux new-session -s insomnia -d '
cd ~/.insomnia &&
git pull &&
INSOMNIA_DATA_PATH=~/.insomnia path/to/insomnia &&
git commit -am :robot: &&
git push'

This can, once again, simply be wrapped in an alias for convenience.

And that's it! 🎉

You can now persist your Insomnia project using Git. Thanks for reading.

Finishing Notes

1. This solution is likely not robust for sharing with others who active push changes to the collection.
2. An Insomnia plugin exists which will do this for you, but as of writing, it only supports GitLab.
3. The popular Insomnia alternative Postman has built-in collaboration features, but is, as of writing, limited to 3 people unless you get your wallet out.h