Skip to main content

A framework for building beautiful shells

Project description


Build Status Coverage PyPI version

Nubia is a lightweight framework for building command-line applications with Python. It was originally designed for the “logdevice interactive shell (aka. ldshell)” at Facebook. Since then it was factored out to be a reusable component and several internal Facebook projects now rely on it as a quick and easy way to get an intuitive shell/cli application without too much boilerplate.

Nubia is built on top of python-prompt-toolkit which is a fantastic toolkit for building interactive command-line applications.

Disclaimer: Nubia is beta for non-ldshell use-cases. Some of the design decisions might sound odd but they fit the ldshell usecase perfectly. We are continuously making changes to make it more consistent and generic outside of the ldshell use-case. Until a fully stable release is published, use it on your own risk.

See the CONTRIBUTING file for how to help out.

If you are curious on the origins of the name, checkout Nubia on Wikipedia with its unique and colourful architecture.

Key Features

  • Interactive mode that offers fish-style auto-completion
  • CLI mode that gets generated from your functions and classes.
  • Optional bash/zsh completions via an external utility ‘nubia-complete’ (experimental)
  • A customisable status-bar in interactive mode.
  • An optional IPython-based interactive shell
  • Arguments with underscores are automatically hyphenated
  • Python3 type annotations are used for input type validation

Interactive mode

The interactive mode in Nubia is what makes it unique. It is very easy to build a unique shell for your program with zero overhead. The interactive shell in its simplistic form offers automatic completions for commands, sub-commands, arguments, and values. It also offers a great deal of control for developers to take control over auto-completions, even for commands that do not fall under the typical format. An example is the “select” command in ldshell which is expressed as a SQL-query. We expect that most use cases of Nubia will not need such control and the AutoCommand will be enough without further customisation.

If you start a nubia-based program without a command, it automatically starts an interactive shell. The interactive mode looks like this:

Interactive Demo

Non-interactive mode

The CLI mode works exactly like any traditional unix-based command line utility. Non-interactive Demo

Have your @command decorated function return an int to send that value as the Unix return code for your non interactive CLI.


It starts with a function like this:

import socket
import typing

from termcolor import cprint
from nubia import argument, command, context

@argument("hosts", description="Hostnames to resolve", aliases=["i"])
@argument("bad_name", name="nice", description="testing")
def lookup(hosts: typing.List[str], bad_name: int) -> int:
    This will lookup the hostnames and print the corresponding IP addresses
    ctx = context.get_context()

    if not hosts:
        cprint("No hosts supplied via --hosts")
        return 1

    print(f"hosts: {hosts}")
    cprint(f"Verbose? {ctx.verbose}")

    for host in hosts:
        cprint(f"{host} is {socket.gethostbyname(host)}")

    return 0


Nubia-based applications require python 3.6+ and works with both Mac OS X or Linux. While in theory it should work on Windows, it has never been tried.

Installing Nubia

If you are installing nubia for your next project, you should be able to easily use pip for that:

pip3 install python-nubia

Building Nubia from source

You can either to build a tarball, or use pipenv to setup a virtualenv with all the dependencies installed.

Running example in virtualenv:

It's often best to create a virtualenv to contain the dependencies required for python-nubia project.

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

If you would like to run the example, then you need to add the root of the source tree into your PYTHONPATH.

virtualenv .venv
source .venv/bin/activate

export PYTHONPATH="$(pwd)"
python3 example/

To run the unit tests:

From within the virtualenv you can use nosetests:


Or if you don't want to create a virtualenv, just use:

python3 nosetests

Getting Started

See the getting started guide to learn how to build a simple application with Nubia.


python-nubia is BSD licensed, as found in the LICENSE file.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

python-nubia-0.2b5.tar.gz (55.1 kB view hashes)

Uploaded source

Built Distribution

python_nubia-0.2b5-py3-none-any.whl (70.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page