/cli

title: eIsland CLI
icon: terminal

eIsland CLI

:::info This document covers the `eisland-cli` command line tool in `cli/`. It reads the scripts in the root `package.json` at runtime and runs them through `npm run`, with an interactive picker, grouped listing, shorthand commands, and confirmation before dangerous scripts. For the scripts themselves, see [Development Commands](README.md). :::

Installation

The CLI is a private local package. It is not published to npm. Its dependencies are installed by the root `postinstall` hook, so after `npm install` at the repository root you only need to build and link it:

cd cli
npm run build
npm link

If you skipped install scripts (for example with `--ignore-scripts`), run `npm ci` inside `cli/` first.

After `npm link`, the `eisland-cli` command is available globally. It works from any directory inside the repository because it walks up to find the root `package.json` (`name: "eisland"`).

:::tip Run `npm run dev` inside `cli/` to rebuild on every change (`vite build --watch`). The linked command picks up the new build right away. :::

Package Scripts

| Command | Script | Description | |---------|--------|-------------| | `npm run build` | `vite build` | Bundle `src/index.ts` into `dist/index.js` (Vite SSR build, Node 24 target) | | `npm run dev` | `vite build --watch` | Rebuild on change | | `npm run typecheck` | `tsc -p tsconfig.json --noEmit` | Type-check only; `tsc` does not emit | | `npm test` | `vitest run` | Run CLI tests with the CLI's own Vitest config | | `npm run test:watch` | `vitest` | Run CLI tests in watch mode |

Usage

| Command | Description | |---------|-------------| | `eisland-cli` | Open the interactive dashboard (TTY only; prints help otherwise) | | `eisland-cli list [group]` | List scripts by group (alias: `ls`) | | `eisland-cli run <script> [-- args]` | Run a script by its exact name | | `eisland-cli <seg> [seg...] [-- args]` | Shorthand: segments are joined with `:` | | `eisland-cli help` | Show help |

eisland-cli test main                       # npm run test:main
eisland-cli plugin build smtc               # npm run plugin:build:smtc
eisland-cli run test:renderer -- --watch    # npm run test:renderer -- --watch
eisland-cli list plugin                     # list only the plugin group

Options

| Option | Description | |--------|-------------| | `-y, --yes` | Skip confirmation for dangerous scripts | | `--lang <locale>` | Output language: `zh-CN`, `zh-TW`, `en-US`, `ja-JP` | | `-h, --help` | Show help | | `-v, --version` | Show the CLI version |

:::important Arguments meant for the script must come after `--`. Unknown options before `--` are rejected, so `eisland-cli test --watch` fails while `eisland-cli test -- --watch` works. :::

Interactive Dashboard

Running `eisland-cli` with no arguments opens a full-screen welcome screen with the eIsland logo and the main menu. Use `↑` / `↓` and `Enter` to open a feature, or `Esc` to quit. Your previous terminal content comes back when you quit.

| Menu entry | Description | |------------|-------------| | Repository | The task view for root `package.json` scripts (the CLI's first feature) | | Local tests | Checks of system features on this machine; see [Local Tests](#local-tests) |

:::important Going back to the main menu does not stop running tasks. They keep running and are still listed when you open Repository again. Quitting from the main menu asks first if any task is still running. :::

The task view uses a top/bottom layout:

| Area | Content | |------|---------| | Top | Output of the current task, following the latest line by default | | Bottom left box | Task list (`●` running, `✔` done, `✖` failed, `■` ended); older tasks collapse when space runs out | | Bottom right box | The actions, script picker, or confirmation prompt |

:::note The bottom panel takes 40% of the terminal height (at least 10 rows), and the output panel gets the rest. The task box has a fixed width of 32 columns, and long task names are truncated. The action box gets the remaining width. If the terminal is narrower than the logo, the welcome screen shows a plain `eIsland` title instead. :::

| Action | Description | |--------|-------------| | Run script... | Open the picker. Type to filter by name or description; several space-separated keywords must all match. The `[dangerous]` tag comes first in the description column, and the selected row's description scrolls when it does not fit | | End current task | Kill the current task's whole process tree (shown while it is running) | | Close current task | Remove a finished task from the list | | Back to main menu | Return to the welcome screen; running tasks keep running | | Quit | End all running tasks (asks first if any are running) and restore the terminal |

| Key | Effect | |-----|--------| | `↑` / `↓`, `Enter` | Choose and confirm an action or script | | `Esc` | Leave the picker and return to the actions | | `Tab` / `Shift+Tab` | Switch the task shown in the output panel | | `PgUp` / `PgDn` | Scroll output by one page (the view stays put while new output arrives) | | `Home` / `End` | Jump to the first line / resume following the latest output | | `Ctrl+C` | Quit (in the picker: go back) |

Several tasks can run at the same time, for example `dev` alongside a test run. Each task keeps its last 5000 lines. The script list is reloaded each time the picker opens. Dangerous scripts ask for `(y/N)` confirmation in the bottom panel unless you started with `--yes`.

:::warning In the dashboard, scripts write to a pipe, not the terminal. Colors are forced on with `FORCE_COLOR=1`, but scripts that read keyboard input (such as Vitest watch-mode shortcuts) receive none. Run those with a direct command instead, for example `eisland-cli run test -- --watch`. :::

:::tip "End current task" uses `taskkill /T /F` on Windows and signals the process group elsewhere, so grandchild processes such as the Tauri pr