Cheat sheet for the xonsh shell with copy-pastable examples. This is a good level of knowledge to start being productive.
If you like the cheatsheet click ⭐ on the repo and tweet about it.
Xonsh is a Python-powered, cross-platform, Unix-gazing shell language and command prompt. The language is a superset of Python 3.6+ with additional shell primitives that you are used to from Bash and IPython. It works on all Python-compatible systems, including Linux, macOS, and Windows. The xonsh shell is developed by a community of 300+ volunteers and the xonsh philosophy based on the principle of cooperation.
If you don't want to learn step by step jump to demo examples.
The "xonsh" word sounds like conch [kɑːntʃ] - a common name of a number of different sea snails or shells (🐚, @). Thus "xonsh" is the reference to the "shell" word that is commonly used to name command shells.
Over time the approach to replace a letter in the words to "x" and pronounce as short /k/ when used with vowels (e.g. "xat" sounds like "cat" [kæt]) became the way to create unique names for xonsh related solutions e.g. xontrib, xonfig, xunter. Adding "x" in the beginning is also the way to create xonsh-related name e.g. xpip.
Fun fact: when you run xonsh on *nix in the home directory the default prompt looks like user@host ~ @ - it's a nice visual metaphor of snail (~) that lives in the conch (@) and the conch is the home for snail.
You can find more visuals around xonsh in xonsh-logo repository.
There are three ways to use xonsh:
-
Simple xonsh install. You can use the system installed Python to install xonsh and dependencies. This is a good option if you don't plan to manage Python versions or virtual environments.
-
Install xonsh with package and environment management system. In this way you can flexibly manage the Python version, dependencies, and virtual environments, but because xonsh is a Python-based shell you have to understand what you're doing and the section below will provide some guidance.
-
Try xonsh without installation. Use xonsh container or the Linux AppImage to run and try xonsh.
-
The best way to install xonsh as core shell. You must read the previous sections before using this.
Most modern operating systems have Python and PyPi (pip) that are preinstalled or that can be installed easily. By installing from PyPi you will get the latest version of the xonsh shell. We highly recommend using the full version of the xonsh PyPi-package with prompt-toolkit on board:
python -m pip install 'xonsh[full]'On any system you can install python and then install xonsh from pip i.e., any_pkg_manager install python && python -m pip install 'xonsh[full]'. This is the preferable way.
If you have python but no pip just install it using ensurepip:
python -m ensurepip --upgrade
pip -VAnother way is to install xonsh from the package manager that is supplied by the operating system. This way is not recommended in operating systems without the rolling release concept the xonsh shell version may be very old (check latest xonsh release or versions of xonsh across platforms) because the average release cycle for the xonsh shell is quarter.
# Not recommended (old version, maybe not full dependencies installed) but possible:
apt install xonsh # Debian/Ubuntu
dnf install xonsh # Fedora
brew install xonsh # OSX
pacman -S xonsh # Arch LinuxXonsh is a Python-based shell, and to run xonsh you must have Python installed. The Python version and its packages can be installed and located anywhere: in the operating system directories, as part of a virtual environment, as part of the user directory, or as a virtual drive created temporarily behind the scenes by the Linux AppImage.
The first thing you have to remember is that when you execute import or any other Python code during a xonsh session, it will be executed in the Python environment that was used to run the current instance of xonsh. Use the xc alias to check the xonsh context.
In other words, you can activate a virtual environment during a xonsh session (using mamba, conda, rye, pyenv, pipx) but the current session will continue to use packages from the environment that was used to run xonsh. And if you want to run xonsh with the packages from the currently activated virtual environment you have to install xonsh in that environment and run it directly. Keep in mind current $PATH and as result which xonsh when running something.
Thus the second thing you should remember is that when you run xonsh in a virtual environment it will try to load xonsh RC files (i.e. ~/.xonshrc) and because the virtual environment is different from the environment you ordinarily use, the loading of the RC file will tend to fail because of the lack of the appropriate set of packages. When you write your ~/.xonshrc it's good practice to check the existing external dependencies before loading them. See also xontrib-rc-awesome and xonsh context alias.
Here is the real life example but mostly created for educational reasons. See the best way to install xonsh in the next section.
You can use Conda (or faster replacement - mamba) with Conda-forge to install and use xonsh.
#
# Install python using brew
#
zsh # Default macOS shell
# Install brew from https://brew.sh/
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python # or `python@3.11`
#
# Install Miniconda from https://docs.conda.io/en/latest/miniconda.html
# (example for Mac, use the link for your platform)
#
cd /tmp
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
chmod +x Miniconda3-latest-MacOSX-arm64.sh
./Miniconda3-latest-MacOSX-arm64.sh
# Add conda init code that was printed to `~/.zshrc` and restart zsh.
# Or run `/Users/username/miniconda3/bin/conda init zsh` to add init to ~/.zshrc and restart zsh.
# After restarting zsh you will see `(base)` in prompt.
# This means that you're in the conda `base` environment.
# Switch to Conda-forge channel
conda config --add channels conda-forge
conda config --set channel_priority strict
conda update --all --yes
# Install xonsh to the `base` environment
conda install xonsh
conda init xonsh # Add init to ~/.xonshrc. You can also add `$CONDA_AUTO_ACTIVATE_BASE='false'` to avoid conda loading at start
which xonsh
# /Users/username/miniconda3/bin/xonsh
# Run xonsh from the `base` environment
xonshHow to work and understand the environments in conda:
# `xpip` is used to install packages to the current xonsh session location (now it's `base` environment)
xpip install ujson
# Example of creating the environment with a certain version of Python
conda search python | grep 3.10
conda create -n "py310" python=3.10 xonsh
conda activate py310
# Now the environment is `py310` but current xonsh session is still in `base` environment
which xonsh
# /Users/username/miniconda3/envs/py310/bin/xonsh
which pip
# /Users/username/miniconda3/envs/py310/bin/pip # pip from `py310`
which xpip
# /Users/username/miniconda3/bin/pip # pip from `base` environment from where xonsh ran
# Run xonsh that installed in `py310` environment from xonsh run in `base` environment
xonsh
conda activate py310
# Now xonsh session is in `py310` environment and the current environment is also `py310`
import ujson
# No module named 'ujson' # YES because ujson was installed in `base` environmentOn Mac we also recommend installing GNU coreutils to use the Linux default tools (i.e. ls, grep):
brew install coreutils
$PATH.append('/opt/homebrew/opt/coreutils/libexec/gnubin') # add to ~/.xonshrcWhich xonsh and which Python used to run the current xonsh session:
import sys
[sys.argv[0], sys.executable]
# ['/opt/homebrew/bin/xonsh', '/opt/homebrew/opt/python@3.11/bin/python3.11']
@(sys.executable) -m site
# Full info about pathsWhich xonsh and which python that will be executed to run new instances depends on the list of directories in $PATH or virtual environment:
$PATH
# ['/home/user/miniconda3/bin', '/opt/homebrew/bin]
[$(ls -la @$(which xonsh)), $(ls -la @$(which python)), $(python -V)]
# ['/home/user/miniconda3/bin/xonsh', '/home/user/miniconda3/bin/python -> python3.11', 'Python 3.11.1']
python -m site
# Full info about pathsThe pipx tool is also good for installing xonsh in case you need a certain Python version:
# Install Python before continuing
pip install pipx
pipx install --python python3.8 xonsh # Here `python3.8` is the path to installed python.
pipx run xonsh
# or add /home/$USER/.local/bin to PATH (/etc/shells) to allow running just the `xonsh` commandWhen xonsh becomes a core shell it's needed to keep python environment with xonsh stable, predictable and independent of any changes in the system. To forget about the cases where manipulations around python and packages break the shell unintended you can install xonsh with xonsh-install.
Note! We do not recommend to use xonsh as a default login shell if you are not feel you strong and experienced. Because of most tools are waiting that login shell is POSIX-compliant you can face with issues when some tool is trying to run sh commands in xonsh.
Using open source Podman is recommended but docker also ok.
# Container with specific Python version and latest release of xonsh
podman run --rm -it python:3.11-slim /bin/bash \
-c "pip install 'xonsh[full]' && xonsh"
# Container with specific Python version and xonsh from the master branch
podman run --rm -it python:3.11-slim /bin/bash \
-c "apt update && apt install -y git && pip install -U git+https://github.com/xonsh/xonsh && xonsh"
# Official xonsh container image may have an old version
podman run --rm -it xonsh/xonsh:slimLinux-portable AppImage contains both Python 3 and xonsh in one file
wget https://github.com/xonsh/xonsh/releases/latest/download/xonsh-x86_64.AppImage -O xonsh
chmod +x xonsh
./xonsh
# Then if you don’t have Python on your host, you can access it from the AppImage by running:
$PATH = [$APPDIR + '/usr/bin'] + $PATH
python -m pip install tqdm --user # the `tqdm` package will be installed to ~/.local/
import tqdmYou can build your own xonsh AppImage with the packages you need in 15 minutes.
The xonsh language is a superset of Python 3 with additional shell support. As a result, you can mix shell commands and Python code as easily as possible. Right off the bat examples:
cd /tmp && ls # shell commands
21 + 21 # python command
for i in range(0, 42): # mix python
echo @(i+1) # and the shell
len($(curl https://xon.sh)) # mix python and the shell
xpip install xontrib-dalias && xontrib load dalias
y = $(@yaml dig +yaml google.com) # convert output into object
y[0]['message']['query_time']
podman exec -it @($(@json podman ps --format json)['ID']) bash
$PATH.append('/tmp') # using environment variables
p'/etc/passwd'.read_text().find('root') # path-string returns Path
# (https://docs.python.org/3/library/pathlib.html)
for line in $(cat /etc/passwd).splitlines(): # read the lines from the output
echo @(line.split(':')[0]) # prepare line on Python and echo
for file in gp`*.*`: # reading the list of files as Path-objects
if file.exists(): # using rich functionality of Path-objects
du -sh @(file) # and pass it to the shell command
import json # python libraries are always at hand
if info := $(podman info --format '{{json .}}'):
print('ContainersRunning:', json.loads(info)['ContainersRunning'])
xpip install xontrib-prompt-bar # xonsh has huge amount of powerful extensions
xontrib load prompt_bar # follow the white rabbit - https://github.com/topics/xontrib
# Finally fork https://github.com/anki-code/xontrib-rc-awesome
# to convert your ~/.xonshrc into a pip-installable package
# with the extensions you need on board.Looks nice? Install xonsh!
The first thing you should remember is that the shell commands are not the calls of another shell (i.e. bash). Xonsh has its own parser implementation for subprocess commands, and this is why a command like echo {1..5} \; (brace expansion and escape characters in bash) won't work. Most sh-shell features can be replaced by sane Python alternatives. For example, the earlier command could be expressed as echo @(range(1,6)) ';'.
If you think that only xonsh has the sh-uncompatible elements in its parser, you are mistaken. If we compare Bash and Zsh we will find that pip install package[subpackage] command will work in Bash but in Zsh the error will be raised because Zsh has a special meaning for square braces. It's normal to have an evolution in the syntax and features.
Be calm and accept the sane and self-consistent Python-driven mindset.
Note:
- Most novices try to copy and paste sh-lang commands that contain special characters and get syntax errors in xonsh. If you want to run environment agnostic sh-lang's commands that you copy from the internet just use the macro call in xonsh
bash -c! echo {123}or use xontrib-sh to run context-free bash commands in xonsh by adding!at the beginning of the command. - We highly recommend to taking a look at the section Install xonsh with package and environment management system.
The second potential misunderstanding comes from the first. Use quotes to escape special characters, the special meaning of braces, or pass a string as an argument. When in doubt, use quotes!
You should clearly understand the difference:
| sh-lang shells | xonsh |
|---|---|
1. Has an escape character:
echo 123\ 456 # 123 456 |
1. Use quotes:
echo "123 456" # 123 456Escape character to wrap and so on: echo "123\ 456" # 123456 |
2. Open the quotes:
echo --arg="val" # --arg=val |
2. Save quotes:
echo --arg="val" # --arg="val" |
3. Brackets have no meaning:
echo {123} [456]
# {123} [456]
|
3. Brackets have meaning:
echo {123} [456]
# SyntaxError
|
Note:
- You can wrap any argument into Python string substitution:
name = 'snail' echo @('--name=' + name.upper()) # --name=SNAIL
- You can use the
showcmdcommand to show the arguments list:showcmd echo The @('args') @(['list', 'is']) $(echo here) "and" --say="hello" to @([]) you # ['echo', 'The', 'args', 'list', 'is', 'here', 'and', '--say="hello"', 'to', 'you']]
3. The process substitution operator $() returns output with universal new lines
In sh-compatible shells, the process substitution operator $() executes the command and then splits the output and uses those parts as arguments. The command echo $(echo -e "1 2\n3") will have three distinct arguments, 1, 2 and 3 that will passed to the first echo.
In xonsh shell the $() operator is smarter (xonsh >= 0.17.0):
- Return the line if it's single line e.g.
$(whoami)will return'user'. - Return universal new lines for multiple lines e.g.
$(ls)will return'1\n2\n3\n'. - Finally you can use xontrib-dalias to have a list of lines e.g.
l = $(@lines cat file).
Note:
- To do what sh-compatible shells are doing with the
$()operator, the xonsh shell has the@$()operator that will be described in the next chapter.showcmd echo @$(echo "1\n2 3\n4") # ['echo', '1', '2', '3', '4']
- To transform the output you can use python substitution e.g. use splitlines:
showcmd echo @($(echo "1\n2 3\n4").splitlines()) # the first echo will get three arguments: "1", "2 3", "4" # ['echo', '1', '2 3', '4']
Xonsh runs subprocess commands or callable aliases using threading prediction mechanism that simply called "threading" or "(un)threadable" words. This threading prediction was introduced to have an ability to capture any output from processes that are completely non interactive e.g. echo or grep. When you run !(echo 1) the echo process will be predicted as thredable and current terminal will be detached and stdout, stderr and everything will be captured.
The threading prediction mechanism:
- It requires the clear understanding of how it works from the developer who want to use capturable operators with complex tasks.
- It has edge cases and some expectations can't be realised without improving the xonsh core logic - it's mostly related to mixing callable aliases with subprocess command.
In the nuthesll when you try to run unthredable and uncapturable process (e.g. vim, ssh) in complex callable allias you can face with that callable alias is thredable by default and wrapping interactive tools into it ledas to cases where you need to have ninja knowledge about how it works in the xonsh core. If you have no this knowledge you will have stuck output as well as freezed and suspended processes at the end. But in more simpler cases it's needed to just add @unthredable to callable alias or change the operator from capturable to uncapturable.
The xonsh core team want to rid of threading prediction in the future but it's not so trivial task that requires to understand more about process management.
Finally here is the way of how to predict threading:
__xonsh__.commands_cache.predict_threadable(['echo'])
# True
__xonsh__.commands_cache.predict_threadable(['ssh'])
# FalseHow to change the predicted value using @thread and @unthread aliases you can find below :)
Operators:
-
$()is to run processes and capture the stdout. Almost the same as in traditional shells. -
!()is to run sync or async threadable (capturable) processes. The terminal is detached for the process in this mode to deliver non-blocking behavior. To block the process and wait for result use.end(),.out,.rtnand other attributes that forces getting the result. -
![]is to run processes without any capturing but return CommandPipeline with base info: pid, return code, timinig, etc. This operator is working when you run plain commands e.g. justecho hello. -
$[]is to run processes without any capturing and any catching the result. Use it for uncapturable processes (e.g.vim) if you want to stream output directly to the terminal and without any capturing.
Examples:
id $(whoami) # xonsh >= 0.17.0
worker1 = !(sleep 3) # Non-blocking.
echo 'Something is happening while worker1 is working.'
if worker1.rtn == 0: # Blocking. The `.rtn` attribute call has `.end()` under the hood.
echo 'worker1 is done'
# Note. There is issue with this case that will be fixed in xonsh > 0.19.0.
file = p'~/.xonshrc'
if ![ls @(file)]:
head @(file)
$[vim ~/.xonshrc]From tech side (most of the behavior is dictated by OS):
| Operator | $() |
!() |
![] |
$[] |
|---|---|---|---|---|
| Blocking | yes | no | yes | yes |
| Capture stdout | yes | yes for threadable | no | strict no |
| Capture stderr | no | yes for threadable | no | strict no |
| Attach TTY input | yes | no | yes | yes |
| Attach TTY output | no for threadable | no for threadable | no for threadable | yes |
| Return | stdout | CommandPipeline | HiddenCommandPipeline | None |
Here:
- Threadable (capturable) process is the process without any interaction with user. Note that if unthreadable process will run with detached terminal it will be suspended by OS automatically.
- Capturing "strict no" means that stream will be passed to the main terminal from any place of calling.
Note:
- If you want to run interactive xonsh from bash script you need to have interactive shebang (i.e.
#!/bin/bash -i) to avoid suspending by OS.
Technical name of this operator: captured stdout. Python call: __xonsh__.subproc_captured_stdout().
Captures stdout and returns single line or miltiline output with universal new lines:
# xonsh >= 0.17.0
$(whoami) # Python mode
# 'user'
id $(whoami) # Subproc mode
# uid=501(user) gid=20(staff)
showcmd $(echo -e '1\n2\r3 4\r\n5') # Subproc mode
# ['1\n2\n3 4\n5\n']
output = $(echo -e '1\n2\r3 4\r\n5') # Python mode
output
# '1\n2\n3 4\n5\n'You can change the behavior by setting $XONSH_SUBPROC_OUTPUT_FORMAT (xonsh >= 0.17.0):
$XONSH_SUBPROC_OUTPUT_FORMAT = 'list_lines'
$(ls /)
# ['/bin', '/etc', '/home']Technical name of this operator: captured object or full capturing with non blocking mode. Python call: __xonsh__.subproc_captured_object()
Captures stdout and returns CommandPipeline. Truthy if successful (returncode == 0), compares to, iterates over lines of stdout:
ret = !(echo 123)
ret
#CommandPipeline(
# pid=404136,
# returncode=0,
# args=['echo', '123'],
# alias=None,
# timestamps=[1604742882.1826484, 1604742885.1393967],
# executed_cmd=['echo', '123'],
# input='',
# output='123\n',
# errors=None
#)
if ret:
print('Success')
#Success
for l in ret:
print(l)
#123
#Note! This is non blocking operator: no waiting for enging output. To get the output you need to convert an object to a string, invoke .end(), ask for .rtn or use the .out to force ending the process and read output from internal buffers:
r = !(ls /)
r.output
# ''
r.end()
r.output
# 'bin\netc\n...'
r = !(ls /)
r.out # out is forcing ending
# 'bin\netc\n...'
r = !(ls /)
print(r) # r will be converted to str and the ending will be forced
# bin
# etc
# ...Note! When you're using full capturing the stdout and stderr will be captured and there will be no terminal (tty) connected. You can use this operator only for non interactive tools running. If you will do !(ls | fzf) or !(python -c "input()") the executed command will be suspended by POSIX OS (1, 2) because the process is waiting for input in background. Use uncaptured operators for interactive tools and read the futher materials around unthreadable mode to do things right.
Technical name of this operator: uncaptured mode. Python call: __xonsh__.subproc_uncaptured().
Passes stdout to the screen and returns None:
ret = $[echo 123]
# 123
repr(ret)
# 'None'This is the same as echo 123, but this syntax allows explicitly running a subprocess command.
![] - print stdout/stderr and return hidden object
Technical name of this operator: uncaptured hidden object. Python call: __xonsh__.subproc_captured_hiddenobject()
Note! The behavior may be different if $XONSH_CAPTURE_ALWAYS is True or False (default).
Passes stdout to the screen and returns HiddenCommandPipeline:
with __xonsh__.env.swap(XONSH_CAPTURE_ALWAYS=False): # Default.
r = ![echo -e '1\n2\r3 4\r\n5']
# 1 # Stream output of the command
# 3 4
# 5
r # No return value because it's HiddenCommandPipeline object
r.out
# '' # Empty because `$XONSH_CAPTURE_ALWAYS = False`.
r.returncode
# 0
with __xonsh__.env.swap(XONSH_CAPTURE_ALWAYS=True):
r = ![echo -e '1\n2\r3 4\r\n5']
# 1 # Stream output of the command
# 3 4
# 5
r # No return value because it's HiddenCommandPipeline object
r.out # But it has the properties from CommandPipeline
# '1\n2\r3 4\n5\n'
r.returncode
# 0Elegant checking the result of the command using walrus operator:
if r := ![ls NO]:
print(f'It works! Return code: {r.returncode}')
else:
print(f'It fails! Return code: {r.returncode}')
# ls: cannot access 'NO': No such file or directory
# It fails! Return code: 2This operator is used under the hood for running commands at the interactive xonsh prompt.
Evaluates Python and passes the arguments:
showcmd 'Supported:' @('string') @(['list','of','strings'])
#['Supported:', 'string', 'list', 'of', 'strings']
echo -n '!' | @(lambda args, stdin: 'Callable' + stdin.read())
#Callable!Technical name: captured inject output. API call: __xonsh__.subproc_captured_inject()
showcmd @$(echo -e '1\n2\r3 4\r\n5')
#['1', '2\r3', '4', '5']This is mostly what bash's $() operator does.
Three ways to get environment:
${...} # Get the list of environment variables.
# Get the list of environment variables using Python syntax:
__xonsh__.env # Get the list of environment variables using builtin reference to xonsh session (__xonsh__)
# Recommended for Python code and xontribs:
from xonsh.built_ins import XSH # Import current xonsh session.
XSH.env # Get the list of environment variables using xonsh session (XSH).Operating with environment variables:
$VAR = 'value' # Set environment variable
ENV = ${...} # short typing
ENV.get('VAR', 'novalue') # the good practice to have a fallback for missing value
# 'value'
ENV.get('VAR2', 'novalue') # the good practice to have a fallback for missing value
# 'novalue'
'VAR' in ENV # Check environment variable exists
#True
${'V' + 'AR'} # Get environment variable value by name from expression
#'value'
print($VAR)
with ${...}.swap(VAR='another value', NEW_VAR='new value'): # Change VAR for commands block
print($VAR)
print($VAR)
#value
#another value
#value
$VAR='new value' xonsh -c r'echo $VAR' # Change variable for subprocess command
#new value
__xonsh__.env.get('VAR', 'novalue') # the way to call environment using the __xonsh__ builtin
# 'value'Python and subprocess mode:
print("my home is $HOME") # Python mode
# my home is $HOME
print("my home is " + $HOME) # Python mode
# my home is /home/snail
echo "my home is $HOME" as well as '$HOME' # Subprocess mode
# my home is /home/snail as well as /home/snailWork with $PATH:
$PATH
# EnvPath(
# ['/usr/bin',
# '/sbin',
# '/bin']
# )
$PATH.append('/tmp') # Append path '/tmp' at end of $PATH list
$PATH.prepend('/tmp') # (xonsh>0.15.1) Insert path '/tmp' at front of $PATH list
$PATH.insert(0, '/tmp') # Insert path '/tmp' to appropriate position of $PATH list
$PATH.remove('/tmp') # Remove path '/tmp' (first match)
$PATH.add(p"~/bin", front=True, replace=True)) # Insert path '~/bin' at front of $PATH list and replace existing entries
$PATH.add(p"~/bin", front=True) # Insert path '~/bin' at front of $PATH list
$PATH.add(p"~/bin", front=False, replace=True)) # Insert path '~/bin' at end of $PATH list and replace existing entriesNote! Starting from xonsh 0.15.2 the logic was improved.
Setup local paths by prepending to path via a loop in .xonshrc:
import os.path
from os import path
$user_bins = [
f'{$HOME}/.cargo/bin',
f'{$HOME}/.pyenv/bin',
f'{$HOME}/.poetry/bin',
f'{$HOME}/bin',
f'{$HOME}/local/bin',
f'{$HOME}/.local/bin',
]
for dir in $user_bins:
if path.isdir(dir) and path.exists(dir):
$PATH.add(dir,front=True, replace=True)See also the list of xonsh default environment variables.
aliases['g'] = 'git status -sb' # Add alias as string
aliases['e'] = 'echo @(2+2)' # Add xonsh executable alias (ExecAlias)
aliases['gp'] = ['git', 'pull'] # Add alias as list of arguments
aliases['b'] = lambda: "Banana!\n" # Add alias as simple callable lambda
aliases |= {'a': 'echo a', 'b':'echo b'} # Add aliases from the dict
del aliases['b'] # Delete aliasEasy wrapping a command by using ExecAlias with built-in $args (or $arg0, $arg1, etc) variable:
aliases['echo-new'] = "echo @($args) new"
$(echo-new hello)
# 'hello new\n'
$(echo-new -n hello)
# 'hello new'Easy switch environment using alias:
aliases['lines'] = "$XONSH_SUBPROC_OUTPUT_FORMAT = 'list_lines'; echo $XONSH_SUBPROC_OUTPUT_FORMAT"
aliases['stream'] = "$XONSH_SUBPROC_OUTPUT_FORMAT = 'stream_lines'; echo $XONSH_SUBPROC_OUTPUT_FORMAT"
lines
# list_lines
$(ls)
# ['file1', 'file2', 'file3']
stream
# stream_lines
$(ls)
# 'file1\nfile2\nfile3\n'Also with handy """-string to use " and ' without escaping:
aliases['scmd'] = """showcmd @([a for a in $args if a != "cutme"])"""
scmd
# usage: showcmd [-h|--help|cmd args]
# Displays the command and arguments as a list ...
scmd 1 2 cutme 3
#['1', '2', '3']Ordinarily "alias" word refers to a subprogram that has exit code and arguments for subprocess mode. In xonsh you can group commands and reuse it as Python functions or classes:
def hello(name):
echo hello @(name)
hello('Alex')
# hello Alexor class:
class my:
@classmethod
def hello(cls, name):
echo hello @(name)
my.hello('Alex')
# hello AlexIf you need to transform command use @aliases.return_command:
@aliases.register
@aliases.return_command
def _xsudo(args):
"""Sudo with expanding aliases."""
return ['sudo', '--', *aliases.eval_alias(args)]
aliases['install'] = "apt install cowsay"
xsudo install
# Password:
# Install cowsay
@aliases.register
@aliases.return_command
def _vi(args):
"""Universal vi editor."""
if $(which vim 2>/dev/null):
return ['vim'] + args
else:
return ['vi'] + args
vi /etc/hostsNote! Using alias that returns command is much more preferable than callable alias if you need to just change the command. Callable alias is a complex process wrapper and in case of choice between return command alias and callable alias the right choice is the first one.
def _myargs1(args):
#def _myargs2(args, stdin=None):
#def _myargs3(args, stdin=None, stdout=None):
#def _myargs4(args, stdin=None, stdout=None, stderr=None):
#def _myargs5(args, stdin=None, stdout=None, stderr=None, spec=None):
#def _myargs6(args, stdin=None, stdout=None, stderr=None, spec=None, stack=None):
print(args)
# print(args, file=stdout) # Using stdout directly is the best practice to support pipes/tests/future.
aliases['args'] = _myargs1
del _myargs1
args 1 2 3
#['1', '2', '3']Simple definition with decorator:
@aliases.register
def _hello():
echo world
hello
# worldRead stdin and write to stdout (real-life example - xontrib-pipeliner):
# Add an exclamation point to each line
def _exc(args, stdin, stdout):
for line in stdin.readlines():
print(line.strip() + '!', file=stdout, flush=True)
aliases['exc'] = _exc
echo hello | exc
# hello!# JSON to YAML
@aliases.register("j2y")
def __j2y(args, stdin, stdout):
import json, yaml
print(yaml.dump(json.loads(stdin.read())), file=stdout)
# YAML to JSON
@aliases.register("y2j")
def __y2j(args, stdin, stdout):
import yaml, json
json.dump(yaml.safe_load(stdin), stdout, indent=4)
echo '{"hello":{"world":"42"}}' | j2y
# hello:
# world: 42
echo 'hello:\n world: 42' | y2j
# {
# "hello": {
# "world": "42"
# }
# }Capturing:
Callable aliases tend to be capturable. Only the explicitly denoted uncaptured subprocess operator $[] is uncapturable, and the subprocess's stdout passes directly through xonsh to the screen.
@aliases.register
def _hunter():
print('catch me')
echo if
$[echo you]
![echo can]
hunter
# catch me
# if
# you
# can
$(hunter)
# you
# 'catch me\nif\ncan\n'Calambur! The "callable alias" could be shortanized to "callias". The name Callias is primarily a gender-neutral name of Greek origin that means Beauty.
Using DecoratorAlias and callable output_format you can create transformer:
from xonsh.procs.specs import SpecAttrDecoratorAlias as dalias # xonsh >= 0.18.0
imp = type('ImpCl', (object,), {'__getattr__':lambda self, name: __import__(name) })()
aliases['@noerr'] = dalias({"raise_subproc_error": False},
"Set `raise_subproc_error` to False.")
aliases['@lines'] = dalias({"output_format": 'list_lines'},
"Set `list_lines` output format.")
aliases['@json'] = dalias({"output_format": lambda lines: imp.json.loads('\n'.join(lines))},
"Set `json` output format.")
aliases['@path'] = dalias({"output_format": lambda lines: imp.pathlib.Path(':'.join(lines))},
"Set `path` output format.")
aliases['@yaml'] = dalias({"output_format": lambda lines: imp.yaml.safe_load('\n'.join(lines))},
"Set `yaml` output format.")Now you can:
$(@lines ls /)
# ['/bin', '/etc', '/home']
$(@json echo '{"a":1}') # Try with `curl` ;)
# dict({"a":1})
$(@path which xonsh)
# Path('/path/to/xonsh')
$(@path which xonsh).parent
# Path('/path/to')
aliases['ydig'] = '@yaml dig +yaml' # Update `dig` via `brew install bind` to have `+yaml`.
y = $(ydig google.com)
y[0]['type']
# 'MESSAGE'
$RAISE_SUBPROC_ERROR = True
if ![@noerr ls nononofile]: # Do not raise exception in case of error.
echo file See also xontrib-dalias.
There is xontrib-abbrevs as an alternative to aliases. You can create abbrev and set the position of editing:
xpip install xontrib-abbrevs
xontrib load abbrevs
abbrevs['gst'] = 'git status'
gst # Once you hit <space> or <return> 'gst' gets expanded to 'git status'.
abbrevs['gp'] = "git push <edit> --force" # Set the edit position.
abbrevs['@'] = "@(<edit>)" # Make shortcut.
abbrevs['...'] = "cd ../.." # Workaround for syntax intersections with Python i.e. `elepsis` object from Python here.
# You can set a callback that receives the current command buffer and the word that triggered abbrev
abbrevs['*'] = lambda buffer, word: "asterisk" if buffer.text.startswith('echo') else word
ls * # will stay
echo * # will be transformed to `echo asterisk`The p-string returns Path object:
path = p'~/.xonshrc'
path
# Path('/home/snail/.xonshrc')
[path.name, path.exists(), path.parent]
# ['.xonshrc', True, Path('/home/snail')]
[f for f in path.parent.glob('*') if 'xonsh' in f.name]
# [Path('/home/snail/.xonshrc')]
dir1 = 'hello'
dir2 = 'world'
path = p'/tmp' / dir1 / dir2 / 'from/dir' / f'{dir1}'
path
# Path('/tmp/hello/world/from/dir/hello')The best description of how string literlas is working is in the table from tutorial.
A simple way to read and write the file content using Path string:
text_len = p'/tmp/hello'.write_text('Hello world')
content = p'/tmp/hello'.read_text()
content
# 'Hello world'Globbing - get the list of files from path by mask or regexp
To Normal globbing add g before back quotes:
ls *.*
ls g`*.*`
for f in gp`/tmp/*.*`: # `p` is to return path objects
print(f.name)
for f in gp`/tmp/*/**`: # `**` is to glob subdirectories
print(f)To Regular Expression Globbing add r before back quotes:
ls `.*`
ls r`.*`
for f in rp`.*`: # `p` is to return path instances
print(f.exists())To Custom function globbing add @ and the function name before back quotes:
def foo(s):
return [i for i in os.listdir('.') if i.startswith(s)]
cd /
@foo`bi`
#['bin']def m(x : str):
return x
# No macro calls:
[m('me'), m(42), m(m)]
# ['me', 42, <function __main__.m>]
# Macro calls:
[m!('me'), m!(42), m!(identity), m!(42), m!( 42 ), m!(import os)]
# ["'me'", '42', 'identity', '42', '42', 'import os']
m!(if True:
pass)
# 'if True:\n pass'Real life example:
from_json = lambda cmd: __import__("json").loads(evalx(f"$({cmd})"))
o = from_json!(echo '{"a":1}')
o
#{'a': 1}
type(o)
# dictecho! "Hello!"
# "Hello!"
bash -c! echo "Hello!"
# Hello!
podman run -it --rm xonsh/xonsh:slim xonsh -c! 2+2
# 4Inside of a macro, all additional munging is turned off:
echo $USER
# lou
echo! $USER
# $USERfrom xonsh.contexts import Block
with! Block() as b:
qwe
asd
zxc
b.macro_block
# 'qwe\nasd\nzxc\n\n'
b.lines
# ['qwe', 'asd', 'zxc', '']import json
class JsonBlock:
__xonsh_block__ = str
def __enter__(self):
return json.loads(self.macro_block)
def __exit__(self, *exc):
del self.macro_block, self.macro_globals, self.macro_locals
with! JsonBlock() as j:
{
"Hello": "world!"
}
j['Hello']
# world!The example is from xontrib-macro-lib:
from xonsh.contexts import Block
class Container(Block):
"""Run xonsh codeblock in a container."""
def __init__(self):
self.image = 'xonsh/xonsh:slim'
def __exit__(self, *a, **kw):
$[podman run -it --rm @(self.image) /usr/local/bin/xonsh -c @(self.macro_block)]
with! Container() as d:
pip install lolcat
echo "We're in the container now!" | lolcatSee also xontrib-macro-lib.
completer list # List the active completersTake a look into xontrib-fish-completer - it provides more rich completion than default bash completer.
Create your own completer:
def dummy_completer(prefix, line, begidx, endidx, ctx):
'''
Completes everything with options "lou" and "carcolh",
regardless of the value of prefix.
'''
return {"lou", "carcolh"}
completer add dummy dummy_completer # Add completer: `completer add <NAME> <FUNC>`
# Now press Tab key and you'll get {"lou", "carcolh"} in completions
completer remove dummy
Uncover the power of prompt_toolkit by binding the hotkeys. Run this snippet or add it to ~/.xonshrc:
from prompt_toolkit.keys import Keys
@events.on_ptk_create
def custom_keybindings(bindings, **kw):
# Press F1 and get the list of files
@bindings.add(Keys.F1) # or for Mac try `@bindings.add("c-k") # control+k`
def run_ls(event):
ls -l
event.cli.renderer.erase()
# Press F3 to insert the grep command
@bindings.add(Keys.F3) # or for Mac try `@bindings.add("c-k") # control+k`
def add_grep(event):
event.current_buffer.insert_text('| grep -i ')
# Clear line by pressing `Escape` key
@bindings.add("escape")
def clear_line(event):
event.current_buffer.delete_before_cursor(1000)
See also: more about key bindings, event.current_buffer.
Xontrib - extension or plugin for xonsh
Xontrib lists:
To install xontribs xonsh has xpip - a predefined alias pointing to the pip command associated with the Python executable running this xonsh. Using xpip is the right way to install xontrib to be confident that the xontrib will be installed in the right environment.
If you want to create your own xontrib using xontrib-template is the best way:
xpip install copier jinja2-time cookiecutter
copier copy --trust gh:xonsh/xontrib-template .You can integrate python tools into xonsh context and environment using xontrib e.g. see fstrider xontrib where xontrib allows to inject xonsh context into file system navigation tool.
Real-life example of xsh script that has: arguments, tab completion for arguments (using xontrib-argcomplete), subprocess calls with checking the result, colorizing the result and exit code:
#!/usr/bin/env xonsh
# PYTHON_ARGCOMPLETE_OK
import argparse
import argcomplete # Tab completion support with xontrib-argcomplete
from argcomplete.completers import ChoicesCompleter
$RAISE_SUBPROC_ERROR = True # Raise an error if a subprocess returns a non-zero exit status.
# Read more: https://xon.sh/envvars.html#raise-subproc-error
argp = argparse.ArgumentParser(description=f"Get count of lines in HTML by site address.")
argp.add_argument('--host', required=True, help="Host").completer=ChoicesCompleter(('xon.sh', 'github.com'))
argcomplete.autocomplete(argp)
args = argp.parse_args()
if result := !(curl -s -L @(args.host)): # Python + Subprocess = ♥
lines_count = len(result.out.splitlines())
printx(f'{{GREEN}}Count of lines on {{#00FF00}}{args.host}{{GREEN}}: {{YELLOW}}{lines_count}{{RESET}}')
else:
printx(f'{{RED}}Error while reading {{YELLOW}}{args.host}{{RED}}! {{RESET}}') # Colorizing messages
exit(1) # Exit with code number 1Try it in action:
xonsh
pip install argcomplete xontrib-argcomplete
xontrib load argcomplete
cd /tmp
wget https://raw.githubusercontent.com/anki-code/xonsh-cheatsheet/main/examples/host_lines.xsh
chmod +x host_lines.xsh
./host_lines.xsh --ho<Tab>
./host_lines.xsh --host <Tab>
./host_lines.xsh --host xon.sh
# Count of lines on xon.sh: 568 To make the interaction with scripts more awesome see also xonsh-awesome-cli-app and articles around click, rich, typer, etc.
Get the script path from $ARGS[0]:
echo @("""echo This script is in @(pf"{$ARGS[0]}".parent)""") > /tmp/getpath.xsh
chmod +x /tmp/getpath.xsh
/tmp/getpath.xsh
# This script is in /tmpStart here: How do I write unit tests?.
There are two history backends: json and sqlite which xonsh has by default. The json backend creates a json file with commands history on every xonsh session. The sqlite backend has one file with SQL-database.
We recommend using the sqlite backend because it saves the command on every execution, and querying the history using SQL is very handy, i.e. history-search, history-pull.
echo 123
# 123
__xonsh__.history[-1]
# HistoryEntry(cmd='echo 123', out='123\n', rtn=0, ts=[1614527550.2158427, 1614527550.2382812])
history info
# backend: sqlite
# sessionid: 637e577c-e5c3-4115-a3fd-99026f113464
# filename: /home/user/.local/share/xonsh/xonsh-history.sqlite
# session items: 2
# all items: 8533
# gc options: (100000, 'commands')
sqlite3 $XONSH_HISTORY_FILE "SELECT inp FROM xonsh_history ORDER BY tsb LIMIT 1;"
# echo 123
aliases['history-search'] = """sqlite3 $XONSH_HISTORY_FILE @("SELECT inp FROM xonsh_history WHERE inp LIKE '%" + $arg0 + "%' AND inp NOT LIKE 'history-%' ORDER BY tsb DESC LIMIT 10");"""
cd /tmp
history-search "cd /"
# cd /tmp
history-search! cd / # macro call
# cd /tmp
pip install sqlite_web
sqlite_web $XONSH_HISTORY_FILE # Open the database in the browser
history pull # Pull the history from parallel sessions and add to the current session. [xonsh -V > 0.13.4]There is a third-party history backend that's supplied in xontribs: xontrib-history-encrypt.
When you're in xonsh interactive mode you can register an event, i.e.:
@events.on_chdir
def mychdir(olddir, newdir, **kw):
echo Jump from @(olddir) to @(newdir)
cd /tmp
# Jump from /home/snail to /tmpAdd ? (regular help) or ?? (super help) to the command:
ls?
# man page for ls
import json
json?
# json module help
json??
# json module super helpSometimes when you're using PyPi, Conda, or virtual environments you can forget about the current version and location of Python and try to import packages in xonsh resulting in a ModuleNotFoundError error. Often this means you installed the package in another environment and didn't realise it. To avoid this read the section about xonsh installation above.
In case of name or syntax collision try to use aliases or abbrevs to resolve the conflict.
The case with id or zip:
id
# <function id>
ID
# uid=501(user) gid=20(staff) groups=20(staff) ...
zip
# zip builtin
ZIP
# zip [-options] [-b path] ...
Zip
# zip [-options] [-b path] ...The case with ellipsis:
aliases['...'] = 'cd ../..' # looks nice, but
...
# Elepsis
del aliases['...']
abbrevs['...'] = 'cd ../..'
... # becomes `cd ../..`The case with import:
cd /tmp
$PATH.append('/tmp')
echo 'echo I am import' > import && chmod +x import
import # Run subprocess `./import`
# I am import
import args # Run Python import of `args` module
# ModuleNotFoundError: No module named 'args'
aliases['imp'] = "import"
imp
# I am importIf you want to capture the output from a tool that basically interactive but has captured mode.
For example basically ssh return the remote terminal that should be unthredable and uncapturable.
But if you use it for getting the data from remote host you would like to capture it.
There are three workarounds:
!(@thread ssh host -T "echo 1") # Switch to thread (xonsh >= 0.18.3).
#CommandPipeline(returncode=0, output='1\n')
!(echo 123 | head) # stream to captured
#CommandPipeline(returncode=0, output='123\n')
!(bash -c "echo 123") # wrap to capturable tool
#CommandPipeline(returncode=0, output='123\n')If you run a console tool and get a frozen terminal (Ctrl+c, Ctrl+d is not working), this can be that the tool was interpreted as a threaded and capturable program but the tool actually has interactive elements that expect input from the user. There are bunch of workarounds:
@unthread ./tool.sh # xonsh >= 0.18.3
with ${...}.swap(THREAD_SUBPROCS=False):
./tool.sh
$[./tool.sh]Because of xonsh syntax was based on Python syntax you can face with parser issues if you install the new Python version and run xonsh. Check that you're specifying certain version of Python when you're using xonsh in your projects and there is no situation when python can be updated witout testing.
Start by forking xontrib-rc-awesome.
Use __xonsh__.imp as inline importer (xonsh >= 0.18.2):
__xonsh__.imp.json.loads('{"a":1}')
# {'a': 1}
__xonsh__.imp.datetime.datetime.now().isoformat()
# '2024-02-12T15:29:57.125696'
__xonsh__.imp.hashlib.md5(b'Hello world').hexdigest()
# '3e25960a79dbc69b674cd4ec67a72c62'To avoid escape characters (i.e. echo "\"hello\"") and make strings more elegant use triple quotes:
echo """{"hello":'world'}"""
# {"hello":'world'}Use in subprocess:
echo Hello @(_name := input('Name: ')) # Use `_` to keep env clean.
echo Hello again @(_name)
# Name: Mike
# Hello Mike
# Hello again MikeUse with commands:
(servers := $(@json echo '["srv1", "srv2"]'))
# list(['srv1', 'srv2'])
echo @(servers[0])
# srv1If you realize that your alias becomes the app it's time to look at xonsh-awesome-cli-app.
When you have group of commands (transaction) it's good to use DisableInterrupt from xontrib-macro:
from xontrib.macro.signal import DisableInterrupt
echo start
with! DisableInterrupt():
echo 'sleep start'
sleep 10
echo 'sleep end'
echo finish
# start
# sleep start
# [Press Ctrl+C]
# KeyboardInterrupt will be raised at the end of current transaction.
# sleep end
# Exception KeyboardInterrupt: KeyboardInterrupt was received during transaction.The first way is to use multiline strings:
echo @("""
line 1
line 2
line 3
""".strip()) > file.txt
$(cat file.txt)
# 'line 1\nline 2\nline 3\n'The second way is to use xonsh macro block via xontrib-macro:
xpip install xontrib-macro
from xontrib.macro.data import Write
with! Write('/tmp/t/hello.xsh', chmod=0o700, replace=True, makedir=True, verbose=True):
echo world
/tmp/t/hello.xsh
# worldRun commands in a container:
podman run -it --rm xonsh/xonsh:slim xonsh -c @("""
pip install --disable-pip-version-check -q lolcat
echo "We're in the podman container now!" | lolcat
""")Don't forget that Alt+Enter can run the command from any place where the cursor is.
In python there is input function but it has no support of multiline pasting. Use prompt:
from prompt_toolkit import prompt
echo @(prompt('Content:\n')) > /tmp/myfile
# Content:
# <Paste multiline text "1\n\2\n" from clipboard>
cat /tmp/myfile
# 1
# 2One line version using inline importer (__xonsh__.imp):
echo @(__xonsh__.imp.prompt_toolkit.prompt("Content:\n")) > /tmp/myfile@aliases.register(",")
@aliases.register(",,")
@aliases.register(",,,")
@aliases.register(",,,,")
def _superdot():
cd @("../" * len($__ALIAS_NAME))
, # cd ../
,, # cd ../../
,,, # cd ../../../For example, you want to have the current timestamp in every command but instead of nesting like @(dt()) you want sugar:
class TimestampCl:
def __repr__(self):
from datetime import datetime
return str(datetime.now().isoformat())
$dt = TimestampCl()
echo $dt
sleep 1
echo $dt
# 2024-03-05T23:34:50.188014
# 2024-03-05T23:34:51.259861If you want more sugar use imp from the previous trick:
imp = type('ImpCl', (object,), {'__getattr__':lambda self, name: __import__(name) })()
$dt = type('TimeCl', (object,), {'__repr__':lambda self: str(imp.datetime.datetime.now().isoformat()) })()
echo $dt
sleep 1
echo $dt
# 2024-03-05T23:34:50.188014
# 2024-03-05T23:34:51.259861Ask simple input:
echo @(input('Text: '))
# Text: hello
# hello
echo Hello @(_name := input('Name: ')) # Use `_` to keep env clean.
echo Hello again @(_name)
# Name: Mike
# Hello Mike
# Hello again Mike
$ENV_NAME = input('Name: ') # Use input to set and reuse env variable
echo Name is $ENV_NAME
# Name: Alex
# Name is Alex
# The way to have continuous interactive search.
while 1: ![cat /etc/passwd | grep --color -i @(input('\nUsername: '))]
while 1: ![cat @(f:='/etc/passwd') | grep --color -i @(input(f+': '))] # walrus happyAsk for input with completion and history:
from prompt_toolkit import PromptSession
from prompt_toolkit.completion import WordCompleter
from prompt_toolkit.history import FileHistory
def ask(title : str, completions : list = []):
filename = ''.join(c for c in title if c.isalpha())
history = FileHistory($XONSH_DATA_DIR + f'/ask_{filename}.txt')
completer = WordCompleter(completions)
session = PromptSession(completer=completer, history=history)
user_input = session.prompt(f'{title}: ')
return user_input
echo I am saying @(ask('What to say'))
# What to say: hello
# I am saying hello
echo Give @(ask('Fruit', ['apple', 'banana', 'orange'])) to @(ask('To', [$(whoami).strip()]))
# Fruit: <Tab>
# Fruit: apple
# To: <Tab>
# To: user
# Give apple to user
$MY_DIR = ask('Dir', $(ls /).splitlines())
# Dir: <Tab> If you want to run shell commands from REST API you can create a flask wrapper using xontrib-macro:
xpip install flask xontrib-macro
cd /tmp
from xontrib.macro.data import Write
with! Write('myapi.xsh', chmod=0o700):
import json
from flask import Flask, request
app = Flask(__name__)
@app.route('/echo', methods=['GET'])
def index():
say = request.args.get('say')
result = $(echo -n @(say)) # run subprocess command
return json.dumps({'result': result})
app.run(host="127.0.0.1", port=5000) # debug=True
./myapi.xsh
# Running on http://127.0.0.1:5000
curl 'http://127.0.0.1:5000/echo?say=cow'
# {"result": "cow"} Don't forget about API security.
Basically xonsh session loads RC files, inherit environment, uses dynamic colors, git callbacks in prompt, saves commands to history and more. Most of this features are disabled in not interactive mode (xonsh -c 'echo 1'). But in some cases you can want to rid of all features to reduce overhead on running completely. Here is the path:
xonsh --no-rc --no-env -DCOLOR_INPUT=0 -DCOLOR_RESULTS=0 -DPROMPT='@ ' \
-DXONSH_HISTORY_BACKEND=dummy -DXONTRIBS_AUTOLOAD_DISABLED=1 -st rlHere:
--no-rcto prevent loading RC files.--no-envto prevent inheriting the environment.-DCOLOR_INPUT=0to disable colors and file completer that can read files to choose the right color.-DCOLOR_RESULTS=0to disable colors in output.-DPROMPT='@ 'to disable prompt with gitstatus and other complex fields.-DXONSH_HISTORY_BACKEND=dummyto disable history backend.-DXONTRIBS_AUTOLOAD_DISABLED=1to avoid loading xontribs.-st rlto use cheapest shell backend (readline).
If you want to have a breakpoint to debug a script, use the standard Python pdb:
xpip install xontrib-macro
from xontrib.macro.data import Write
with! Write('/tmp/run.xsh', chmod=0o700, replace=True, makedir=True):
echo hello
$VAR = 1
var = 2
import pdb
pdb.set_trace() # interactive debug
echo finish
xonsh /tmp/run.xsh
# hello
# > /tmp/run.xsh(9)<module>()
# -> echo finish
# (Pdb)
var
# 2
__xonsh__.env['VAR']
# 1
exit
# bdb.BdbQuitYou've stuffed your command shell with aliases, tools, and colors but you lose it all when using ssh. The mission of the xxh project is to bring your favorite shell wherever you go through ssh without root access or system installations.
To change the command between pressing enter and execution there is the on_transform_command event:
xpip install lolcat
@events.on_transform_command
def _(cmd, **kw):
if cmd.startswith('echo') and 'lolcat' not in cmd:
# Be careful with the condition! The modified command will be passed
# to `on_transform_command` event again and again until the event
# returns the same command. Newbies can make a mistake here and
# end up with unintended looping.
return cmd.rstrip() + ' | lolcat'
else:
return cmd
echo 123456789 # <Enter>
# Execution: echo 123456789 | lolcatHere is a snippet from @maxwellfire:
50000+50000
# 100000
500+500.123
# 1000.123
import xonsh.pretty
xonsh.pretty.for_type(type(1), lambda int, printer, cycle: printer.text(f'{int:,}'))
xonsh.pretty.for_type(type(1.0), lambda float, printer, cycle: printer.text(f'{float:,}'))
50000+50000
# 100,000
500+500.123
# 1,000.123Builtin chdir context manager for scripting
from xonsh.tools import chdir
cd /tmp
mkdir -p dir1
pwd
with chdir("./dir1"):
pwd
pwd
# /tmp
# /tmp/dir1
# /tmpcd into a directory and, if the count of files is less then 100, run ls:
aliases['cdls'] = "cd @($arg0) && @(lambda: 1 if len(g`./*`) > 100 else 0) && ls"
cdls / && pwd
# bin dev etc ...
# /
cdls /usr/sbin && pwd
# /usr/sbinIn some terminals (Konsole in Linux or Windows Terminal for WSL) you can press ctrl-x ctrl-e to open up an editor (nano in Linux) in the terminal session, paste the code there, edit and then quit out. Your multiple-line code will be pasted and executed.
sleep 100 & # job 1
sleep 100 & # job 2
sleep 100 & # job 3
while $(jobs):
time.sleep(1)
print('Job done!')For example you can continuously pulling history from other sessions or just run this in xonsh to print every second:
$SHELL_TYPE
# 'prompt_toolkit'
import asyncio
from prompt_toolkit.shortcuts import print_formatted_text
async def print_and_sleep():
while True:
print_formatted_text('hey!')
await asyncio.sleep(2)
loop = asyncio.get_event_loop()
loop.create_task(print_and_sleep())Trace with hunter:
pip install hunter
$PYTHONHUNTER='depth_lt=10,stdlib=False' $XONSH_DEBUG=1 xonsh -c 'echo 1'Or try xunter for tracing and profiling.
Read Bash to Xonsh Translation Guide, run bash -c! echo 123 or install xontrib-sh.
First of all we recommend using WSL 2 with Manjaro (that maintains a rolling release) on Windows. Don't forget to fix PATH.
But if you want to use xonsh in a Windows environment:
- Install Windows Terminal - the modern terminal emulator for Windows.
- Install xontrib coreutils, cmdix, pycoreutils - a pure Python implementation of the UNIX coreutils i.e.
echo,cat,pwd,ls, etc. - Read Windows-specific tips and tricks.
aws configure --profile p1
aws configure --profile p2
aliases['aws-p1'] = "$AWS_DEFAULT_PROFILE='p1' @('aws') @($args)"
aliases['aws-p2'] = "$AWS_DEFAULT_PROFILE='p2' @('aws') @($args)"
aws-p2 s3 ls s3://my-profile1-bucket/ # The same as `aws s3 ls --profile p2 s3://my-profile1-bucket/`Python is everywhere as well ;)
You can spend significantly more time Googling and debugging sh-based solutions as well as significantly more time to make the payload work after running a command. Yeah, xonsh is a bit slower but you will not notice that in real-life tasks :)
Also, take a look:
- Python 3.12: A Game-Changer in Performance and Efficiency
- Python 3.11 is up to 10-60% faster than Python 3.10
- Making Python 5x FASTER with Guido van Rossum.
- RustPython (performance of Ruff - Python linter on Rust)
- xonsh parser on Rust
- Nuitka the Python Compiler (xonsh-binary)
uvandmambato install packages as fast as possible.
The fancy prompt is the tip of the iceberg. Xonsh shell brings other important features to love: sane language, powerful aliases, agile extensions, history backends, fully customisable tab completion, magic macro blocks, behaviour customisation via environment variables, and more, and more, and more :)
Compared to 15-20-year-old shells, yeah, xonsh is a 5-year-old youngster. But we've used it over these 5 years day by day to solve our tasks with success and happiness :)
Moved to xonsh-developer-toolkit.
Thank you for reading! This cheatsheet is just the tip of the iceberg of the xonsh shell; you can find more in the official documentation.
Also you can install the cheatsheet xontrib:
xpip install xontrib-cheatsheet
xontrib load cheatsheet
cheatsheet
# Opening: https://github.com/anki-code/xonsh-cheatsheet/blob/main/README.mdIf you like the cheatsheet, click ⭐ on the repo and tweet.
- Xonsh Tutorial
- Most copy-pastable examples prepared by xontrib-hist-format
- The cheat sheet xontrib was created with xontrib template.