---
title: "CLI and TUI"
description: "Complete LaunchNext terminal guide for CLI commands, TUI workflow, and command safety."
url: "https://docs.closex.org/launchnext/cli-and-tui.html"
markdown_url: "https://docs.closex.org/launchnext/cli-and-tui.md"
site: "CloseX Docs"
product: "LaunchNext"
language: "en"
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 and TUI

LaunchNext includes two terminal interfaces:

- `CLI`: one-shot commands for scripts and automation.
- `TUI`: interactive terminal session with command history.

In practice, this feature is especially useful for AI agents that work from the terminal, such as `Claude Code`, `Codex`, or similar local automation tools. They can inspect the current LaunchNext layout, search apps, generate snapshots, and perform controlled changes without going through the GUI manually.

This page reflects the current implementation in `LaunchNextCLI.swift`, `LaunchNextCLIIPC.swift`, `LaunchpadApp.swift`, and the current General settings UI.

## Before you start

1. Open `Settings > General`.
2. Turn on `Enable CLI code` if you will use GUI-backed CLI commands or `--tui`.
3. Keep the LaunchNext GUI app running for GUI-backed commands.

Important:

- `history` and `help` work without GUI.
- `example` also works without GUI.
- `list`, `snapshot`, `search`, `create-folder`, and `move` require the GUI process.
- `create-folder` and `move` fail when layout lock is enabled.
- `--tui` requires an interactive terminal (TTY).

## Launch modes

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

Also supported:

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

Mode behavior:

- `launchnext` with no args:
  - interactive terminal -> enters TUI
  - non-interactive environment -> stays in GUI mode
- `--gui` always forces GUI mode.
- `--tui` always starts interactive terminal mode.
- `--cli <command>` runs one command and exits.

## CLI command reference

| Command | GUI required | What it does |
| --- | --- | --- |
| `help` | No | Prints usage and command help. |
| `list` | Yes | Prints flat app list. |
| `snapshot` | Yes | Prints full layout snapshot JSON, including folder IDs. |
| `history` | No | Prints saved CLI/TUI command history. |
| `example` | No | Prints practical CLI/TUI examples. |
| `search` | Yes | Searches app/folder name and path. |
| `create-folder` | Yes | Creates folder from top-level apps only. |
| `move` | Yes | Moves top-level or folder-contained app based on source/target options. |

## `search` Details

Supported forms:

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

Notes:

- default limit is `50`
- max limit is `500`
- `--json` returns structured JSON output

## `create-folder` Details

Usage:

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

Rules:

- At least two unique `--path` values are required.
- Only top-level apps are currently supported.
- Apps already inside folders are rejected.
- `--dry-run` validates and returns preview JSON without applying changes.

## `move` Details

General usage:

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

Supported combinations in current build:

- `normal-app -> normal-index`
- `folder-app -> normal-index`
- `normal-app -> folder-append`
- `folder-app -> folder-append`
- `folder-app -> folder-index`

Required target options:

- `normal-index`: `--index <n>`
- `folder-append`: `--target-folder-id <id>`
- `folder-index`: `--target-folder-id <id> --index <n>`

Recommended flow:

1. Run `snapshot` first to get folder IDs.
2. Test with `--dry-run`.
3. Remove `--dry-run` only after output is correct.

## TUI workflow

Start TUI:

```bash
launchnext --tui
```

Inside TUI prompt (`launchnext>`), built-in commands include:

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

TUI keeps persistent history and supports arrow-key navigation for previous commands.

## History and Runtime Files

- History file: `~/Library/Application Support/LaunchNext/cli_history`
- CLI IPC socket: `~/Library/Application Support/LaunchNext/cli.sock`
- History keeps up to `200` entries.

## Common errors and fixes

`CLI code is disabled`

- Enable `Settings > General > Enable CLI code`.
- Note: some terminal text in older builds may still mention "Development settings".

`Please launch LaunchNext GUI first`

- Start GUI and retry:

```bash
open -a LaunchNext
```

`Layout is locked`

- Disable layout lock before `move` / `create-folder`.

`LaunchNext TUI requires an interactive terminal`

- Run TUI in a normal terminal window, not a non-interactive CI shell.

## Related pages

- [General](https://docs.closex.org/launchnext/settings/general.md)
- [LaunchNext Settings](https://docs.closex.org/launchnext/settings/index.md)
- [Updates and Troubleshooting](https://docs.closex.org/launchnext/updates-and-troubleshooting.md)