# Custom command aliases Aliases provide a way to abbreviate system commands and add default arguments to commonly used commands. Aliases are described in user-config files (see `apolo help user-config` for details). `~/.apolo/user.toml` is used for **global** aliases, and `.apolo.toml` can be used for saving **project-specific** aliases. Project aliases overrides global ones if the same alias name exists in both configuration files. There are two types of aliases: **internal** and **external**. **Internal** aliases execute built-in apolo commands, and \*\* external\*\* aliases execute **system OS** commands. ## Internal aliases Internal aliases are used for running existing apolo CLI commands under a different name and with optional overriden defaults (passed predefined command line options and arguments). For example, the following alias definition creates a `apolo lsl` command that executes `apolo storage ls -hl` to list the storage's content using a long output mode with human-readable file sizes. ``` [alias.lsl] cmd = "ls -l --human-readable" help = "List directory contents in a long mode. ``` Available configuration arguments: * `[alias.lsl]`: Defines a subgroup for a named alias, `lsl` in this case. * `cmd`: The command to execute with provided overridden options, this key is **mandatory**. The `cmd` key in the alias section implies **internal alias** mode. * `help`: Help string displayed by the `apolo lsl --help` command (optional). Internal aliases accept additional command line options and agruments, and pass them to the underlying command as is. For example, `apolo lsl storage:directory` works as `apolo ls -l --human-readable storage:directory` ## External aliases External aliases spawn a subprocess with passing default options and arguments. All user-provided arguments are passed to the underlying program as well. For example, the following configuration defines `apolo du` command as an alias for the system `du --human-readable` command with an additional ability to specify a directory for analysis. ``` [alias.du] exec = "du" args = "[FILE]..." options = [ "-h, --human-readable print sizes in powers of 1024 (e.g., 1024M)", "-d, --max-depth=N max recursion level for subdirectories lookup", ] help = ''' Summarize disk usage of the set of files, recursively for directories. ''' ``` Available configuration arguments: * `[alias.du]`: Defines a subgroup for a named alias, `du` in this case. * `exec`: External command to execute, this key is **mandatory**. The `exec` key in the alias section implies **external alias** mode. * `args`: Positional argumentss accepted by the alias, the format is described below (optional). * `options`: Options and flags accepted by the alias, the format is described below (optional). * `help`: Help string displayed by `apolo du --help` command (optional), **args** is a string with a sequence of arguments, e.g. `DIR SRC... [DST]` If an argument is enclosed in square brackets, it's **optional** (`[FILE]`). If an argument ends with an ellipsis, this argument accepts multiple values (`SRC...`) **options** is a list of strings specifying various options. Each string describes a single option. The option definitions should be separated from the option descriptions (help) by two or more spaces. An option definition can contain: * Short name (`-h`) * Long name (`--human-readable`) * Indication of the required value type (`-d, --max-depth=N`). If the required value indicator (`=NAME`) is absent, the option will be considered a boolean flag. **exec** defines an external system command to execute. The command is spawned in a subprocess. Apolo CLI waits for the subprocess to be finished, and then returns the exit code to the outer caller. The parameter may specify an executable file along with some options. For example, `exec = "du --human-readable"` enforces human-readable mode for the `du` command. `exec` can be used in **simplified** and **pattern** mode. ## Pattern mode In **pattern mode**, the system command is used along with **substitutions**. For example, `exec = "du {human_readable} {max_depth} {file}"`. Substitution is enclosed in curly brackets and represents a variable name to expand, e.g. `{file}`. It's expanded with an option or positional argument specified by `args` or `options`. The substitution name is automatically lowercased, and dashes (`-`) are replaced with underscores (`_`). For example, `args = "ARG-NAME"` matches to `{arg_name}`. If a substitution corresponds to an optional parameter not provided by the user, this substitution will be expanded to an empty string. If a substitution corresponds to multiple values, all of them are used. For example, `apolo du folder1 folder2` expands to `du folder1 folder2` since the `[FILE]...` argument matches to `folder1 folder2` values. Options are expanded using the longest form if provided, e.g. `apolo du -h` is expanded to `du --human-readable`. Options with values are expanded as well, e.g. `apolo du -d 1` is expanded to `du --max-depth 1`. `apolo du --max-depth 1` matches to the same command. ## Simplified mode In **simplified mode**, the `exec` value does not contain any **substitutions**. In this case, all parsed `options` and `args` are appended to the executed command automatically if provided. For example, `exec = "du"` is expanded to `exec = "du {human_readable} {max_depth} {file}"` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.apolo.us/index/apolo-cli/topics/topic-aliases.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.