Example of awesome CLI app template for xonsh. Just fork it and add your commands.

If you like the idea of bar theme click ⭐ on the repo and tweet.

Features

• CLI: based on power and sugar from click.
• Execution: pip-installable as well as clone-and-run.
• Ability to grow your library.
• Ability to set up context and environment.
• Ability to set up context options and command arguments.
• Ability to use environment variables as replacement of options and arguments.
• Logging
• Tests: local, docker.

Install

pip install git+https://github.com/anki-code/xonsh-awesome-cli-app
mycli

or

git clone https://github.com/anki-code/xonsh-awesome-cli-app
cd xonsh-awesome-cli-app
./mycli

Usage

You can use this app as a template to your own apps.

mycli
# Usage: mycli [OPTIONS] COMMAND [ARGS]...
# 
#   CLI management.
# 
# Options:
#   --name TEXT  Context option: name.
#   --debug      Context option: debug mode.
#   --help       Show this message and exit.
# 
# Commands:
#  say      Say.
#  context  Show app context.

mycli hello --help
# Usage: mycli hello [OPTIONS]
# 
#   Say hello.
# 
# Options:
#   --wait  Command argument: wait before print.
#   --help  Show this message and exit.

mycli say hello
# Username say: hello

mycli say hello --wait
# Wait...
# Username say: hello

mycli --name Mike say hello --wait
# Wait...
# Mike say: hello

$MYCLI_NAME = 'Alex'
mycli say hello
# Alex say: hello

mycli context
# Environment:
# {'MYCLI_NAME': 'Alex'}
# Context:
# {'debug': False, 'log': <RootLogger root (INFO)>, 'name': 'Alex'}

mycli --debug say hello
# TRACE SUBPROC: (['echo', 'Username', 'say:', 'hello'],), captured=hiddenobject
# Username say: hello
# 2024-03-01 18:21:24,723 - root - INFO - Additional log message.
# TRACE SUBPROC: (['echo', 'Here', 'is', 'debug', 'message', 'too', ''],), captured=hiddenobject
# Here is debug message too

How to create subcommands

If you need subcommands (subgroups) e.g.:

mycli env activate --name myname
mycli env deactivate
mycli info --full

use this example:

import click

@click.group()  # Create main group in `click`
def cli():
    pass

@cli.group()  # Create subgroup `env` in `cli`
def env():
    pass

@env.command()  # Create subcommand `activate` in `env`
@click.option('--name')
def activate(name):
    click.echo(f"Activating environment: {name}")

Tests

You can use pytest for test cli:

pytest tests/
# tests/test_app.xsh passed

Known issues

pytest: xonsh not found

In some sort situations you need to use current env python to run tests:

@(sys.executable) -m pytest -v

import sys
py = sys.executable
def test_help():
    @(py) -m xonsh ./mycli --help

See more CLI libs

• click, Shared options and flags between commands
• rich
• typer

See also

• xonsh-cheatsheet - Cheat sheet for xonsh shell with copy-pastable examples.
• rc-awesome - Awesome snippets of code for xonshrc in xonsh shell.
• macro - Library of the useful macro for the xonsh shell.
• docker-xonsh-wrapper - Wrap an app in docker container and catch the signals from docker using xonsh shell.
• xunter - Profiling the xonsh shell code using hunter.
• Xxh Development Environment (xde)