# Operations

## Local Service Management

Use the `nterminal` command:

```bash
nterminal doctor
nterminal start
nterminal status
nterminal logs
nterminal restart
nterminal stop
```

The script starts a lightweight supervisor in the background. The supervisor runs the built server, writes PID files, appends logs, waits for the local health endpoint, and restarts the Node process if it exits unexpectedly. `nterminal stop` stops both the supervisor and the real Node PID so PTY cleanup can run.

Runtime files are kept under `~/.nterminal`.

Short aliases:

```bash
nterminal status
nterminal start
nterminal stop
nterminal restart
nterminal logs
```

## Updates

Each server updates itself as an npm package install.

The **Servers** panel in Settings can manage the fleet:

- **Check for updates** checks the npm registry.
- **Update** runs `npm install -g nterminal@latest --prefer-online` plus a package-aware restart.
- **Update all** updates secondary servers in parallel first, then still attempts the main server last even if a secondary failed.

Notes:

- 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.
- If the global npm prefix is root-owned, onboarding can install a restricted sudo helper pinned to the detected npm prefix for `nterminal@latest` updates only.
- An npm registry or permission error is reported as an explanatory status.
- Update endpoints require the same auth boundary as the rest of NTerminal.
- Runtime startup refuses to create missing main state. If `~/.nterminal/state.json` is missing or has no password credential, restore it or run onboarding instead of booting into a new empty setup.

## Clean Uninstall

To remove the local runtime before uninstalling the npm package:

```bash
nterminal uninstall --force
npm uninstall -g nterminal
```

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

Option:

- add `--keep-tmux` to preserve live tmux-backed panes

## Verification

Run the standard checks before publishing or deploying:

```bash
npm run typecheck
npm test
npm run build
git diff --check
```

For a full browser smoke test:

```bash
npm run test:e2e
```

Manual smoke test:

1. Start the built server.
2. Set the initial password in the browser.
3. Create a terminal.
4. Run `printf nterminal-ok`.
5. Split the terminal.
6. Refresh the browser and confirm the terminal reconnects.
7. Close a pane and confirm it detaches as a pill.
8. Destroy the pill and confirm the PTY exits.

## Troubleshooting

If native PTY install or startup fails for a package install:

```bash
npm explore -g nterminal -- npm rebuild node-pty --build-from-source
```

If the service script will not start:

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