nterminal 1.2.12 → 1.2.14

package/dist/shared/protocol.d.ts

@@ -60,6 +60,12 @@ export interface AgentPingResponse {
     ok: boolean;
     latencyMs: number;
 }
+export interface AgentUninstallResponse {
+    ok: boolean;
+    message: string;
+    disconnecting: boolean;
+    disconnected?: boolean;
+}
 export interface SystemStatsResponse {
     cpuPercent: number | null;
     memoryPercent: number;
@@ -76,16 +82,8 @@ export interface SystemStatsResponse {
 export interface VersionInfo {
     version: string;
     runningVersion: string;
-    commit: string | null;
-    runningCommit: string | null;
-    branch: string | null;
-    dirty: boolean;
-    isGit: boolean;
-    installMode: 'git' | 'package';
 }
 export interface UpdateCheckResponse {
-    behind: number | null;
-    commit: string | null;
     currentVersion?: string;
     latestVersion?: string | null;
     updateAvailable?: boolean | null;

package/dist/shared/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/shared/protocol.ts"],"names":[],"mappings":"AAyVA,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,OAAO,GAAG,MAAwC,CAAC;QACzD,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3G,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YAC7E,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,IACE,OAAO,CAAC,IAAI,KAAK,QAAQ;YACzB,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ;YACtC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;YAC9B,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAC9B,CAAC;YACD,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACjE,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../../src/shared/protocol.ts"],"names":[],"mappings":"AAwVA,MAAM,UAAU,0BAA0B,CAAC,GAAW;IACpD,IAAI,CAAC;QACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,OAAO,GAAG,MAAwC,CAAC;QACzD,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC3G,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,aAAa,IAAI,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ,EAAE,CAAC;YAC7E,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,IACE,OAAO,CAAC,IAAI,KAAK,QAAQ;YACzB,OAAO,OAAO,CAAC,UAAU,KAAK,QAAQ;YACtC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC;YAC9B,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAC9B,CAAC;YACD,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACjE,OAAO,OAAgC,CAAC;QAC1C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/docs/configuration.md

@@ -4,34 +4,17 @@ Configuration comes from `.env` or process environment variables.
 
 ## `.env.example`
 
-`.env.example` is the local runtime template. Keep it in source control, but never commit the copied `.env` file.
+`.env.example` is the runtime template. Keep it in source control, but never commit the copied `.env` file.
 
-The template intentionally contains only the core values needed for a manual local start. Add advanced settings from the table below only when you need to override the defaults.
+The template intentionally contains only the core values. Add advanced settings from the table below only when you need to override the defaults.
 
-Source checkouts read `.env` from the repository root. npm package installs launched through `nterminal` read the runtime env file from `~/.nterminal/.env`.
-
-For manual local setup:
-
-```bash
-cp .env.example .env
-npm run generate:secrets
-```
-
-Paste the generated `NTERMINAL_SESSION_SECRET=...` value into `.env`.
-
-For normal package installs, prefer:
+NTerminal package installs launched through `nterminal` read the runtime env file from `~/.nterminal/.env`.
 
 ```bash
 nterminal onboarding
 ```
 
-For source checkouts:
-
-```bash
-npm run onboarding
-```
-
-Onboarding writes `.env` for you.
+Onboarding writes `.env` for you, including an absolute `NTERMINAL_STATE_PATH` so password/TOTP state is read from the same file when the service starts.
 
 ## Settings
 
@@ -41,7 +24,7 @@ Onboarding writes `.env` for you.
 | `NTERMINAL_PORT` | `3107` | HTTP server port. |
 | `NTERMINAL_WORKSPACE_ROOT` | home directory | Startup directory for new terminal tabs. |
 | `NTERMINAL_SHELL` | `$SHELL`, then `/bin/bash` | Shell path for new PTYs. |
-| `NTERMINAL_STATE_PATH` | `.nterminal/state.json` | Local state file for password and layout data. |
+| `NTERMINAL_STATE_PATH` | `~/.nterminal/state.json` | Local state file for password and layout data. Onboarding writes an absolute path. |
 | `NTERMINAL_SESSION_SECRET` | required | Server secret for password hashing and session cookies. |
 | `NTERMINAL_SESSION_TTL_SECONDS` | `43200` | Session lifetime in seconds. |
 | `NTERMINAL_COOKIE_SECURE` | `false` locally | Set `true` when serving through HTTPS. |
@@ -54,8 +37,8 @@ Onboarding writes `.env` for you.
 | `NTERMINAL_FILE_LIST_MAX_ENTRIES` | `2000` | Maximum entries returned in one file explorer directory listing. |
 | `NTERMINAL_FILE_TEXT_MAX_BYTES` | `1048576` | Maximum bytes loaded for text or Markdown view/edit. |
 | `NTERMINAL_FILE_PREVIEW_MAX_BYTES` | `52428800` | Maximum bytes served for browser file previews. |
-| `NTERMINAL_PID_PATH` | `.nterminal/nterminal.pid` | PID file for the control script. |
-| `NTERMINAL_LOG_PATH` | `.nterminal/nterminal.log` | Log file for the control script. |
+| `NTERMINAL_PID_PATH` | `~/.nterminal/nterminal.pid` | PID file for the control script. |
+| `NTERMINAL_LOG_PATH` | `~/.nterminal/nterminal.log` | Log file for the control script. |
 | `NTERMINAL_HEALTH_TIMEOUT_SECONDS` | `15` | Startup health-check timeout for the control script. |
 | `NTERMINAL_STOP_TIMEOUT_SECONDS` | `20` | Graceful stop timeout for the control script. |
 

package/docs/features.md

@@ -17,7 +17,7 @@
 - Each server keeps its own terminal layout, tabs, split panes, detached terminals, and file context.
 - The sidebar switches servers without tearing down the inactive server workspaces.
 - Server cards show CPU, memory, disk, and swap usage with percentages and absolute values.
-- Settings includes an Updates section for checking git status and updating each server.
+- Settings includes an Updates section for checking npm package updates on each server.
 - Update all runs secondary server updates in parallel first, then updates the main server last.
 - Background update checks run hourly and badge Settings/Updates when an update is available.
 

package/docs/onboarding.md

@@ -2,22 +2,12 @@
 
 NTerminal uses one interactive command for both the main server and secondary servers.
 
-For npm package installs:
-
 ```bash
 npm install -g nterminal
 nterminal onboarding
 ```
 
-CLI package installs store `.env`, state, pid, and log files under `~/.nterminal`. Install with a user-writable npm global prefix so in-app updates can run `npm install -g nterminal@latest` without sudo.
-
-For source checkouts:
-
-```bash
-npm run onboarding
-```
-
-`npm install` runs automatically as the `preonboarding` hook, so a fresh checkout does not need a separate install step.
+NTerminal stores `.env`, state, pid, and log files under `~/.nterminal`. Install with a user-writable npm global prefix so in-app updates can run `npm install -g nterminal@latest` without sudo.
 
 ## Main Server
 
@@ -33,9 +23,9 @@ The main setup flow:
 
 1. Picks a bind address and port. The default main bind is `127.0.0.1`, so public traffic goes through the configured reverse proxy instead of bypassing TLS.
 2. Requires a public `https://<domain>` URL for the proxy setup path. Raw IPs, `http://`, `localhost`, and `.local` URLs are rejected in that path.
-3. Writes `.env`, including a generated `NTERMINAL_SESSION_SECRET`.
+3. Writes `.env`, including a generated `NTERMINAL_SESSION_SECRET` and absolute `NTERMINAL_STATE_PATH`.
 4. Sets the login password and enables TOTP headlessly. The CLI prints a terminal QR code, base32 secret, and `otpauth://` URI, then verifies the 6-digit code.
-5. Optionally starts the bundled package build, or builds and starts a source checkout, with `scripts/nterminalctl deploy`.
+5. Optionally starts the installed package with `nterminal deploy`.
 6. Optionally provisions nginx, DNS verification, firewall rules, and Let's Encrypt TLS.
 
 The final summary prints the public URL, internal bind, and next steps.
@@ -55,10 +45,10 @@ The secondary setup flow:
 1. Binds to `0.0.0.0` and picks a free port, preferring `3107`.
 2. Asks for the URL the main server should use to reach this machine.
 3. Asks for a display name.
-4. Generates a session secret and `NTERMINAL_AGENT_TOKEN`, then writes `.env`.
+4. Generates a session secret and `NTERMINAL_AGENT_TOKEN`, then writes `.env` with an absolute state path.
 5. Prompts for the main server URL, password, and authenticator code.
 6. Registers this secondary server with the main server automatically.
-7. Optionally starts the bundled package build, or builds and starts a source checkout.
+7. Optionally starts the installed package.
 
 Onboard the main server first. The main must already have password and TOTP configured before a secondary server can register itself.
 
@@ -84,37 +74,6 @@ Privileged work uses one of two modes:
 
 The "Main is ready" summary is printed only after the selected setup path has completed its checks.
 
-## Local-Only Start
-
-For a localhost-only development run without nginx/TLS onboarding:
-
-```bash
-npm install
-cp .env.example .env
-npm run generate:secrets
-```
-
-Paste the generated value into `.env`:
-
-```env
-NTERMINAL_SESSION_SECRET=replace-with-generate-secrets-output
-```
-
-Then build and start:
-
-```bash
-npm run build
-npm start
-```
-
-Open:
-
-```text
-http://127.0.0.1:3107
-```
-
-On the first visit, set the local NTerminal password and configure TOTP.
-
 ## Re-Running Onboarding
 
 You can re-run onboarding to refresh generated config or register a secondary server again.

package/docs/operations.md

@@ -2,7 +2,7 @@
 
 ## Local Service Management
 
-For production-style local operation from an npm package install, use the `nterminal` command:
+Use the `nterminal` command:
 
 ```bash
 nterminal doctor
@@ -13,69 +13,56 @@ nterminal restart
 nterminal stop
 ```
 
-For source checkouts, use the bundled control script through npm:
-
-```bash
-npm run ctl -- doctor
-npm run ctl -- build
-npm run ctl -- start
-npm run ctl -- status
-npm run ctl -- logs
-npm run ctl -- restart
-npm run ctl -- stop
-```
-
 The script starts the built server in the background, writes a PID file, appends logs, waits for the local health endpoint, and stops the real Node PID so PTY cleanup can run.
 
-Source checkouts keep runtime files in the repository's `.nterminal/` directory by default. npm package installs launched through `nterminal` keep runtime files under `~/.nterminal`.
-
-One-command source checkout deploy:
-
-```bash
-npm run deploy:local
-```
+Runtime files are kept under `~/.nterminal`.
 
 Short aliases:
 
 ```bash
-npm run service:status
-npm run service:start
-npm run service:stop
-npm run service:restart
-npm run service:logs
+nterminal status
+nterminal start
+nterminal stop
+nterminal restart
+nterminal logs
 ```
 
 ## Updates
 
-Each server updates itself with the method used to install it.
+Each server updates itself as an npm package install.
 
 The **updates** panel in the main server sidebar footer can manage the fleet:
 
-- **Check for updates** runs `git fetch` for git checkouts, or checks the npm registry for package installs.
-- **Update** runs `git pull --ff-only` plus rebuild/restart for git checkouts, or `npm install -g nterminal@latest` plus restart for package installs.
+- **Check for updates** checks the npm registry.
+- **Update** runs `npm install -g nterminal@latest` plus restart.
 - **Update all** updates secondary servers in parallel first and the main server last.
 
 Notes:
 
-- `--ff-only` stops and reports an error when a checkout has local commits or a diverged branch.
 - npm package updates run as the same user that owns the running server process. Use a user-writable npm prefix, not a root-owned global install, if you want UI updates to work without sudo.
-- A git checkout with no upstream branch, or an npm registry/permission error, is reported as an explanatory status.
+- An npm registry or permission error is reported as an explanatory status.
 - Update endpoints require the same auth boundary as the rest of NTerminal.
 
-## Clean Local State
+## Clean Uninstall
 
-To clean a local install before reinstalling:
+To remove the local runtime before uninstalling the npm package:
 
 ```bash
-nterminal clean --force --env
+nterminal uninstall --force
+npm uninstall -g nterminal
 ```
 
-This stops the managed server, kills NTerminal tmux sessions, removes `.nterminal/`, and removes `.env`.
-In a source checkout, run the same command as `npm run ctl -- clean --force --env`.
+`npm uninstall -g nterminal` cannot run cleanup automatically on modern npm versions. Run `nterminal uninstall --force` first; it stops the managed server, unloads an NTerminal launchd agent when present, kills NTerminal tmux sessions, removes runtime state under `~/.nterminal`, and removes `~/.nterminal/.env`.
+
+If you already removed the package while a server is still running, reinstall or use npx to run the cleanup command, then uninstall again:
+
+```bash
+npx nterminal@latest uninstall --force
+npm uninstall -g nterminal
+```
 
-Options:
+Option:
 
-- omit `--env` to keep `.env`
 - add `--keep-tmux` to preserve live tmux-backed panes
 
 ## Verification
@@ -114,17 +101,11 @@ If native PTY install or startup fails for a package install:
 npm explore -g nterminal -- npm rebuild node-pty --build-from-source
 ```
 
-For source checkouts:
-
-```bash
-npm rebuild node-pty --build-from-source
-```
-
 If the service script will not start:
 
 ```bash
-npm run ctl -- doctor
-npm run ctl -- logs
+nterminal doctor
+nterminal logs
 ```
 
 If you lose the local NTerminal password, stop the server and remove the local state file at `NTERMINAL_STATE_PATH`. The next browser visit will show the first-run password setup screen again.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nterminal",
-  "version": "1.2.12",
+  "version": "1.2.14",
   "license": "GPL-3.0-only",
   "type": "module",
   "packageManager": "npm@10.9.7",

package/scripts/nterminalctl

@@ -4,7 +4,8 @@ set -Eeuo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 DEFAULT_APP_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 APP_DIR="${NTERMINAL_APP_DIR:-$DEFAULT_APP_DIR}"
-ENV_FILE="${NTERMINAL_ENV_FILE:-$APP_DIR/.env}"
+DEFAULT_RUNTIME_DIR="${HOME:-$APP_DIR}/.nterminal"
+ENV_FILE="${NTERMINAL_ENV_FILE:-$DEFAULT_RUNTIME_DIR/.env}"
 
 COMMAND="${1:-help}"
 if [[ $# -gt 0 ]]; then
@@ -65,13 +66,17 @@ resolve_path() {
 
 load_env_file
 
+DEFAULT_STATE_PATH="$DEFAULT_RUNTIME_DIR/state.json"
+DEFAULT_PID_PATH="$DEFAULT_RUNTIME_DIR/nterminal.pid"
+DEFAULT_LOG_PATH="$DEFAULT_RUNTIME_DIR/nterminal.log"
+
 HOST="${NTERMINAL_HOST:-127.0.0.1}"
 PORT="${NTERMINAL_PORT:-3107}"
 NODE_BIN="${NTERMINAL_NODE_BIN:-node}"
 NPM_BIN="${NTERMINAL_NPM_BIN:-npm}"
-PID_PATH="$(resolve_path "${NTERMINAL_PID_PATH:-.nterminal/nterminal.pid}")"
-LOG_PATH="$(resolve_path "${NTERMINAL_LOG_PATH:-.nterminal/nterminal.log}")"
-STATE_PATH="$(resolve_path "${NTERMINAL_STATE_PATH:-.nterminal/state.json}")"
+PID_PATH="$(resolve_path "${NTERMINAL_PID_PATH:-${NTERMINAL_RUNTIME_PID_PATH:-$DEFAULT_PID_PATH}}")"
+LOG_PATH="$(resolve_path "${NTERMINAL_LOG_PATH:-${NTERMINAL_RUNTIME_LOG_PATH:-$DEFAULT_LOG_PATH}}")"
+STATE_PATH="$(resolve_path "${NTERMINAL_STATE_PATH:-${NTERMINAL_RUNTIME_STATE_PATH:-$DEFAULT_STATE_PATH}}")"
 HEALTH_TIMEOUT_SECONDS="${NTERMINAL_HEALTH_TIMEOUT_SECONDS:-15}"
 STOP_TIMEOUT_SECONDS="${NTERMINAL_STOP_TIMEOUT_SECONDS:-20}"
 RUNTIME_ENTRY="$APP_DIR/dist/server/index.js"
@@ -91,6 +96,12 @@ if [[ -n "$UPDATE_LOCK_PATH" ]]; then
   trap cleanup_update_lock EXIT
 fi
 
+export NTERMINAL_APP_DIR="$APP_DIR"
+export NTERMINAL_ENV_FILE="$ENV_FILE"
+export NTERMINAL_STATE_PATH="$STATE_PATH"
+export NTERMINAL_PID_PATH="$PID_PATH"
+export NTERMINAL_LOG_PATH="$LOG_PATH"
+
 health_url() {
   printf 'http://%s:%s/api/auth/session' "$HOST" "$PORT"
 }
@@ -103,16 +114,8 @@ ensure_app_dir() {
   [[ -d "$APP_DIR" ]] || die "app directory not found: $APP_DIR"
 }
 
-is_source_checkout() {
-  [[ -f "$APP_DIR/tsconfig.server.json" && -d "$APP_DIR/src" ]]
-}
-
 missing_env_message() {
-  if is_source_checkout; then
-    printf '.env not found at %s; copy .env.example and run npm run generate:secrets' "$ENV_FILE"
-  else
-    printf '.env not found at %s; run nterminal onboarding' "$ENV_FILE"
-  fi
+  printf '.env not found at %s; run nterminal onboarding' "$ENV_FILE"
 }
 
 ensure_env_file() {
@@ -123,9 +126,6 @@ ensure_runtime() {
   if [[ -f "$RUNTIME_ENTRY" ]]; then
     return 0
   fi
-  if is_source_checkout; then
-    die "dist/server/index.js not found; run scripts/nterminalctl build first"
-  fi
   die "dist/server/index.js not found; reinstall nterminal"
 }
 
@@ -198,6 +198,31 @@ launchd_controls_app() {
   esac
 }
 
+launchd_agent_plist() {
+  local home_dir="${HOME:-}"
+  [[ -n "$home_dir" ]] || return 1
+  printf '%s/Library/LaunchAgents/%s.plist' "$home_dir" "$LAUNCHD_LABEL"
+}
+
+unload_launchd_if_controlled() {
+  launchd_controls_app || return 0
+  local domain
+  domain="$(launchd_domain)" || return 0
+  launchctl bootout "$domain" >/dev/null 2>&1 || launchctl remove "$LAUNCHD_LABEL" >/dev/null 2>&1 || true
+  rm -f "$PID_PATH"
+  info "NTerminal launchd agent unloaded label=$LAUNCHD_LABEL"
+}
+
+remove_owned_launchd_plist() {
+  local plist
+  plist="$(launchd_agent_plist || true)"
+  [[ -n "$plist" && -f "$plist" ]] || return 0
+  if grep -F "$APP_DIR" "$plist" >/dev/null 2>&1; then
+    rm -f "$plist"
+    info "NTerminal launchd plist removed path=$plist"
+  fi
+}
+
 remove_stale_pid() {
   local pid
   pid="$(read_pid || true)"
@@ -371,37 +396,14 @@ cmd_restart() {
 
 cmd_build() {
   ensure_app_dir
-  if ! is_source_checkout; then
-    ensure_runtime
-    info "Package install uses bundled dist; no build needed."
-    return 0
-  fi
-  (
-    cd "$APP_DIR"
-    "$NPM_BIN" run build
-  )
+  ensure_runtime
+  info "Package install uses bundled dist; no build needed."
 }
 
 cmd_deploy() {
   ensure_app_dir
   ensure_env_file
-  (
-    cd "$APP_DIR"
-    if is_source_checkout && [[ -f package-lock.json ]]; then
-      "$NPM_BIN" ci
-    elif is_source_checkout; then
-      "$NPM_BIN" install
-    fi
-    if is_source_checkout; then
-      "$NPM_BIN" run typecheck
-      # node-pty's install script always compiles from source (no prebuilt
-      # download); ask npm to rebuild it explicitly after dependency updates.
-      "$NPM_BIN" rebuild node-pty --build-from-source
-      "$NPM_BIN" run build
-    else
-      ensure_runtime
-    fi
-  )
+  ensure_runtime
   cmd_restart
 }
 
@@ -453,15 +455,10 @@ clean_state_paths() {
   local state_path="$1"
   local pid_path="$2"
   local log_path="$3"
-  local default_state_dir="$4"
   local state_dir
   state_dir="$(dirname "$state_path")"
-  if [[ "$state_dir" == "$default_state_dir" ]]; then
-    rm -rf "$state_dir"
-  else
-    rm -f "$state_path" "$pid_path" "$log_path" "$state_dir/update.lock"
-    rm -rf "$state_dir/notification-assets"
-  fi
+  rm -f "$state_path" "$pid_path" "$log_path" "$state_dir/update.lock"
+  rm -rf "$state_dir/notification-assets"
 }
 
 cmd_clean() {
@@ -479,7 +476,7 @@ cmd_clean() {
   done
 
   if (( force != 1 )); then
-    die "clean is destructive; rerun with: scripts/nterminalctl clean --force [--env] [--keep-tmux]"
+    die "clean is destructive; rerun with: $(control_command clean) --force [--env] [--keep-tmux]"
   fi
 
   ensure_app_dir
@@ -490,7 +487,7 @@ cmd_clean() {
 
   local state_dir
   state_dir="$(dirname "$STATE_PATH")"
-  clean_state_paths "$STATE_PATH" "$PID_PATH" "$LOG_PATH" "$APP_DIR/.nterminal"
+  clean_state_paths "$STATE_PATH" "$PID_PATH" "$LOG_PATH"
   if (( remove_env == 1 )); then
     rm -f "$ENV_FILE"
   fi
@@ -498,6 +495,41 @@ cmd_clean() {
   info "NTerminal cleaned state_dir=$state_dir env_removed=$remove_env tmux_killed=$kill_tmux"
 }
 
+cmd_uninstall() {
+  local force=0
+  local kill_tmux=1
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --force) force=1 ;;
+      --keep-tmux) kill_tmux=0 ;;
+      *) die "unknown uninstall option: $1" ;;
+    esac
+    shift
+  done
+
+  if (( force != 1 )); then
+    die "uninstall is destructive; rerun with: $(control_command uninstall) --force [--keep-tmux]"
+  fi
+
+  ensure_app_dir
+  unload_launchd_if_controlled
+  stop_pid_file "$PID_PATH"
+  if (( kill_tmux == 1 )) && command -v tmux >/dev/null 2>&1; then
+    tmux -L nterminal kill-server >/dev/null 2>&1 || true
+  fi
+  clean_state_paths "$STATE_PATH" "$PID_PATH" "$LOG_PATH"
+  rm -f "$ENV_FILE"
+  remove_owned_launchd_plist
+
+  info "NTerminal runtime uninstalled state_dir=$(dirname "$STATE_PATH") env_removed=1 tmux_killed=$kill_tmux"
+  info "Package files are still installed. To remove them, run: npm uninstall -g nterminal"
+}
+
+control_command() {
+  local command="$1"
+  printf 'nterminal %s' "$command"
+}
+
 cmd_pid() {
   local pid
   pid="$(current_pid || true)"
@@ -568,17 +600,20 @@ cmd_doctor() {
 
 cmd_help() {
   cat <<EOF
-Usage: scripts/nterminalctl <command>
+Usage: nterminal <command>
 
 Commands:
   status         Show process status. Exit 0 when running, 3 when stopped.
   start          Start the built server in the background.
   stop           Stop the managed server with SIGTERM, then SIGKILL after timeout.
   restart        Stop and start the server.
-  build          Build source checkouts. Package installs use bundled dist.
-  deploy         Build source checkouts when needed, then restart.
+  build          No-op for package installs; verifies the bundled runtime exists.
+  deploy         Restart the installed package using the bundled runtime.
   clean --force  Stop server, kill NTerminal tmux sessions, and remove local state/log/pid files.
                  Add --env to also remove .env. Add --keep-tmux to preserve live panes.
+  uninstall --force
+                 Stop server, unload NTerminal launchd agent, remove local runtime files and .env.
+                 Add --keep-tmux to preserve live panes.
   logs [N]       Show the last N log lines. Default: 100.
   logs -f [N]    Follow logs.
   doctor         Check Node/npm/env/runtime/pid/log/port readiness.
@@ -589,9 +624,9 @@ Commands:
 Environment:
   NTERMINAL_APP_DIR                  Override app directory.
   NTERMINAL_ENV_FILE                 Override .env path.
-  NTERMINAL_STATE_PATH               Default .nterminal/state.json.
-  NTERMINAL_PID_PATH                 Default .nterminal/nterminal.pid.
-  NTERMINAL_LOG_PATH                 Default .nterminal/nterminal.log.
+  NTERMINAL_STATE_PATH               Default ~/.nterminal/state.json.
+  NTERMINAL_PID_PATH                 Default ~/.nterminal/nterminal.pid.
+  NTERMINAL_LOG_PATH                 Default ~/.nterminal/nterminal.log.
   NTERMINAL_HEALTH_TIMEOUT_SECONDS   Default 15.
   NTERMINAL_STOP_TIMEOUT_SECONDS     Default 20.
   NTERMINAL_LAUNCHD_LABEL            Default com.nterminal.local. Used when a loaded LaunchAgent controls this app.
@@ -606,6 +641,7 @@ case "$COMMAND" in
   build) cmd_build "$@" ;;
   deploy) cmd_deploy "$@" ;;
   clean|purge) cmd_clean "$@" ;;
+  uninstall|remove) cmd_uninstall "$@" ;;
   logs|log) cmd_logs "$@" ;;
   doctor) cmd_doctor "$@" ;;
   pid) cmd_pid "$@" ;;