Getting started with aux4

What's aux4?

aux4 is a CLI (Command-line Interface) generator, used to create high-level scripts and automate your daily tasks.

Install

> curl https://aux4.sh | sh

IDEs

Add support for aux4 in your favorite IDE.

Visual Studio Code

aux4 Visual Studio Code Extension

Vim/Neovim

aux4 Vim Plugin

How to use

aux4 is a command-line interface generator tool designed to be extremely simple to learn and use. It requires creating a .aux4 file using JSON format. It all starts from the profiles array.

{
  "profiles": [
    ...
  ]
}

Each profile has a name and a list of commands. But the most important profile is the main one.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        ...
      ]
    }
  ]
}

The command is defined by its name, followed by a sequence of command-line instructions that will be executed, and a help section with its documentation.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "<COMMAND NAME>"
          "execute": [
            "<FIRST COMMAND-LINE INSTRUCTION>",
            "<SECOND COMMAND-LINE INSTRUCTION>",
            "..."
          ],
          "help": {
            "text": "<DESCRIPTION OF THE COMMAND>"
          }
        }
      ]
    }
  ]
}

Hello World

The best way to start is creating a Hello World example.

We can create a hello command that will print Hello World.

First, create the .aux4 file.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "hello",
          "execute": [
            "echo 'Hello World'"
          ],
          "help": {
            "text": "say hello world"
          }
        }
      ]
    }
  ]
}

The command hello (lines 6-14) will print the Hello World in the console output (line 9). The help section is used to document the command (line 12).

When you run aux4 in the same folder where the .aux4 file is, it lists all available commands.

> aux4

hello
say hello world

To execute your command, just run aux4 hello.

> aux4 hello

Hello World

Using Variables

Now we can make our Hello World example a little more personal.

We can include the firstName and lastName in the greeting message (line 9).

In the help section, we also can document those variables, so we don't forget in the future (lines 13-23).

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "hello",
          "execute": [
            "echo 'Hello ${firstName} ${lastName}!'"
          ],
          "help": {
            "text": "say hello",
            "variables": [
              {
                "name": "firstName",
                "text": "the first name to say hello"
              },
              {
                "name": "lastName",
                "text": "the last name to say hello",
                "default": ""
              }
            ]
          }
        }
      ]
    }
  ]
}

I hope you noticed the difference between those variables. For the lastName variable, we defined a default value for it (line 21). By adding a default value (even an empty string), the CLI will not prompt for that variable when it is not provided.

If you run aux4 command, it will display a short documentation on your command, and also the list of variables.

> aux4

hello
say hello
  --firstName
  --lastName

However, when you run aux4 --help, it will display the full documentation, including the description of each variable.

> aux4 --help

hello
say hello

  --firstName
    the first name to say hello

  --lastName
    the last name to say hello

    Default:

Now you can run your command passing the variables.

> aux4 hello --firstName Douglas --lastName Crockford

Hello Douglas Crockford!

Maybe you're wondering what happens if you run without the variables. It will prompt the user to input the value for the required variables.

> aux4 hello

✔ the first name to say hello: |

Since we defined a default value for lastName, it will not prompt the user.

> aux4 hello

✔ the first name to say hello: David
Hello David !

But you still can manually pass the value for that:

> aux4 hello --lastName SG

✔ the first name to say hello: David
Hello David SG!

Parsing JSON

If you work with data or APIs, parsing and extracting data from JSON is inevitable. aux4 has a built-in tool to parse JSON. Let's see how easy it is to use.

Let's say we want to create a command that will extract the version from the package.json file.

{
  "version": "1.0"
}

By using the json: executor prefix, it automatically parses the output of the command to JSON (line 9).

You can always get the output of the previous command using the response variable ${response}, in this case the value will be a JSON object instead of string (line 10).

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "get-version",
          "execute": [
            "json:cat package.json",
            "echo 'version ${response.version}'"
          ],
          "help": {
            "text": "get the version from package.json"
          }
        }
      ]
    }
  ]
}

When you run the command, it will display the version.

> aux4 get-version

version 1.0

I know you want to make it fancier. So we can change it to read the JSON from an URL instead of local file.

We just need to use curl -s to get the data from the URL (line 9), and include the variable in the documentation (lines 14-19).

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "get-version",
          "execute": [
            "json:curl -s ${url}",
            "echo 'version ${response.version}'"
          ],
          "help": {
            "text": "get the version from package.json",
            "variables": [
              {
                "name": "url",
                "text": "the url of the package"
              }
            ]
          }
        }
      ]
    }
  ]
}

Now when you run the command, it will display the version from the URL.

> aux4 get-version --url https://raw.githubusercontent.com/heroku/node-js-sample/master/package.json

version 0.2.0

Confirmation Prompt

Depending on what the command-line does, it's important to make sure the user really wants to execute it.

aux4 has a built-in confirmation prompt using the confirm: executor. You just need to provide the message to the user (line 9).

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "execute",
          "execute": [
            "confirm:Are you sure you want to execute it in ${env}",
            "echo 'Executing in ${env}...'"
          ],
          "help": {
            "text": "execute the command in the specified environment",
            "variables": [
              {
                "name": "env",
                "text": "the environment to execute the command"
              }
            ]
          }
        }
      ]
    }
  ]
}

Once you run the command, it will prompt the confirmation to the user.

> aux4 execute --env PROD

? Are you sure you want to execute it in PROD? [y/N] |

If the user says yes, it will proceed the execution.

Are you sure you want to execute it in PROD: y
Executing in PROD...

If the user says no, it will abort the execution.

Are you sure you want to execute it in PROD: N
User aborted

For Each

Let's iterate over this. We both know there are better ways to do it, but let's use a simple use case to make it very clear to everybody how to use this tool.

We are going to create a command to count the lines of each .txt file.

First, we just list the *.txt files using ls (line 9). Note that we are using a nout: executor prefix. This means we don't want to print the output of that command. nout stands for no output.

Second, we will iterate over the previous output, and for each file using the each: executor, we are going to count its lines (line 10).

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "count-lines",
          "execute": [
            "nout:ls *.txt",
            "each:wc -l ${item}"
          ],
          "help": {
            "text": "count the number of lines in each text file"
          }
        }
      ]
    }
  ]
}

We can run the command, assuming you have .txt files in the directory, it should show their number of lines.

> aux4 count-lines

f1.txt
f2.txt
f3.txt

How does each work? It's always based on the previous command output. If the output is text, it will iterate over the lines. If the output is a JSON array, it will iterate over the elements of the array.

Assuming we have people.json file, with an array of people with their names and ages.

[
  {
    "name": "Sarah",
    "age": 30
  },
  {
    "name": "Joshua",
    "age": 40
  },
  {
    "name": "Noah",
    "age": 50
  }
]

We can create a command to list the people and show how old they are.

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "list-people",
          "execute": [
            "json:cat people.json",
            "each:echo '${item.name} is ${item.age} years old'"
          ],
          "help": {
            "text": "list the people in the people.json file"
          }
        }
      ]
    }
  ]
}

In this case, we parse the JSON on line 9, and for each element we print the name and age (line 10).

> aux4 list-people

Sarah is 30 years old
Joshua is 40 years old
Noah is 50 years old

Multiple Profiles

Okay, it's time to make things more interesting. In this scenario, we will create two commands to call two REST API endpoints.

As a matter of organization, we will create one profile for the REST API (lines 17-59), to keep the commands isolated. We can add one command for each endpoint:

get-person (lines 20-38)
get-person-transactions (lines 39-57)

The main profile is required (lines 3-16). So, we can include a command called api that redirects to the profile api using the profile: executor (line 9).

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "api",
          "execute": [
            "profile:api"
          ],
          "help": {
            "text": "the company api"
          }
        }
      ]
    },
    {
      "name": "api",
      "commands": [
        {
          "name": "get-person",
          "execute": [
            "curl -s https://${env}-mycompanyapi.com/person/${id}"
          ],
          "help": {
            "text": "get person's information",
            "variables": [
              {
                "name": "env",
                "text": "the api environment"
              },
              {
                "name": "id",
                "text": "the person id"
              }
            ]
          }
        },
        {
          "name": "get-person-transactions",
          "execute": [
            "curl -s https://${env}-mycompanyapi.com/person/${id}/transactions"
          ],
          "help": {
            "text": "get all the person's transactions",
            "variables": [
              {
                "name": "env",
                "text": "the api environment"
              },
              {
                "name": "id",
                "text": "the person id"
              }
            ]
          }
        }
      ]
    }
  ]
}

When you run aux4, it will show the api command from the main profile.

> aux4

api
the company api

But when you run aux4 api, it will list the commands from the api profile.

> aux4 api

get-person
get person's information
  --env
  --id

get-person-transactions
get all the person's transactions
  --env
  --id

In this case, if you want to get the person's information, you can call the command. This is a great way to organize your commands, grouping them in a way that makes more sense to your business.

> aux4 api get-person --env dev --id 120

{
  "id": 120,
  "name": "Simon"
}

Nested Folders

aux4 loads the .aux4 files from all parent directories and combines them automatically. Considering you have the following structure:

/home/user
- /.aux4
- /data
  - /.aux4

Imagine the /home/user/.aux4 file is the same we used in the previous example (Multiple Profiles).

Let's say we want to include another command to the api profile, but we just want to see that when we are in the data folder. So we can add to the /home/user/data/.aux4 file:

{
  "profiles": [
    {
      "name": "api",
      "commands": [
        {
          "name": "another-command",
          "execute": [
            "echo 'another api endpoint'"
          ],
          "help": {
            "text": "another api call"
          }
        }
      ]
    }
  ]
}

I hope you noticed that we didn't include the main profile in this case. Because it already loaded it from the parent directory.

In this way, when we run aux4 api from the /home/user/data/ directory. We can see the extra command.

> aux4 api

get-person
get person's information
  --env
  --id

get-person-transactions
get all the person's transactions
  --env
  --id

another-command
another api call

However, if you want to add extra commands, that is not under the api profile. You still can include them to the main profile (lines 3-16).

{
  "profiles": [
    {
      "name": "main",
      "commands": [
        {
          "name": "hello",
          "execute": [
            "echo 'Hello World!'"
          ],
          "help": {
            "text": "say hello"
          }
        }
      ]
    },
    {
      "name": "api",
      "commands": [
        {
          "name": "another-command",
          "execute": [
            "echo 'another api endpoint'"
          ],
          "help": {
            "text": "another api call"
          }
        }
      ]
    }
  ]
}

Now if you run again aux4 from /home/user/data directory. It will list both commands hello and api.

> aux4

hello
say hello

api
the company api

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Table of Contents

Getting started with aux4

What's aux4?

Install

IDEs

Visual Studio Code

Vim/Neovim

How to use

Hello World

Using Variables

Parsing JSON

Confirmation Prompt

For Each

Multiple Profiles

Nested Folders