What causes "This should be run as kitten show_key" in kovidgoyal/kitty?

Invoke it through kitty: `kitten show_key` (or @ map a shortcut to launch kitten show_key).

kovidgoyal/kitty · error · SystemExit

This should be run as kitten show_key

Error message

This should be run as kitten show_key

What it means

kitty's show_key kitten is not a standalone program: its main() unconditionally raises SystemExit('This should be run as kitten show_key'). The real implementation is injected by kitty's kitten runner, which runs the file under the '__run_kitten__' run_name and provides the actual entry points; executing the file directly (as __main__) hits the stub.

Source

Thrown at kittens/show_key/main.py:21


import sys

OPTIONS = r"""
--key-mode -m
default=normal
type=choices
choices=normal,application,kitty,unchanged
The keyboard mode to use when showing keys. :code:`normal` mode is with DECCKM
reset and :code:`application` mode is with DECCKM set. :code:`kitty` is the full
kitty extended keyboard protocol.
""".format
help_text = 'Show the codes generated by the terminal for key presses in various keyboard modes'
usage = ''


def main(args: list[str]) -> None:
    raise SystemExit('This should be run as kitten show_key')


if __name__ == '__main__':
    main(sys.argv)
elif __name__ == '__doc__':
    cd = sys.cli_docs  # type: ignore
    cd['usage'] = usage
    cd['options'] = OPTIONS
    cd['help_text'] = help_text
    cd['short_desc'] = help_text

View on GitHub (pinned to 6d5d0c4406)

Solutions

Invoke it through kitty: `kitten show_key` (or @ map a shortcut to launch kitten show_key).
If running from source: `kitten --debug-input` style usage or `python -m kitty.main kitten show_key` / `kitten show_key` built from your checkout.
In tests/scripts, import and call the real implementation functions rather than main(); never call the stub main().
If embedding, use kittens.runner.run_kitten('show_key', ...) so the module is executed with the proper run_name.

Example fix

# before
python kittens/show_key/main.py   # SystemExit: This should be run as kitten show_key

# after
kitten show_key

Defensive patterns

Strategy: validation

Validate before calling

import sys

def run_show_key(args):
    if sys.__dict__.get('__name__') and __name__ == '__main__':
        raise SystemExit('use: kitten show_key')
    # delegate to kitty's launcher instead
    import subprocess
    subprocess.run(['kitten', 'show_key', *args], check=True)

Prevention

Never execute kitten files with python directly; always go through the kitty binary.
In test suites, monkeypatch/call the kitten's real implementation functions, not main().
Use `kitten show_key` in keybindings rather than file paths.

When it happens

Trigger: Running `python kittens/show_key/main.py` directly, importing the module and calling main(args), or executing it via runpy without run_name='__run_kitten__'. Any path where __name__ == '__main__' reaches the stub main().

Common situations: Developers exploring the kitty source tree executing kitten files with python; IDE 'Run file' actions; tests importing kitten modules and calling main(); copy-pasting a kitten file out of kitty and running it standalone.

Related errors

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/1052272159457922. Report an issue: GitHub.