Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

python cli scripts for humans

Project description


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

Important - If you have older scripts you might need the captain~=3.0.0 branch. The mainline branch has an entirely different interface.


A valid captain cli script needs just two things:

  1. A Default class that extends captain.Command and has a handle() method:

    from captain import Command
    class Default(Command):
        def handle(self, foo, bar):
            return 0
  2. Calling captain.handle() at the end of your script:

    from captain import Command, handle
    class Default(Command):
        def handle(self, foo, bar):
            return 0
    if __name__ == "__main__":

That's it! Whatever arguments you define in your class's Default.handle() method 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.arg() decorator provides a nice passthrough api to the full argparse.ArgumentParser.add_argument() method if you want to fine tune how arguments are passed into your script:

from captain import Command, handle, arg

class Default(Command):
    @arg('--foo', '-f', action="store_true")
    @arg('arg', metavar='ARG')
    def handle(self, *args, **kwargs):
        '''this is the help description'''

if __name__ == "__main__":

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

Command Output

The class 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 that Captain adds to every script.

It's available in the handle() method by using self.output:

from captain import Command

class Default(Command):
    def handle(self, *args, **kwargs):
        var1 = "print"

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

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

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

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


A typical standard python cli script

import argparse

if __name__ == '__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

class Default(captain.Command):
    def handle(foo=False, bar=0, *args):
        '''fancy script description'''
        return 0

if __name__ == '__main__':


Captain supports multiple subcommands defined in the script by naming your captain.Command child classes something other than Default:


import captain

class Foo(captain.Command):
    def handle(self):

class Bar(captain.Command):
    def handle(self):

if __name__ == '__main__':

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 defined in, you can set up your package's module like this:

# example/

from captain import Command, handle

class Default(captain.Command):
    def handle(self):
if __name__ == "__main__":

And then in your script you can add:

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

That's all there is to it.


Use pip:

$ pip install captain

For latest and greatest:

$ pip install -U "git+"

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 4.1.1
Filename, size File type Python version Upload date Hashes
Filename, size captain-4.1.1.tar.gz (23.0 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