LaunchNext CLI 与 TUI

LaunchNext 提供两套终端接口：

• CLI：一次性命令，适合脚本和自动化。
• TUI：交互式终端会话，带历史记录。

实际使用里，这套能力尤其适合在终端里工作的 AI Agent，比如 Claude Code、Codex，或者类似的本地自动化工具。它们可以直接读取当前 LaunchNext 布局、搜索应用、生成快照，并在不手动点 GUI 的情况下执行可控修改。

本页内容基于当前实现：LaunchNextCLI.swift、LaunchNextCLIIPC.swift、LaunchpadApp.swift 以及当前 General 设置界面。

使用前准备

1. 打开 设置 > 常规。
2. 如果你要使用依赖 GUI endpoint 的 CLI 命令或 --tui，请开启 Enable CLI code。
3. 对于依赖 GUI 的命令，保持 LaunchNext 图形界面正在运行。

重点限制：

• history 和 help 不依赖 GUI。
• example 也不依赖 GUI。
• list、snapshot、search、create-folder、move 依赖 GUI 进程。
• 当布局锁定开启时，create-folder 与 move 会失败。
• --tui 必须在交互式终端（TTY）中运行。

启动模式

launchnext
launchnext --gui
launchnext --tui
launchnext --cli help
launchnext list

也支持：

LaunchNext --cli help
LaunchNext --tui
/Applications/LaunchNext.app/Contents/MacOS/LaunchNext --tui

模式行为：

• launchnext 不带参数时：
  • 交互式终端 -> 进入 TUI
  • 非交互环境 -> 保持 GUI 模式
• --gui：强制 GUI 模式。
• --tui：强制 TUI 模式。
• --cli <command>：执行单条命令后退出。

CLI 命令总览

命令	是否需要 GUI	作用
help	否	输出用法与帮助。
list	是	输出扁平应用列表。
snapshot	是	输出完整布局快照 JSON（包含 folder ID）。
history	否	输出已保存的 CLI/TUI 历史命令。
example	否	输出 CLI/TUI 示例命令。
search	是	按名称和路径搜索应用/文件夹。
create-folder	是	仅支持用顶层应用创建文件夹。
move	是	按来源/目标参数移动顶层应用或文件夹内应用。

search 细节

支持形式：

launchnext --cli search --query "safari"
launchnext --cli search safari
launchnext --cli search --query "mail" --limit 20
launchnext --cli search --query "mail" --limit 20 --json

说明：

• 默认 limit 为 50
• 最大 limit 为 500
• 使用 --json 可返回结构化 JSON 结果

create-folder 细节

用法：

launchnext --cli create-folder \
  --path "/Applications/Mail.app" \
  --path "/Applications/Notes.app" \
  --name "Utilities" \
  --index 12 \
  --dry-run

规则：

• 至少需要两个不同的 --path。
• 当前仅支持顶层应用。
• 文件夹内应用会被拒绝。
• --dry-run 只做校验并返回预览 JSON，不会实际改动布局。

move 细节

基础写法：

launchnext --cli move --source normal-app --path "/Applications/Safari.app" --to normal-index --index 12 --dry-run

当前版本支持的组合：

• normal-app -> normal-index
• folder-app -> normal-index
• normal-app -> folder-append
• folder-app -> folder-append
• folder-app -> folder-index

目标参数要求：

• normal-index：--index <n>
• folder-append：--target-folder-id <id>
• folder-index：--target-folder-id <id> --index <n>

建议流程：

1. 先跑 snapshot 获取 folder ID。
2. 先用 --dry-run 验证结果。
3. 确认无误后再移除 --dry-run 实际执行。

TUI 使用流程

启动：

launchnext --tui

进入提示符（launchnext>）后可用命令：

• list
• snapshot
• history
• example
• search
• create-folder
• move
• clear
• help
• quit

TUI 会持久化历史记录，支持方向键回溯历史命令。

历史与运行时文件

• 历史文件：~/Library/Application Support/LaunchNext/cli_history
• CLI IPC Socket：~/Library/Application Support/LaunchNext/cli.sock
• 历史最大保留 200 条。

常见报错与处理

CLI code is disabled

• 到 设置 > 常规 > Enable CLI code 打开后再试。
• 注意：部分旧版终端提示文案可能仍写成 “Development settings”。

Please launch LaunchNext GUI first

• 先启动 GUI：

open -a LaunchNext

Layout is locked

• 先关闭布局锁，再执行 move / create-folder。

LaunchNext TUI requires an interactive terminal

• 请在正常终端窗口运行，不要在非交互式 CI shell 中运行。

相关页面

• 常规
• LaunchNext 设置
• 更新与排障