kovidgoyal/kitty · error · SystemExit

The kitty command line is incomplete

Error message

The kitty command line is incomplete

What it means

kitty dispatches subcommands via a namespaced entry-point table (namespaced_entry_points in kitty/entry_points.py). When `kitty <namespace>` is run with no subcommand at all, args[1] lookup raises IndexError and kitty exits with 'The kitty command line is incomplete'.

Source

Thrown at kitty/entry_points.py:106

def run_kitten(args: list[str]) -> None:
    try:
        kitten = args[1]
    except IndexError:
        from kittens.runner import list_kittens

        list_kittens()
        raise SystemExit(1)
    sys.argv = args[1:]
    from kittens.runner import run_kitten as rk

    rk(kitten)


def namespaced(args: list[str]) -> None:
    try:
        func = namespaced_entry_points[args[1]]
    except IndexError:
        raise SystemExit('The kitty command line is incomplete')
    except KeyError:
        pass
    else:
        func(args[1:])
        return
    raise SystemExit(f'{args[1]} is not a known entry point. Choices are: ' + ', '.join(namespaced_entry_points))


entry_points = {
    # These two are here for backwards compat
    'icat': icat,
    'list-fonts': list_fonts,
    '+': namespaced,
}
namespaced_entry_points = {k: v for k, v in entry_points.items() if k[0] not in '+@'}
namespaced_entry_points['hold'] = hold
namespaced_entry_points['complete'] = complete
namespaced_entry_points['runpy'] = runpy

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Supply the intended subcommand/arguments after the namespace.
2. Inspect your alias/script to confirm arguments are actually passed (quote "$@").
3. Run kitty with no args to list valid entry points if unsure of names.

Example fix

# before
kitty +open   # missing target
# after
kitty +open file.txt

if len(args) < 2:
    raise SystemExit('usage: kitty <namespace> <subcommand> [args...]')

When it happens

Trigger: Running `kitty +<namespace>` style invocation where only the namespace token is present, e.g. `kitty icat` with no further argument when the handler expects one, or `kitten`-style dispatch with args length 1.

Common situations: Shell scripts or aliases that truncate arguments; empty "$@" expansion in a wrapper script; typo that drops the subcommand after the namespace.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• No kitten named {original_kitten_name}
• This should be run as kitten ssh
• {x} is not a valid value for {alias}. Valid values are y, ye
• Usage: kitty +runpy "some python code"
• usage: kitty +launch script.py [arguments to be passed to sc

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