Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# Developing builtin kittens

Builtin kittens in kitty are written in the Go language, with small Python wrapper scripts to define command line options and handle UI integration.

## Getting started

To get started with creating a builtin kitten, one that will become part of kitty and be available as `kitten my-kitten`, create a directory named `my_kitten` in the `kittens` directory. Then, in this directory add three, files: `__init__.py` (an empty file), `__main__.py` and `main.go`.

### Template for main.py

The file `main.py` contains the command line option definitions for your kitten. Change the actual options and help text below as needed.

    #!/usr/bin/env python
    # License: GPL v3 Copyright: 2018, Kovid Goyal <kovid at kovidgoyal.net>

    import sys

    # See the file kitty/cli.py in the kitty sourcecode for more examples of
    # the syntax for defining options
    OPTIONS = r'''
    --some-string-option -s
    default=my_default_value
    Help text for a simple option taking a string value.

    --some-boolean-option -b
    type=bool-set
    Help text for a boolean option defaulting to false.

    --some-inverted-boolean-option
    type=bool-unset
    Help text for a boolean option defaulting to true.

    --an-integer-option
    type=int
    default=13
    bla bla

    --an-enum-option
    choices=a,b,c,d
    default=a
    This option can only take the values a, b, c, or d
    '''.format

    help_text = '''\
    The introductory help text for your kitten.

    Can contain multiple paragraphs with :bold:`bold`
    :green:`colored`, :code:`code`, :link:`links <http://url>` etc.
    formatting.

    Option help strings can also use this formatting.
    '''

    # The usage string for your kitten
    usage = 'TITLE [BODY ...]'
    short_description = 'some short description of your kitten it will show up when running kitten without arguments to list all kittens`

    if __name__ == '__main__':
        raise SystemExit('This should be run as kitten my-kitten')
    elif __name__ == '__doc__':
        cd = sys.cli_docs  # type: ignore
        cd['usage'] = usage
        cd['options'] = OPTIONS
        cd['help_text'] = help_text
        cd['short_desc'] = short_description

### Template for main.go

    package my_kitten

    import (
        "fmt"

        "kitty/tools/cli"
    )

    var _ = fmt.Print

    func main(_ *cli.Command, opts *Options, args []string) (rc int, err error) {
        // Here rc is the exit code for the kitten which should be 1 or higher if err is not nil
        fmt.Println("Hello world!")
        fmt.Println(args)
        fmt.Println(fmt.Sprintf("%#v", opts))
        return
    }

    func EntryPoint(parent *cli.Command) {
        create_cmd(parent, main)
    }

### Edit `tools/cmd/tool/main.go`

Add the entry point of the kitten into `tools/cmd/tool/main.go`.

First, import the kitten into this file. To do this, add `"kitty/kittens/my_kitten"` into the `import ( ... )` section at the top. Then, add `my_kitten.EntryPoint(root)` into `func KittyToolEntryPoints(root *cli.Command)` and you are done. After running make you should be able to test your kitten by running:

    kitten my-kitten