CLI

Install

npm install -g immorterm

This installs the immorterm control-plane CLI (Node). It is not the same binary as the persistent-terminal C binary, which ships separately via Homebrew (brew install lonormaly/tap/immorterm) or GitHub Releases. If both end up on your PATH under the same name, immorterm doctor detects the collision and tells you which one you're actually running.

One-shot use without a global install also works:

npx immorterm status

Usage

immorterm                  # no args: interactive menu (TTY required)
immorterm <command> [...]  # one-shot subcommand

Commands: init, start, stop, status, enable, disable, pro (alias: license), upgrade, install, doctor, dashboard, config, serve, logs, memory, insights.

With no arguments in a non-TTY environment (CI, piped stdin), the CLI does not attempt the interactive menu — it prints a warning plus the command list and exits 0:

Interactive mode requires a terminal (TTY). Use a subcommand instead: immorterm status, immorterm start, etc.
Available commands: init, start, stop, status, enable, disable, pro, upgrade, install, doctor, dashboard, config, serve, logs, memory, insights

After any subcommand except upgrade, when stdout is a TTY, the CLI may print a one-line update hint. The check runs at most once per autoUpdate.checkIntervalHours (config), only when autoUpdate.enabled is true, and never creates a config file for users who haven't run immorterm init.

init

Setup wizard. Configures the terminal backend, theme, services, and license, then writes ~/.immorterm/config.json.

immorterm init             # interactive wizard (rich TUI)
immorterm init --yes       # no prompts, write defaults

Three paths, picked automatically:

1. Interactive terminal — full-screen TUI wizard.
2. Interactive, but the TUI fails to start — plain-prompt fallback wizard.
3. Non-TTY stdin/stdout, or --yes — no prompts at all. Defaults plus any flags are written directly.

Flags

An invalid --terminalMode value silently falls back to regular.

Non-interactive output

ImmorTerm initialized (non-interactive)
  Config: ~/.immorterm/config.json
  Terminal: regular
  Theme: Purple Haze
  Memory: enabled
  Gateway: disabled
  License: Free

After every path (interactive or not), init also:

• attempts to install the VS Code extension (non-fatal on failure), and
• if memory ended up enabled but the memory binary is missing, prompts to install it (interactive) or prints Memory binary not found. Install it with: immorterm memory install (non-interactive).

start / stop

Start or stop the background services.

immorterm start            # start all enabled services
immorterm start memory     # start one service (even if disabled in config)
immorterm start gateway
immorterm stop             # stop all
immorterm stop memory
immorterm stop gateway

With no service argument, start skips services that are disabled in config and prints how to enable them. Naming a service explicitly starts it regardless of its enabled flag. stop always stops what you name (or both).

status

Service states, component versions, license, and free-tier limits.

immorterm status

Shows, in order: a themed banner; Memory state (healthy / starting / stopped, plus MCP health and the free-tier retrieval window); Gateway state (server count, active children, free-tier server cap); a Component Versions table (with → x.y.z available markers when updates exist); auto-update status and when it last checked; and the license tier. On the free tier a limits summary is appended (max terminals, projects, memory retention hours, MCP servers).

enable / disable

Toggle a service in config, globally or per-project. This does not start or stop anything — pair with immorterm start / stop.

immorterm enable memory
immorterm enable gateway
immorterm disable memory --project .

Per-project use ensures the project has an identity file and writes the service flag into project-level config; without --project it writes defaults.services.<service>.enabled in the global config.

memory

Manage the native memory service (a local binary; your data never leaves the machine).

immorterm memory install   # download and install the binary
immorterm memory up        # start the daemon
immorterm memory status    # default action when no subcommand is given
immorterm memory down      # stop the daemon (SIGTERM)

The service port is read from ~/.immorterm/memory.state.json (written by the service on startup) and defaults to 8765:

Memory service is already running and healthy.
Memory service: http://127.0.0.1:8765/health

An unknown action prints the usage line npx immorterm memory [up|down|status|install] and exits 0.

pro (alias: license)

Upgrade to Pro or manage the subscription. immorterm license ... is a backward-compatible alias — same command, same subcommands.

immorterm pro                       # free tier: upgrade flow · pro: management menu
immorterm pro status                # show license details + validate with the server
immorterm pro activate <key>        # activate a license key
immorterm pro deactivate            # remove license (transfer to another machine)
immorterm pro dev <tier>            # dev-only tier override

No subcommand: on the free tier this runs the upgrade flow — fetches live pricing, prompts for an email, opens checkout in the browser, polls up to 3 minutes for purchase confirmation, then asks you to paste the license key (the full key is only ever delivered by email). On an active license it shows a management menu instead (view status, deactivate, open the pro page).

status prints tier, email, expiry, masked key, instance, and last validation time, then validates the key against the license server.

activate <key> (positional, required) activates and persists the license, then lists what's unlocked and offers to enable the MCP Gateway.

deactivate releases the license so it can be activated on another machine, and reverts the local config to the free tier.

dev <tier> sets a development tier override that bypasses license validation: pro, memory-pro, free, or off (also clear) to remove it. It creates a ~/.immorterm/.dev sentinel file; delete that file to disable dev overrides entirely.

Environment variables used by the checkout flow:

upgrade

Upgrade ImmorTerm components, or check what's outdated.

immorterm upgrade                   # upgrade everything with an update available
immorterm upgrade cli               # one component
immorterm upgrade --dry-run         # show what would happen, change nothing
immorterm upgrade memory --force    # upgrade even if already up to date

Per-component strategy:

An unknown component name prints the valid list and exits 0. When nothing needs upgrading, it prints each component's version with a checkmark.

install

Install ImmorTerm components. Currently one subcommand:

immorterm install extension          # stable
immorterm install extension --pre    # pre-release
immorterm install extension --force  # reinstall over an existing install

Requires the VS Code code CLI on PATH (Command Palette → "Shell Command: Install 'code' command in PATH"). Without --force, an already-installed extension is left alone and its version is printed.

doctor

Full diagnostics.

immorterm doctor

Runs eight checks, each pass / warn / fail with a one-line fix hint on anything that isn't a pass:

Example line format:

  ✓ C Binary: ImmorTerm 0.9.3 (built 2026-01-01)
  ! Memory Binary: Not found
      fix: npx immorterm memory install

Exit code is 1 when any check fails; warnings alone exit 0.

config

Read and write global config values using dot notation.

immorterm config get defaults.services.memory.enabled
immorterm config set theme "Ocean Depths"
immorterm config set defaults.terminalMode ai

Both key and (for set) value are required positionals. Values are parsed: true, false, null, and numbers become their typed values; everything else stays a string. Objects print as pretty JSON on get. Missing intermediate objects are created automatically on set, so paths that the wizard hasn't materialized yet still work.

dashboard

Interactive TUI dashboard with live service polling.

immorterm dashboard

Free tier runs read-only (view status only); Pro gets full control hotkeys. It auto-starts the local API server (immorterm serve) so session data is available — non-fatal if that fails. Exits 1 if the TUI itself can't launch.

serve

Local API server for the web dashboard and TUI. Serves session data from the registry and structured log files — no data leaves the machine.

immorterm serve               # default port 3847
immorterm serve --port 4000

Writes a PID file to ~/.immorterm/serve.pid so other entry points (the dashboard, the TUI log explorer) can detect and reuse a running instance — starting it twice is a no-op. CORS allows immorterm.com and localhost origins. On startup it prints its endpoint list:

ImmorTerm API server running on http://localhost:3847
Endpoints:
  GET  /api/health
  GET  /api/health/daemons
  GET  /api/health/services
  GET  /api/sessions[?include_archived=true]
  GET  /api/sessions/:id/snapshot
  GET  /api/sessions/:id/grid
  GET  /api/sessions/:id/ai
  GET  /api/sessions/:id/cast
  GET  /api/sessions/:id/daemon-log[?lines=100]
  POST /api/sessions/:id/restart
  POST /api/sessions/:id/remove
  POST /api/health/daemons/prune
  GET  /api/search?q=...[&include_archived=false]

Press Ctrl+C to stop

logs

Browse terminal session logs for the current project in a TUI explorer.

immorterm logs                # pick a session interactively
immorterm logs <session-id>   # jump straight to one session

Sessions are scoped to the current working directory's project. Exits 1 if the explorer can't launch.

insights

Proactive-intelligence stats from the memory service: suggestion engagement rates, per-signal effectiveness bars, top failure patterns, 7-day session counts, and memory category distribution.

immorterm insights

Requires the memory service to be running — otherwise it prints Memory service unavailable. Start it with: immorterm memory up and exits 1.

Exit codes

The CLI exits 0 unless something listed here happens:

Notably 0: running with no subcommand in a non-TTY environment, unknown memory actions, and unknown upgrade components (each prints an error and valid usage instead).

Default ports