---
title: "CLI 与 TUI"
description: "LaunchNext 终端能力完整指南，包含 CLI 命令、TUI 使用流程与安全建议。"
url: "https://docs.closex.org/zh/launchnext/cli-and-tui.html"
markdown_url: "https://docs.closex.org/zh/launchnext/cli-and-tui.md"
site: "CloseX Docs"
product: "LaunchNext"
language: "zh-Hans"
last_updated: "2026-05-01T05:09:25.000Z"
alternates:
  en: "https://docs.closex.org/launchnext/cli-and-tui.md"
  zh-Hans: "https://docs.closex.org/zh/launchnext/cli-and-tui.md"
  ja: "https://docs.closex.org/ja/launchnext/cli-and-tui.md"
---

# LaunchNext CLI 与 TUI

LaunchNext 提供两套终端接口：

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

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

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

## 使用前准备

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

重点限制：

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

## 启动模式

```bash
launchnext
launchnext --gui
launchnext --tui
launchnext --cli help
launchnext list
```

也支持：

```bash
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` 细节

支持形式：

```bash
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` 细节

用法：

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

规则：

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

## `move` 细节

基础写法：

```bash
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 使用流程

启动：

```bash
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`

- 到 `设置 > 常规 > 命令行接口` 打开后再试。
- 注意：部分旧版终端提示文案可能仍写成 “Development settings”。

`Please launch LaunchNext GUI first`

- 先启动 GUI：

```bash
open -a LaunchNext
```

`Layout is locked`

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

`LaunchNext TUI requires an interactive terminal`

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

## 相关页面

- [常规](https://docs.closex.org/zh/launchnext/settings/general.md)
- [LaunchNext 设置](https://docs.closex.org/zh/launchnext/settings/index.md)
- [更新与排障](https://docs.closex.org/zh/launchnext/updates-and-troubleshooting.md)