Skip to content

Shortcuts, Aliases, and Macros

Shortcuts

Command shortcuts for long command names and common commands can be more convenient for your users. Shortcuts are used without a space separating them from their arguments, like !ls. By default, the following shortcuts are defined:

  • ? - help
  • ! - shell: run as OS-level command
  • @ - run script file
  • @@ - run script file; filename is relative to current script location

To define more shortcuts, start with the cmd2.DEFAULT_SHORTCUTS constant, which is a dictionary, and then add more shortcuts to it by updating it with a dictionary of additional shortcuts in the format {'shortcut': 'command_name'} where you omit do_ from the command name:

class App(Cmd):
    def __init__(self):
        shortcuts = cmd2.DEFAULT_SHORTCUTS
        shortcuts.update({'*': 'sneeze', '~': 'squirm'})
        cmd2.Cmd.__init__(self, shortcuts=shortcuts)

Warning

Shortcuts need to be created by updating the shortcuts dictionary attribute before calling the cmd2.Cmd super class __init__() method. Moreover, that super class init method needs to be called after updating the shortcuts attribute.

This warning applies in general to many other attributes which are not settable at runtime.

Note

Command, alias, and macro names cannot start with a shortcut

Aliases

In addition to shortcuts, cmd2 provides an alias feature via the alias command. Aliases work like aliases in the Bash shell.

The syntax to create an alias is: alias create name command [args], e.g. alias create ls !ls -lF.

Redirectors and pipes should be quoted in the alias definition to prevent the alias create command from being redirected:

alias create save_results print_results ">" out.txt

Tab completion recognizes an alias, and completes as if the aliased command was on the command line.

For more details run: help alias create

Use alias list to see all or some of your aliases. The output of this command displays your aliases in a format that can be used to create them. Therefore you can place this output in a cmd2 startup script to recreate your aliases each time you start the application

Ex: alias list

For more details run: help alias list

Use alias delete to remove aliases

For more details run: help alias delete

Note

Aliases cannot have the same name as a command or macro

Macros

cmd2 provides a feature that is similar to aliases called macros. The major difference between macros and aliases is that macros can contain argument placeholders. Arguments are expressed when creating a macro using {#} notation, where {1} means the first argument.

The following creates a macro called my_macro that expects two arguments:

macro create my_macro make_dinner -meat {1} -veggie {2}

When the macro is called, the provided arguments are substituted and the assembled command is run. For example:

my_macro beef broccoli ---> make_dinner -meat beef -veggie broccoli

Similar to aliases, pipes and redirectors need to be quoted in the definition of a macro:

macro create lc !cat "{1}" "|" less

To use the literal string {1} in your command, escape it this way: {{1}}.

Since macros don't resolve until after you press <Enter>, their arguments tab complete as paths. You can change this default behavior by overriding Cmd.macro_arg_complete() to implement custom tab completion for macro arguments.

For more details run: help macro create

The macro command has list and delete subcommands that function identically to the alias subcommands of the same name. Like aliases, macros can be created via a cmd2 startup script to preserve them across application sessions.

For more details on listing macros run: help macro list

For more details on deleting macros run: help macro delete

Note

Macros cannot have the same name as a command or alias