kitty 命令行接口（CLI）完全指南：从启动参数到 Tabs 与 Windows 管理

kitty 命令行接口（CLI）完全指南：从启动参数到 Tabs 与 Windows 管理

【免费下载链接】kittyIf you live in the terminal, kitty is made for you! Cross-platform, fast, feature-rich, GPU based.项目地址: https://gitcode.com/GitHub_Trending/ki/kitty

kitty 是一个跨平台、基于 GPU 渲染、功能丰富的终端模拟器。本指南以 kitty 官方文档 docs/invocation.rst 为骨架，系统讲解 kitty 的命令行调用方式：包括全部启动选项的用途与取值、如何在启动时运行指定程序、以及启动后通过键盘快捷键管理 Tabs 与 Windows 的方法。读完本文，你将能够熟练使用kitty [options] [program-to-run ...]完成日常终端会话、项目开发环境的搭建，并理解这些选项在 kitty/launcher/main.c 与 kitty/simple_cli_definitions.py 中的底层实现。

kitty 命令的基本调用形式

kitty 的完整用法如下（此格式由 docs/conf.py 从选项定义自动生成到generated/cli-kitty.rst，再被 docs/invocation.rst 引用）：

kitty [options] [program-to-run ...]

其中：

• [options]是 kitty 自身的启动选项，用于控制窗口外观、配置文件、会话、远程控制等行为；
• [program-to-run ...]是要在 kitty 中运行的程序及其参数。如果不指定，kitty 默认启动一个交互式 shell。

例如官方文档给出的典型示例，启动 kitty 并保持窗口打开运行一段 shell 命令：

kitty --hold sh -c "echo hello, world"

--hold的作用是：当子进程退出后，窗口保持打开并停留在一个 shell 提示符处，方便你查看输出结果。需要注意，该选项只影响第一个窗口；你可以用关闭窗口的快捷键或输入 exit 命令退出。

命令行选项的定义源在 kitty/simple_cli_definitions.py 的kitty_options_spec()函数中，文档化的 CLI 参考就是由它渲染生成的。下面按功能分组逐一讲解这些选项。

窗口外观与身份：--class、--name、--title、--position

这几个选项控制 kitty OS 窗口（OS Window）在桌面环境中的外观与身份标识，其中前两个仅在非 macOS 平台生效（定义中带condition=not is_macos）：

• --class --app-id（别名--app-id）：在 Wayland 下设置application id，在 X11 下设置WM_CLASS窗口属性的 class 部分。默认值为kitty。
• --name --os-window-tag：在 Wayland 下设置window tag；在 X11 下设置WM_CLASS属性的 name 部分，未指定时默认使用--class的值。
• --title -T：设置 OS 窗口标题。注意这会永久覆盖程序内部设置的标题，因此只在运行不设置标题的程序时使用。
• --position：设置首个 OS 窗口在屏幕上的放置位置，格式如10x20。该选项能否生效取决于桌面环境/窗口管理器的策略，且在 Wayland 上永远不生效。如果想要 kitty 自动恢复上次的窗口位置，可参考remember_window_position配置项（见 docs/conf.rst）。

配置加载：--config 与 --override

• --config -c：指定要读取的配置文件路径，类型为 list，可多次指定以按顺序合并多个配置文件。使用特殊值NONE表示不加载任何配置文件；也支持使用-或/dev/stdin从标准输入读取配置。文件选择器会补全*.conf文件以及none、NONE关键字。

  如果不指定该选项，kitty 会按以下顺序搜索配置文件，取第一个存在的文件：

  1. $XDG_CONFIG_HOME/kitty/kitty.conf
  2. ~/.config/kitty/kitty.conf（macOS 上为~/Library/Preferences/kitty/kitty.conf）
  3. $XDG_CONFIG_DIRS/kitty/kitty.conf

  如果设置了环境变量KITTY_CONFIG_DIRECTORY，则总是使用该目录，不再进行上述搜索。此外，若系统级文件/etc/xdg/kitty/kitty.conf存在，它会被合并到用户配置之前（即优先级更低），用于为所有用户提供系统级默认值。

• --override -o：覆盖单个配置项，类型为 list，可多次指定。语法为name=value，例如：

  kitty -o font_size=20

  该选项的底层实现在 kitty/cli.py：parse_override()会把name=value形式的字符串转换为name value的覆盖行，再与配置文件一同交给load_config()处理。

关于配置文件本身的语法（注释、行续接、include/globinclude/envinclude/geninclude等指令）详见 docs/conf.rst。

工作目录与启动程序

• --directory --working-directory -d：启动时切换到指定目录，默认值为.。该选项带目录补全。
• --execute -e：在选项定义中存在但标记为隐藏（help 文本为!），通常不需要手动使用。

会话（Session）支持：--session

--session选项用于指定一个包含启动session（tabs、windows、布局、程序）的文件：

kitty --session ~/path/to/myproject/launch.kitty-session

• 文件选择器支持*.session、*.kitty-session、*.kitty_session扩展名，并相对配置目录解析；
• 使用-表示从 STDIN 读取；文件名中的环境变量会被展开，相对路径相对 kitty 配置目录解析；
• 特殊值none表示即使kitty.conf中指定了startup_session也不用会话；
• 注意：使用该选项后，命令行中指定的 program-to-run 参数会被忽略。

一个简单的会话文件示例（完整语法见 docs/sessions.rst）：

# 设置当前 tab 的布局 layout tall # 设置当前 tab 中窗口的工作目录 cd ~/path/to/myproject # 创建主窗口并运行编辑器 launch --title "Edit My Project" /usr/bin/nvim # 创建侧边窗口运行 shell launch --title "Build My Project" # 创建另一个侧边窗口查看日志 launch --title "Log for my project" /usr/bin/tail -f /path/to/project/log/file

单实例模式：--single-instance、--instance-group 与 --wait-for-single-instance-window-close

• --single-instance -1：只允许运行一个 kitty 实例。后续的调用会在现有实例中新建一个顶层窗口然后立即退出。这样可以让多个窗口共享 GPU 上的 sprite 缓存，同时减少启动时间。可以用--start-as=hidden启动一个后台 kitty 实例充当服务器。
• --instance-group：与--single-instance配合使用。所有指定了相同 instance-group 的 kitty 调用，都会在该组内第一个 kitty 实例中创建新窗口，从而在同一台机器上维护多组相互独立的 kitty 实例。
• --wait-for-single-instance-window-close：配合--single-instance使用。默认情况下 kitty 在新窗口创建后立即退出；指定此选项后，会一直等到新建窗口关闭才退出。注意：如果找不到已存在的实例，kitty 无论如何都会等待。

单实例逻辑在 C 启动器中实现，见 kitty/launcher/single-instance.c 与 kitty/launcher/main.c：handle_fast_commandline()检测到single_instance标志后，会先解析instance_group并调用single_instance_main()。

远程控制：--listen-on 与 --start-as

• --listen-on：在指定的 socket 地址上监听控制消息。例如：

  kitty -o allow_remote_control=yes --listen-on unix:/tmp/mykitty

  或 TCP 形式tcp:localhost:12345；在 Linux 上还支持与文件无关的抽象 UNIX socket，如unix:@mykitty。环境变量会被展开，相对路径相对临时目录解析。要控制 kitty，可在kitten @中使用--to选项指定该地址：

  kitten @ --to unix:/tmp/mykitty ls

  注意：该选项只有在allow_remote_control设置为yes、socket或socket-only时才会生效，也可以直接在kitty.conf中配置。若要从无窗口的 headless 模式启动，可配合--start-as=hidden。完整的远程控制教程见 docs/remote-control.rst。

• --start-as：控制初始 OS 窗口的创建方式，类型为 choices，默认normal，可取值：

  取值	含义
  normal	正常窗口
  fullscreen	全屏窗口
  maximized	最大化窗口
  minimized	最小化窗口
  hidden	隐藏窗口（适合作为单实例服务器）

  该选项对--session创建的所有 OS 窗口都生效，并会覆盖会话文件中指定的窗口状态。

分离与挂起：--detach、--detached-log、--hold、--grab-keyboard

• --detach：从控制终端分离，若存在的话。在 macOS 上应改用open -a kitty.app -n。
• --detached-log：配合--detach使用，指定保存 STDOUT/STDERR 的日志文件路径。
• --hold：见上文，保持第一个窗口在子进程退出后不关闭。
• --grab-keyboard：抓取键盘，使操作系统定义的全局快捷键被传递给 kitty 而不是被系统截获，适合创建 OS 模态窗口。其效果取决于操作系统/窗口管理器/桌面环境：在 Wayland 上仅在合成器实现 inhibit-keyboard-shortcuts 协议时有效；在 macOS 上由于苹果不允许应用在无特殊权限的情况下抓取键盘而无效。

--detach的实现细节在 kitty/launcher/main.c：启动器创建管道、fork()子进程并调用setsid()脱离会话，父进程等待子进程完成setsid()后立即退出；同时将 stdin 重定向到/dev/null（除非--session从 STDIN 读取），把 stdout/stderr 重定向到--detached-log指定的文件（默认为/dev/null）。

调试与诊断选项

• --version -v：输出当前 kitty 版本。

• --dump-commands：将子进程收到的命令输出到 STDOUT。

• --replay-commands：回放之前--dump-commands转储的命令。可以在新窗口中回放：

  kitty sh -c "kitty --replay-commands /path/to/dump/file; read"

• --dump-bytes：将子进程收到的原始字节保存到指定文件。

• --debug-rendering --debug-gl：调试渲染命令，使所有 OpenGL 调用检查错误而非忽略，并打印杂项调试信息，适合排查渲染问题。

• --debug-input --debug-keyboard：打印接收到的按键与鼠标事件。

• --debug-font-fallback：打印主字体缺失字符时回退字体选择的信息。

• --watcher：已废弃，应改用kitty.conf中的watcher配置项。

启动器如何快速处理命令行（源码视角）

在 Python 主程序启动之前，C 启动器会先做一遍"快速命令行处理"，见 kitty/launcher/main.c。其关键流程：

1. delegate_to_kitten_if_possible()检查参数：若第二个参数以@开头则转交给kitten可执行文件（对应kitten @远程控制）；若出现+kitten <name>且该 kitten 属于被包装列表，也直接exec对应 kitten。
2. parse_and_check_kitty_cli()调用由 kitty/simple_cli_definitions.py 生成 C 代码parse_cli_for_kitty()（生成的解析器文件为cli-parser-data_generated.h），解析器骨架在 kitty/launcher/cli-parser.h 中，支持长选项--opt、--opt=value、短选项组合以及选项参数分离等标准 POSIX 风格。
3. 若检测到--help/--version直接输出并退出；若检测到--detach则执行上述分离逻辑；若检测到--single-instance则调用single_instance_main()。
4. 最终把解析结果通过 Python C API 以kitty_run_data字典形式传给 Python 层（见 kitty/launcher/main.c 与 kitty/cli.py 的apply_preparsed_cli_flags()），避免重复解析。

对布尔类型选项，解析器接受y、yes、true表示真，n、no、false表示假；对 choices 类型会校验取值并给出合法值列表；未知选项会给出"Did you mean"式的编辑距离提示（见 kitty/launcher/cli-parser.h）。

Tabs 与 Windows：启动后的多任务组织

kitty 支持把多个程序组织成 tabs 和 windows。顶层组织单位是 OS 窗口（OS Window），每个 OS 窗口包含一个或多个 tab，每个 tab 包含一个或多个 kitty 窗口（window）。这些窗口可以像平铺窗口管理器那样以多种布局（layout）排列。以下快捷键均可通过kitty.conf自定义（完整可映射动作列表见 docs/actions.rst，高级映射方式见 docs/mapping.rst）。

滚动（Scrolling）

滚动动作只在终端处于主屏幕（main screen）时生效；当备用屏幕（alternate screen）激活（例如全屏编辑器）时，按键事件会传递给终端内运行的程序。

Tabs

Windows

其他常用快捷键

在 kitty.conf 中自定义窗口管理快捷键

basic.rst还给出了几组开箱即用的映射范例，把它们写入 kitty.conf（通常位于~/.config/kitty/kitty.conf）即可生效：

仿照 vim 的窗口移动习惯，聚焦相邻窗口并移动窗口：

map ctrl+left neighboring_window left map shift+left move_window right map ctrl+down neighboring_window down map shift+down move_window up ...

切换到之前激活的窗口（nth_window对正数从零开始计数聚焦第 n 个窗口，负数则取之前激活的窗口）：

map ctrl+p nth_window -1

切换到第 n 个 OS 窗口（只接受从 1 开始的正数）：

map ctrl+1 nth_os_window 1

把当前窗口分离并移动到另一个 tab 或 OS 窗口：

# 将窗口移动到新的 OS 窗口 map ctrl+f2 detach_window # 将窗口移动到新的 tab map ctrl+f3 detach_window new-tab # 将窗口移动到之前激活的 tab map ctrl+f3 detach_window tab-prev # 将窗口移动到当前 tab 左侧的 tab map ctrl+f3 detach_window tab-left # 将窗口移动到当前 tab 左侧新建的 tab map ctrl+f3 detach_window new-tab-left # 询问要移动到哪个 tab map ctrl+f4 detach_window ask

分离当前 tab：

# 将 tab 移动到新的 OS 窗口 map ctrl+f2 detach_tab # 询问要移动到哪个 OS 窗口 map ctrl+f4 detach_tab ask

关闭当前 tab 内除活动窗口外的所有窗口：

map f9 close_other_windows_in_tab

另外，同一 kitty 实例内的 tabs 可以直接用鼠标拖拽来重新排列、分离或移动到另一个 OS 窗口。

与 kitty 命令行相关的其他文档

• docs/basic.rst：本文 Tabs/Windows 章节的原始出处；
• docs/conf.rst：kitty.conf语法与配置项总览；
• docs/sessions.rst：会话文件的完整语法与goto_session用法；
• docs/remote-control.rst：通过kitten @与--listen-onsocket 控制 kitty 的完整教程；
• docs/actions.rst：所有可映射到按键的动作清单；
• docs/mapping.rst：更复杂的按键映射（模态映射、按应用映射等）；
• 源码实现：kitty/simple_cli_definitions.py（CLI 选项定义）、kitty/launcher/main.c（启动器快速命令行处理）、kitty/launcher/cli-parser.h（CLI 解析器骨架）、kitty/cli.py（Python 侧解析与配置合并）。

掌握以上命令行选项与快捷键体系后，无论是快速启动一个临时终端、按会话文件恢复整个开发环境，还是用单实例/远程控制搭建自动化工作流，都可以在 kitty 的命令行接口上直接完成。

【免费下载链接】kittyIf you live in the terminal, kitty is made for you! Cross-platform, fast, feature-rich, GPU based.项目地址: https://gitcode.com/GitHub_Trending/ki/kitty