nushell/docs/commands/alias.md

# alias

This command allows you to define shortcuts for other common commands. By default, they only apply to the current session. To persist them, add `--save`.

Syntax: `alias {flags} <name> [<parameters>] {<body>}`

The command expects three parameters:

* The name of the alias
* The parameters as a space-separated list (`[a b ...]`), can be empty (`[]`)
* The body of the alias as a `{...}` block

## Flags

* `-s`, `--save`: Save the alias to your config (see `config path` to edit them later)

## Examples

Define a custom `myecho` command as an alias:

```shell
> alias myecho [msg] { echo $msg }
> myecho "hello world"
hello world
```

Since the parameters are well defined, calling the command with the wrong number of parameters will fail properly:

```shell
> myecho hello world
error: myecho unexpected world
- shell:1:18
1 | myecho hello world
  |              ^^^^^ unexpected argument (try myecho -h)
```

The suggested help command works!

```shell
> myecho -h

Usage:
  > myecho ($msg) {flags}

parameters:
  ($msg)

flags:
  -h, --help: Display this help message
```

## Persistent aliases

Aliases are most useful when they are persistent. For that, use the `--save` flag:

```shell
> alias --save myecho [msg] { echo $msg }
```

This will store the alias in your config, under the `startup` key. To edit the saved alias, run it again with the same name, or edit your config file directly. You can find the location of the file using `config path`.

For example, to edit your config file in `vi`, run:
```shell
> vi $(config path)
```
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00			`# alias`
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
docs: add alias --save flag (#1874) 2020-05-24 19:42:20 +02:00			This command allows you to define shortcuts for other common commands. By default, they only apply to the current session. To persist them, add `--save`.

			Syntax: `alias {flags} <name> [<parameters>] {<body>}`
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00
			`The command expects three parameters:`
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
docs/alias: simplify the 'persistent' section, using --save (#2285) All the workarounds using `config` aren't necessary anymore. Only `config path` is still of interest. 2020-08-01 14:11:26 +02:00			`* The name of the alias`
Make all bullet point items uppercase (#2257) 2020-07-25 20:15:12 +02:00			* The parameters as a space-separated list (`[a b ...]`), can be empty (`[]`)
			* The body of the alias as a `{...}` block
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00
docs: add alias --save flag (#1874) 2020-05-24 19:42:20 +02:00			`## Flags`

update config documentation (#2178) * update config documentation * update config syntax * update config syntax * Update alias.md Co-authored-by: Jonathan Turner <jonathandturner@users.noreply.github.com> 2020-07-22 23:42:04 +02:00			* `-s`, `--save`: Save the alias to your config (see `config path` to edit them later)
docs: add alias --save flag (#1874) 2020-05-24 19:42:20 +02:00
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00			`## Examples`

			Define a custom `myecho` command as an alias:
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00			```shell
			`> alias myecho [msg] { echo $msg }`
			`> myecho "hello world"`
			`hello world`
			```

			`Since the parameters are well defined, calling the command with the wrong number of parameters will fail properly:`
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00			```shell
			`> myecho hello world`
			`error: myecho unexpected world`
			`- shell:1:18`
			`1 \| myecho hello world`
			`\| ^^^^^ unexpected argument (try myecho -h)`
			```

			`The suggested help command works!`
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00			```shell
			`> myecho -h`

			`Usage:`
			`> myecho ($msg) {flags}`

			`parameters:`
			`($msg)`

			`flags:`
			`-h, --help: Display this help message`
			```

			`## Persistent aliases`

docs/alias: simplify the 'persistent' section, using --save (#2285) All the workarounds using `config` aren't necessary anymore. Only `config path` is still of interest. 2020-08-01 14:11:26 +02:00			Aliases are most useful when they are persistent. For that, use the `--save` flag:
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
			```shell
docs/alias: simplify the 'persistent' section, using --save (#2285) All the workarounds using `config` aren't necessary anymore. Only `config path` is still of interest. 2020-08-01 14:11:26 +02:00			`> alias --save myecho [msg] { echo $msg }`
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00			```
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
docs/alias: simplify the 'persistent' section, using --save (#2285) All the workarounds using `config` aren't necessary anymore. Only `config path` is still of interest. 2020-08-01 14:11:26 +02:00			This will store the alias in your config, under the `startup` key. To edit the saved alias, run it again with the same name, or edit your config file directly. You can find the location of the file using `config path`.
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00
docs/alias: simplify the 'persistent' section, using --save (#2285) All the workarounds using `config` aren't necessary anymore. Only `config path` is still of interest. 2020-08-01 14:11:26 +02:00			For example, to edit your config file in `vi`, run:
First pass at updating all documentation formatting and cleaning up output of examples (#2031) 2020-06-23 20:21:47 +02:00			```shell
docs/alias: simplify the 'persistent' section, using --save (#2285) All the workarounds using `config` aren't necessary anymore. Only `config path` is still of interest. 2020-08-01 14:11:26 +02:00			`> vi $(config path)`
docs/commands: add alias.md (#1697) * docs/commands: add alias.md * docs/commands/alias: drop reference to bash 2020-05-03 06:49:27 +02:00			```