Built-in Aliases

This page describes the xonsh built-in commands and aliases.

cd

Changes the directory. If no directory is specified (i.e. if there are no arguments) then this changes to the current user’s home directory.

pushd

Adds a directory to the top of the directory stack, or rotates the stack, making the new top of the stack the current working directory.

usage: pushd [-h] [-n] [-q] [+N|-N|dir]

Adds a directory to the top of the directory stack, or rotates the stack,
making the new top of the stack the current working directory.

On Windows, if the path is a UNC path (begins with `\\<server>\<share>`) and if the `DisableUNCCheck` registry
value is not enabled, creates a temporary mapped drive letter and sets the working directory there, emulating
behavior of `PUSHD` in `CMD.EXE`

positional arguments:
  +N|-N|dir    * dir :
                   Makes dir be the top of the stack,
                   making it the new current directory as if it had been supplied as an argument to the cd builtin.
               * +N :
                   Brings the Nth directory (counting from the left of the list printed by dirs, starting with zero)
                   to the top of the list by rotating the stack.
               * -N :
                   Brings the Nth directory (counting from the right of the list printed by dirs, starting with zero)
                   to the top of the list by rotating the stack.

optional arguments:
  -h, --help   show this help message and exit
  -n, --cd     Suppresses the normal change of directory when adding directories to the stack,
               so that only the stack is manipulated.
  -q, --quiet  Do not call dirs, regardless of $PUSHD_SILENT

popd

Removes entries from the directory stack.

usage: popd [-h] [-n] [-q] [+N|-N]

When no arguments are given, popd removes the top directory from the stack
and performs a cd to the new top directory.
The elements are numbered from 0 starting at the first directory listed with ``dirs``;
that is, popd is equivalent to popd +0.

positional arguments:
  +N|-N        Removes the Nth directory (counting from the left/right of the list printed by dirs w.r.t. -/+ prefix),
               starting with zero.

optional arguments:
  -h, --help   show this help message and exit
  -n, --cd     Suppresses the normal change of directory when removing directories from the stack,
               so that only the stack is manipulated.
  -q, --quiet  Do not call dirs, regardless of $PUSHD_SILENT

dirs

Displays the list of currently remembered directories. Can also be used to clear the directory stack.

usage: dirs [-h] [-c] [-p] [-v] [-l] [N]

Manage the list of currently remembered directories.

positional arguments:
  N           Displays the Nth directory (counting from the left/right according to +/x prefix respectively),
              starting with zero

optional arguments:
  -h, --help  show this help message and exit
  -c          Clears the directory stack by deleting all of the entries.
  -p          Print the directory stack with one entry per line.
  -v          Print the directory stack with one entry per line,
              prefixing each entry with its index in the stack.
  -l          Produces a longer listing; the default listing format
              uses a tilde to denote the home directory.

jobs

Display a list of all current jobs.

fg

Bring the currently active job to the foreground, or, if a single number is given as an argument, bring that job to the foreground.

bg

Resume execution of the currently active job in the background, or, if a single number is given as an argument, resume that job in the background.

disown

The behavior of this command matches the behavior of zsh’s disown command which is as follows:

Remove the specified jobs from the job table; the shell will no longer report their status, and will not complain if you try to exit an interactive shell with them running or stopped. If no job is specified, disown the current job. If the jobs are currently stopped and the $AUTO_CONTINUE option is set ($AUTO_CONTINUE = True), a warning is printed containing information about how to make them running after they have been disowned. If one of the latter two forms is used, the jobs will automatically be made running, independent of the setting of the $AUTO_CONTINUE option.

EOF, exit, and quit

The commands EOF, exit, and quit all alias the same action, which is to leave xonsh in a safe manner. Typing Crtl-d is the same as typing EOF and pressing enter.

exec and xexec

usage: xexec [-h] [-l] [-c] [-a NAME] ...

exec (also aliased as xexec) uses the os.execvpe() function to
replace the xonsh process with the specified program.

This provides the functionality of the bash 'exec' builtin::

    >>> exec bash -l -i
    bash $

positional arguments:
  command               program to launch along its arguments

optional arguments:
  -h, --help            show this help message and exit
  -l, --login           the shell places a dash at the
                        beginning of the zeroth argument passed to command to simulate login
                        shell.
  -c, --clean           causes command to be executed with an empty environment.
  -a NAME, --name NAME  the shell passes name as the zeroth argument
                        to the executed command.

Notes
-----
This command **is not** the same as the Python builtin function
exec(). That function is for running Python code. This command,
which shares the same name as the sh-lang statement, is for launching
a command directly in the same process. In the event of a name conflict,
please use the xexec command directly or dive into subprocess mode
explicitly with ![exec command]. For more details, please see
http://xon.sh/faq.html#exec.

source

Executes the contents of the provided files in the current context. This, of course, only works on xonsh and Python files.

source-bash

Like the source command but for Bash files. This is a thin wrapper around the source-foreign alias where the shell argument is automatically set to bash.

source-zsh

Like the source command but for ZSH files. This is a thin wrapper around the source-foreign alias where the shell argument is automatically set to zsh.

source-foreign

Like the source command but for files in foreign (non-xonsh) languages. It will pick up the environment and any aliases.

usage: source-foreign [-h] [-n] [-l] [--envcmd ENVCMD] [--aliascmd ALIASCMD] [--extra-args EXTRA_ARGS]
                      [-u] [-p PREVCMD] [--postcmd POSTCMD] [--funcscmd FUNCSCMD] [--sourcer SOURCER]
                      [--use-tmpfile] [--seterrprevcmd SETERRPREVCMD] [--seterrpostcmd SETERRPOSTCMD]
                      [--overwrite-aliases] [--suppress-skip-message] [--show] [-d]
                      shell files_or_code [files_or_code ...]

Sources a file written in a foreign shell language.

positional arguments:
  shell                 Name or path to the foreign shell
  files_or_code         file paths to source or code in the target language.

optional arguments:
  -h, --help            show this help message and exit
  -n, --non-interactive
                        whether the sourced shell should be interactive
  -l, --login           whether the sourced shell should be login
  --envcmd ENVCMD       command to print environment
  --aliascmd ALIASCMD   command to print aliases
  --extra-args EXTRA_ARGS
                        extra arguments needed to run the shell
  -u, --unsafe          whether the source shell should be run safely, and not raise any errors, even if they occur.
  -p PREVCMD, --prevcmd PREVCMD
                        command(s) to run before any other commands, replaces traditional source.
  --postcmd POSTCMD     command(s) to run after all other commands
  --funcscmd FUNCSCMD   code to find locations of all native functions in the shell language.
  --sourcer SOURCER     the source command in the target shell language.
                        If this is not set, a default value will attempt to be
                        looked up based on the shell name.
  --use-tmpfile         whether the commands for source shell should be written to a temporary file.
  --seterrprevcmd SETERRPREVCMD
                        command(s) to set exit-on-error before any other commands.
  --seterrpostcmd SETERRPOSTCMD
                        command(s) to set exit-on-error after all other commands.
  --overwrite-aliases   flag for whether or not sourced aliases should replace the current xonsh aliases.
  --suppress-skip-message
                        flag for whether or not skip messages should be suppressed.
  --show                show the script output.
  -d, --dry-run         Will not actually source the file.

history

Tools for dealing with xonsh history. See the history tutorial for more information all the history command and all of its sub-commands.

usage: history [-h] {show,id,file,info,flush,off,on,clear,gc,transfer,diff} ...

Try 'history <command> --help' for more info

optional arguments:
  -h, --help            show this help message and exit

commands:
  {show,id,file,info,flush,off,on,clear,gc,transfer,diff}
    show                Display history of a session, default command
    id                  Display the current session id
    file                Display the current history filename
    info                Display information about the current history
    flush               Flush the current history to disk
    off                 History will not be saved for this session
    on                  History will be saved for the rest of the session (default)
    clear               One-time wipe of session history
    gc                  Launches a new history garbage collector
    transfer            Transfer entries between history backends.
    diff                Diff two xonsh history files

timeit

Runs timing study on arguments. Similar to IPython’s %timeit magic.

scp-resume

Simple alias defined as ['rsync', '--partial', '-h', '--progress', '--rsh=ssh'].

showcmd

Displays how commands and arguments are evaluated.

ipynb

Simple alias defined as ['ipython', 'notebook', '--no-browser'].

trace

Provides an interface to printing lines of source code prior to their execution.

usage: trace [-h] {on,start,add,off,stop,del,rm,color,ls} ...

Tool for tracing xonsh code as it runs.

optional arguments:
  -h, --help            show this help message and exit

commands:
  {on,start,add,off,stop,del,rm,color,ls}
    on (start, add)     begins tracing selected files.
    off (stop, del, rm)
                        removes selected files fom tracing.
    color (ls)          output color management for tracer

xpip

Runs the pip package manager for xonsh itself. Useful for installations where xonsh is in an isolated environment (eg conda, homebrew).

In general, use xpip if you’re configuring or adding features to xonsh, and use pip if you’re doing Python development.

xonfig

Manages xonsh configuration information.

usage: xonfig [-h] {info,web,wizard,styles,colors,tutorial} ...

Manage xonsh configuration.

optional arguments:
  -h, --help            show this help message and exit

commands:
  {info,web,wizard,styles,colors,tutorial}
    info                Displays configuration information
    web                 Launch configurator in browser.
    wizard              Launch configurator in terminal
    styles              Prints available xonsh color styles
    colors              Preview color style
    tutorial            Launch tutorial in browser.

Windows cmd Aliases

The following aliases on Windows are expanded to ['cmd', '/c', alias]:

{'cls': ['cmd', '/c', 'cls'],
 'copy': ['cmd', '/c', 'copy'],
 'del': ['cmd', '/c', 'del'],
 'dir': ['cmd', '/c', 'dir'],
 'erase': ['cmd', '/c', 'erase'],
 'md': ['cmd', '/c', 'md'],
 'mkdir': ['cmd', '/c', 'mkdir'],
 'mklink': ['cmd', '/c', 'mklink'],
 'move': ['cmd', '/c', 'move'],
 'rd': ['cmd', '/c', 'rd'],
 'ren': ['cmd', '/c', 'ren'],
 'rename': ['cmd', '/c', 'rename'],
 'rmdir': ['cmd', '/c', 'rmdir'],
 'time': ['cmd', '/c', 'time'],
 'type': ['cmd', '/c', 'type'],
 'vol': ['cmd', '/c', 'vol'],
 }

activate/deactivate on Windows with Anaconda

On Windows with an Anaconda Python distribution, activate and deactivate are aliased to ['source-bat activate'] and ['source-bat deactivate']. This makes it possible to use the same commands to activate/deactivate conda environments as in cmd.exe.

sudo on Windows

On Windows, if no executables named sudo are found, Xonsh adds a sudo alias that poly fills the “run as Admin” behavior with the help of ShellExecuteEx and ctypes. It doesn’t support any actual sudo parameters and just takes the command to run.

ls

The ls command is aliased to ['ls', '--color=auto', '-v'] normally. On Mac OSX it is instead aliased to ['ls', '-G'].

grep

The grep command is aliased to ['grep', '--color=auto'].

xontrib

Manages xonsh extensions. More information is available at Tutorial: Extensions (Xontribs)