Skip to main content

python cli scripts for humans

Project description

Easy python cli scripts for people that just want get things done.

Captain was lovingly crafted for First Opinion and powers all our command line scripts.


A valid captain cli script needs just two things:

  1. A main function

    def main(foo, bar):
        return 0
  2. Calling exit using captain.exit()

    import captain
    def main(foo, bar):
        return 0

That’s it! Whatever arguments you define in the main function will be options on the command line. A captain script is called just like any other python command line script, so to run the above example you could do:

$ python path/to/ --foo=1 --bar=2

Argument Decorator

The captain.decorators.arg() decorator provides a nice passthrough api to the full argparse module if you need to really customize how arguments are passed into your script:

from captain import exit
from captain import echo
from captain.decorators import arg

@arg('--foo', '-f')
@arg('arg', metavar='ARG')
def main(*args, **kwargs):
    '''this is the help description'''


Would print a help string like this:

usage: [-h] [--foo FOO] ARG

this is the help description

positional arguments:

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

If you want another nifty way to define arguments, take a look at docopt.


This small module makes it easy to print stuff in your script while still giving you full control by being able to configure the logger if you need to. It also will obey the global --quiet flag.

from captain import echo

var1 = "print"

var2 = "stdout"
echo.out("this will {} to {}", var1, var2)

var2 = "stderr"
echo.err("this will {} to {}", var1, var2)

e = ValueError("this will print with stacktrace and everything")

The echo module has a lot of nice little helper features but Captain also can work with modules like clint if you need to do more advanced cli output.


A typical standard python cli script

import argparse

if __name__ == u'__main__':
    parser = argparse.ArgumentParser(description='fancy script description')
    parser.add_argument("--foo", action='store_true')
    parser.add_argument("--bar", default=0, type=int)
    parser.add_argument("args", nargs='*')
    args = parser.parse_args()

would become:

import captain

def main(foo=False, bar=0, *args):
    '''fancy script description'''
    return 0



Captain supports multiple subcommands defined in the script using the format main_subcommand.


import captain

def main_foo():

def main_bar():


So foo could be called using:

$ python foo

And bar could be called using:

$ python bar

Embedding captain in another package

If you want a script from you package to be usable using both python -m example and maybe a console_scripts entry point, you can set up your package’s module like this:

# example/

from captain import exit as console

def main():


And then in your script you can add:

entry_points = {
    'console_scripts': [
        'example = example.__main__:console'

That’s all there is to it.

Easy listing of all captain scripts in a directory

You can get a list of all available scripts in a directory by running captain with no arguments:

$ captain


Use pip:

$ pip install captain

Project details

Download files

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

Files for captain, version 2.0.2
Filename, size File type Python version Upload date Hashes
Filename, size captain-2.0.2.tar.gz (20.3 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page