# aux4 docs

## What's aux4?

_aux4_ is an Open Source CLI (Command-line Interface) generator, used to create high-level scripts and automate your daily tasks.
It generates a CLI tool in runtime by parsing a JSON file called `.aux4` in your current (or parent) folder.

The name _aux4_ is an abbreviation of _auxiliary for_. So when you combine it with the name of your command,
you can read it as _auxiliary for git_ or _auxiliary for pipeline_, etc. The idea is to build a tool to help you do something else.

## Install

```bash
> curl https://aux4.sh | sh
```

See [Installation](/install) for more options including Docker.

## IDEs

aux4 has editor plugins for [Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=aux4.aux4) and [Vim/Neovim](https://github.com/aux4/vim). See the [IDEs](/ides) page for setup instructions.

## Getting Started

The best way to start learning _aux4_ is our [Getting Started](/getting-started) section, please check it out if you haven't already.

## The .aux4 file

The `.aux4` file has the structure and definition of your command-line interface (CLI) tool.

It is a hidden file (that's why it starts with a dot)
to avoid disturbing your environment. For example, if you run the `ls` command, it won't list that file. This allows you to iterate over the directory's files
without interference.

This file uses [JSON](https://www.json.org) format, and it's primarily defined by an array of profiles.

```json
{
  "profiles": [
    ...
  ]
}
```

## Profile

A _profile_ is a group of commands. It's easier for the user of your CLI tool if you have your commands grouped (or organized)
by category so they can easily navigate through them.

When you run the `aux4` command, the first thing it will do is list the commands from the _main_ profile.

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

## Command

The _command_ is what the user will execute in the prompt. The _command_ has a name (line 7), a sequence of command-line instructions
to be executed (lines 8-10), and a help section describing how it works (lines 11-13).

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

When you run `aux4` it lists all the commands from the _main_ profile.

```bash
> aux4
```

```text
hello
say hello
```

To run your command you can just run `aux4 <COMMAND>`.

```bash
> aux4 hello
```

```text
Hello World
```

## Learn More

- [Getting Started](/getting-started) - Step-by-step tutorials to get up and running
- [Installation](/install) - Install aux4 via curl, Homebrew, Docker, or pkgx
- [IDEs](/ides) - Editor plugins for VS Code and Vim/Neovim
- [Variables](/variables) - Parameters, prompts, defaults, environment variables, and more
- [Executors](/executors) - All available executors (set, log, json, each, profile, etc.)
- [Functions](/functions) - Built-in functions for formatting variables (param, values, object, arg, args)
- [Configuration](/config) - Load variables from YAML/JSON configuration files
- [Commands](/commands) - Built-in commands (version, man, source, which, shell, completion)
- [Hooks](/hooks) - Cross-cutting interceptors that run before, after, or on error of any command
- [Render](/render) - Format command output as a list, table, or other human-friendly view
- [Testing](/testing) - Write and run tests for your aux4 commands
- [Package Manager](/package-manager) - Install, manage, and publish packages with pkger
- [Packaging](/packaging) - Package and distribute your CLI tools through the aux4 Hub
- [Docker](/docker) - Run aux4 in Docker containers