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

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

Also supported:

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:

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:

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:

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:

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:

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
• LaunchNext Settings
• Updates and Troubleshooting