<img src="assets/logo.svg" height=200 style="margin-bottom: 20px">

Introduction

Ain is a terminal HTTP API client. It's an alternative to postman, paw or insomnia.

• Flexible organization of API:s using files and folders (examples).
• Use shell-scripts and executables for common tasks.
• Put things that change in environment variables or .env-files.
• Handles url-encoding.
• Share the resulting curl, wget or httpie command-line.
• Pipe the API output for further processing.
• Tries hard to be helpful when there are errors.

Ain was built to enable scripting of input and further processing of output via pipes. It targets users who work with many API:s using a simple file format. It uses curl, wget or httpie to make the actual calls.

⭐ Please leave a star if you find it useful! ⭐

Table of contents

<!-- npx doctoc --github --notitle --maxlevel=2 --> <!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• Pre-requisites
• Installation
  • If you have go installed
  • Via homebrew
  • Via scoop
  • Via the AUR (Arch Linux)
  • Download binaries yourself
• Syntax highlight
  • Vim plug
• Quick start
• Important concepts
• Template files
• Running ain
• Supported sections
  • [Host]
  • [Query]
  • [Headers]
  • [Method]
  • [Body]
  • [Config]
  • [Backend]
  • [BackendOptions]
• Variables
• Executables
• Fatals
• Quoting
• Escaping
• URL-encoding
• Sharing is caring
• Handling line endings
• Troubleshooting
• Ain in a bigger context
• Contributing
  • Commit messages
  • Testing

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Pre-requisites

You need curl, wget or httpie installed and available on your $PATH. To test this run ain -b. This will generate a basic starter template listing what backends are available on your system in the [Backend] section. It will select one and leave the others commented out.

You can also check manually what backends you have installed by opening a shell and type curl, wget or http (add the suffix .exe to those commands if you're on windows). Any output from the command means it's installed.

On linux or mac one of the three is likely to already be installed. The others are available in your package manager or homebrew.

If you're on windows curl.exe is installed if it's windows 10 build 17063 or higher. Otherwise you can get the binaries via scoop, chocolatey or download them yourself. Ain uses curl.exe and cannot use the curl cmd-let powershell builtin.

Installation

If you have go installed

You need go 1.13 or higher. Using go install:

go install github.com/jonaslu/ain/cmd/ain@latest

Via homebrew

Using the package-manager homebrew

brew install ain

Via scoop

Using the windows package-manager scoop

scoop bucket add jonaslu_tools https://github.com/jonaslu/scoop-tools.git
scoop install ain

Via the AUR (Arch Linux)

From arch linux AUR using yay

yay -S ain-bin

Download binaries yourself

Install it so it's available on your $PATH: https://github.com/jonaslu/ain/releases

Syntax highlight

Ain comes with it's own syntax highlight for vim.

Vim plug

Using vim plug

Plug 'jonaslu/ain', { 'rtp': 'grammars/vim' }

Manual install

Quick start

Ain comes with a built in basic template that you can use as a starting point. Ain checks what backends (that's curl, wget or httpie) are available on your system and inserts them into the [Backend] section of the generated template. One will be selected and the rest commented out so the template is runnable directly.

Run:

ain -b basic-template.ain

The command above will output a starter-template to the file basic-template.ain. The basic template calls the / GET http endpoint on localhost with the Content-Type: application/json.

To run the template specify a PORT variable:

ain basic-template.ain --vars PORT=8080

See help for all options: ain -h and check out the examples.

Important concepts

• Templates: Files containing what, how and where to make the API call. By convention has the file suffix .ain.
• Sections: Label in a file grouping the API parameters.
• Variables: Things that vary as inputs in a template file.
• Executables: Enables using the output of a command in a template file.
• Backends: The thing that makes the API call (curl, wget or httpie).
• Fatals: Error in parsing the template files (it's your fault).

Template files

Ain assembles data in template files to build the API-call. Ain parses the data following labels called sections in each template file. Here's a full example:

[Host]           # The URL. Appends across files. Mandatory
http://localhost:${PORT}/api/blog/post

[Query]          # Query parameters. Appends across files
id=2e79870c-6504-4ac6-a2b7-01da7a6532f1

[Headers]        # Headers for the API-call. Appends across files
Authorization: Bearer $(./get-jwt-token.sh)
Content-Type: application/json

[Method]         # HTTP method. Overwrites across files
POST

[Body]           # Body for the API-call. Overwrites across files
{
  "title": "Reaping death",
  "content": "There is a place beyond the dreamworlds past the womb of night."
}

[Config]         # Ain specific config. Overwrites across files
Timeout=10

[Backend]        # How to make the API-call. Overwrites across files. Mandatory
curl

[BackendOptions] # Options to the selected backends. Appends across files
-sS              # Comments are ignored.

The template files can be named anything but some unique ending-convention such as .ain is recommended so you can find them easily.

Ain understands eight [Sections] with each of the sections described in details below. The data in sections either appends or overwrites across template files passed to ain.

Anything after a pound sign (#) is a comment and will be ignored.

Running ain

ain [OPTIONS] <template.ain> [--vars VAR=VALUE ...]

Ain accepts one or more template-file(s) as a mandatory argument. As sections appends or overwrite you can organize API-calls into hierarchical structures with increasing specificity using files and folders.

You can find examples of this in the examples folder.

Adding an exclamation-mark (!) at the end of a template file name makes ain open the file in your $VISUAL or $EDITOR editor. If none is set it falls back to vim in that order. Once opened you edit the template file for this run only.

Example:

ain templates/get-blog-post.ain!     # Lets you edit the get-blog-post.ain for this run

Ain waits for the editor command to exit. Any terminal editor such as vim, emacs, nano etc will be fine. If your editor forks (as vscode does by default) check if there's a flag stopping it from forking. To stop vscode from forking use the --wait flag:

export EDITOR="code --wait"

If ain is connected to a pipe it will read template file names from the pipe. This enables you to use find and a selector such as fzf to keep track of the template-files:

$> find . -name *.ain | fzf -m | ain

Template file names specified on the command line are read before names from a pipe. This means that echo create-blog-post.ain | ain base.ain is the same as ain base.ain create-blog-post.ain.

When making the call ain mimics how data is returned by the backend. After printing any internal errors of it's own, ain echoes back output from the backend: first the standard error (stderr) and then the standard out (stdout). It then returns the exit code from the backend command as it's own unless there are error specific to ain in which it returns status 1.

Supported sections

Sections are case-insensitive and whitespace ignored but by convention uses CamelCase and are left indented. A section cannot be defined twice in a file. A section ends where the next begins or the file ends.

See escaping If you need a literal section heading on a new line.

[Host]

Contains the URL to the API. This section appends lines from one template file to the next. This feature allows you to specify a base-url in one file (e g base.ain) as such: http://localhost:3000 and in the