kovidgoyal/kitty · error · SystemExit

Must specify exactly {command.args.args_count} argument(s) f

Error message

Must specify exactly {command.args.args_count} argument(s) for {command.name}

What it means

SystemExit raised by kitty's remote-control subcommand CLI parser when a command that requires a fixed number of positional arguments receives a different count. args_count declares the exact arity (e.g. 1 for @ send-text's text, 2 for title+value commands); a mismatch aborts before execution.

Source

Thrown at kitty/rc/base.py:453

        pass

    def handle_streamed_data(self, data: bytes, payload_get: PayloadGetType) -> BytesIO | AsyncResponse:
        stream_id = payload_get('stream_id')
        if not stream_id or not isinstance(stream_id, str):
            raise StreamError('No stream_id in rc payload')
        return self.stream_in_flight.handle_data(stream_id, data)


def cli_params_for(command: RemoteCommand) -> tuple[Callable[[], str], str, str, str]:
    return (command.options_spec or '\n').format, command.args.spec, command.desc, f'kitten @ {command.name}'


def parse_subcommand_cli(command: RemoteCommand, args: ArgsType) -> tuple[Any, ArgsType]:
    opts, items = parse_args(args[1:], *cli_params_for(command), result_class=command.options_class)
    if command.args.args_count is not None and command.args.args_count != len(items):
        if command.args.args_count == 0:
            raise SystemExit(f'Unknown extra argument(s) supplied to {command.name}')
        raise SystemExit(f'Must specify exactly {command.args.args_count} argument(s) for {command.name}')
    return opts, items


def display_subcommand_help(func: RemoteCommand) -> None:
    with suppress(SystemExit):
        parse_args(['--help'], (func.options_spec or '\n').format, func.args.spec, func.desc, func.name)


def command_for_name(cmd_name: str) -> RemoteCommand:
    from importlib import import_module

    cmd_name = cmd_name.replace('-', '_')
    try:
        m = import_module(f'kitty.rc.{cmd_name}')
    except ImportError:
        raise KeyError(f'Unknown kitty remote control command: {cmd_name}')
    return cast(RemoteCommand, getattr(m, cmd_name))

View on GitHub (pinned to 6d5d0c4406)

Solutions

Run 'kitten @ <command> --help' to see the expected positional arguments and supply exactly that many
Fix empty shell variables: use defaults or guard before invoking, e.g. [ -n "$title" ] && kitten @ set-window-title "$title"
Quote arguments so multi-word values count as one positional

Example fix

# before
kitten @ set-window-title

# after
kitten @ set-window-title "my title"

Defensive patterns

Strategy: validation

Validate before calling

# example for @ set-window-title which takes exactly 1 positional
title = os.environ.get('TITLE', '').strip()
if not title:
    sys.exit('TITLE required')
assert len([title]) == 1
subprocess.run(['kitten', '@', 'set-window-title', title])

Type guard

def has_exact_args(items: list[str], n: int) -> bool:
    return len(items) == n

Try / catch

res = subprocess.run(argv, capture_output=True, text=True)
if 'Must specify exactly' in res.stderr:
    print_usage_and_expected_count(cmd); sys.exit(2)

Prevention

Guard against empty interpolated variables before building kitty @ commands
Read each subcommand's --help once and encode its arity in your script's command table

When it happens

Trigger: Running e.g. 'kitten @ set-window-title' with no title (needs 1), 'kitten @ send-text' with no text, or any rc subcommand with fewer/more positional args than declared in its args.spec.

Common situations: Scripts where the interpolated variable is empty, forgotten arguments when converting one-liners, or shell quoting mistakes that merge/split arguments.

Related errors

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