kovidgoyal/kitty · error · ParsingOfArgsFailed

No cmdline to run specified

Error message

No cmdline to run specified

What it means

ParsingOfArgsFailed raised by the remote-control 'run' command when the payload contains no cmdline. The run command's sole purpose is to spawn a command line, so an empty cmdline fails argument parsing before anything is executed.

Source

Thrown at kitty/rc/run.py:113

        return pipe()

    def response_from_kitty(self, boss: Boss, window: Window | None, payload_get: PayloadGetType) -> ResponseType:
        import os
        import tempfile

        data = payload_get('data')
        q = self.handle_streamed_data(standard_b64decode(data) if data else b'', payload_get)
        if isinstance(q, AsyncResponse):
            return q
        stdin_data = q.getvalue()
        from kitty.launch import parse_remote_control_passwords

        cmdline = payload_get('cmdline')
        allow_remote_control = payload_get('allow_remote_control')
        pw = payload_get('remote_control_password')
        rcp = parse_remote_control_passwords(allow_remote_control, pw)
        if not cmdline:
            raise ParsingOfArgsFailed('No cmdline to run specified')
        responder = self.create_async_responder(payload_get, window)
        stdout, stderr = tempfile.TemporaryFile(), tempfile.TemporaryFile()

        def on_death(exit_status: int, err: Exception | None) -> None:
            with stdout, stderr:
                if err:
                    responder.send_error(f'Failed to run: {cmdline} with err: {err}')
                else:
                    exit_code = os.waitstatus_to_exitcode(exit_status)
                    stdout.seek(0)
                    stderr.seek(0)
                    responder.send_data(
                        {
                            'stdout': standard_b64encode(stdout.read()).decode('ascii'),
                            'stderr': standard_b64encode(stderr.read()).decode('ascii'),
                            'exit_code': exit_code,
                            'exit_status': exit_status,
                        }

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Pass the command and its arguments: kitten @ run --allow-remote-control --env KEY=val -- <cmd> <args...>
2. In scripts, assert the command list is non-empty before invoking kitten @ run
3. Check for shell-quoting mistakes that drop the argument (e.g. unquoted empty variables)

Example fix

# before
CMD=""; kitten @ run -- $CMD
# after
CMD="htop"; [ -n "$CMD" ] && kitten @ run -- $CMD

cmdline = [c for c in ["bash","-lc", build_cmd()] if c and c.strip()]
assert cmdline and cmdline[-1].strip(), 'empty cmdline for kitten @ run'

def is_nonempty_cmdline(v) -> bool:
    return isinstance(v, list) and len(v) > 0 and all(isinstance(x, str) and x for x in v)

When it happens

Trigger: kitten @ run with no command argument, or an RPC payload where the cmdline key is missing/None/empty list.

Common situations: Scripts that build the command dynamically and end up with an empty list; quoting bugs that swallow the argument; calling the raw command dict without assembling cmdline.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Must specify an action
• Unknown extra argument(s) supplied to {command.name}
• Must specify exactly {command.args.args_count} argument(s) f
• Unknown kitty remote control command: {cmd_name}
• Must specify at least one panel setting

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