deepinspect-cli

One CLI to install, run, update, and diagnose the DeepInspect local-training-app.

deepinspect-cli wraps the service scripts that ship with the DeepInspect local-training-app so you can manage a host from a single command. It handles the initial clone, dependency installs, starts and stops the training stack, pulls updates and rebuilds, and runs a health-check that can auto-repair common issues.

Platform: Linux only. The DeepInspect app runs on Docker with NVIDIA GPU access, which ties the host to Linux.

---

Table of Contents

• Quick start
• Install
• Requirements
• Commands
  • install
  • start
  • stop
  • update
  • doctor
• What lives where
• Troubleshooting
• Development
• Uninstall

---

Quick start

# 1. Install the CLI (one-click)
curl -fsSL https://raw.githubusercontent.com/switchontech/deepinspect-cli/main/install.sh | bash

# 2. Clone + install the DeepInspect app (defaults to the `develop` branch)
deepinspect install

# 3. Start it
deepinspect start

# 4. Verify health
deepinspect doctor

That's it — the UI opens at http://localhost:3000, the API at http://localhost:8000.

---

Install

Option A — remote one-liner

curl -fsSL https://raw.githubusercontent.com/switchontech/deepinspect-cli/main/install.sh | bash

Option B — from a local clone

git clone https://github.com/switchontech/deepinspect-cli.git
cd deepinspect-cli
./install.sh

What the installer does

1. Asserts the host is Linux and has git, node (>= 18), and npm.
2. Clones (or fast-forward updates) this repo into ~/.deepinspect-cli.
3. Runs npm install --omit=dev to pull Commander + kleur.
4. Symlinks the deepinspect binary onto the first writable of ~/.local/bin, /usr/local/bin (via sudo), or ~/.local/bin (fallback — you'll be told to add it to PATH).

Environment overrides

Variable	Default	Purpose
DEEPINSPECT_CLI_REPO	https://github.com/switchontech/deepinspect-cli.git	Source repo to clone
DEEPINSPECT_CLI_DIR	$HOME/.deepinspect-cli	Where the CLI is installed
DEEPINSPECT_CLI_BRANCH	main	Which branch of the CLI to install

---

Requirements

These must exist on the host before deepinspect install:

Tool	Minimum	Notes
Linux	Ubuntu 22.04 tested	Required for Docker + NVIDIA
git	any recent
node	22.12.0	The app's frontend expects Node 22 LTS
npm	bundled with Node
python3	3.x	Backend dependencies
docker	any recent	Daemon must be reachable
NVIDIA driver + nvidia-smi	—	Needed for GPU training

Also required (one-time, from the upstream repo): the training_app_container and vault-prod Docker containers must be set up via the scripts under linux_docker_setup/ in the upstream app. deepinspect doctor will tell you if they are missing.

deepinspect doctor reports every missing piece.

---

Commands

deepinspect <command> [args] [options]

Command	What it does
deepinspect install [branch]	Clone + install the local-training-app
deepinspect start	Start the app (Docker container + services)
deepinspect stop	Stop the app
deepinspect update [branch]	Pull, rebuild, and restart
deepinspect doctor [--fix]	Diagnose and (optionally) auto-repair

deepinspect install [branch]

Clones switchontech/local-training-app into ~/.deepinspect/app and installs both frontend and backend dependencies.

deepinspect install                # clone the default branch (develop)
deepinspect install main           # clone the main branch
deepinspect install feature/new-ui # clone a feature branch

• Runs npm install in frontend/.
• Runs pip install -r requirements_v7.txt (falls back to requirements_v5.txt, then requirements_v3.txt) in backend/.
• Persists the selected branch in ~/.deepinspect/state.json.
• Re-running on an existing clone will switch branch and fast-forward pull, but won't rebuild. Use update for that.

deepinspect start

Delegates to the app's service_scripts/start_training_app.sh, which:

• Starts the training_app_container Docker container.
• Unseals Vault (if sealed, using /root/etc/training-app/unseal.key).
• Starts the FastAPI backend, file server, and frontend inside the container.
• Opens Chrome at http://localhost:3000.

deepinspect stop

Delegates to service_scripts/stop_training_app.sh, which stops the execute-pipe and the training app container.

deepinspect update [branch]

Full refresh cycle:

stop → git fetch → git checkout <branch> → git pull --ff-only
     → git submodule update --init --recursive
     → npm install && npm run build (frontend)
     → pip install -r requirements_v*.txt (backend)
     → start

deepinspect update                 # refresh the current branch
deepinspect update main            # switch to main, rebuild, restart

deepinspect doctor [--fix]

A structured health check. Each check prints as ok, warn, or err.

Group	Check
Binaries	git, docker, node, npm, python3 (required)
Binaries	nvidia-smi, jq (optional but flagged)
Runtime	Node version (warns if below 22)
Install	.git present at ~/.deepinspect/app
Install	frontend/, backend/, service_scripts/ exist
Install	frontend/node_modules/ populated
Docker	Daemon reachable
Docker	training_app_container and vault-prod status
Vault	Sealed vs. unsealed
Ports	3000 (frontend) and 8000 (backend) availability
GPU	nvidia-smi output
Backend	HTTP reachability on :8000

deepinspect doctor          # report only
deepinspect doctor --fix    # attempt safe auto-repairs

With --fix, doctor will:

• docker start any stopped required container.
• Kill processes holding port 3000 or 8000.

It will not auto-unseal Vault (that's what start is for) or install missing binaries — you'll see a pointer to the fix instead.

Exit code: 0 if every check was ok, 1 if any check errored.

---

What lives where

~/.deepinspect-cli/         ← the CLI itself (this repo)
~/.deepinspect/
├── app/                    ← clone of switchontech/local-training-app
├── state.json              ← branch, install + last-update timestamps
├── logs/                   ← reserved for CLI logs
└── pids/                   ← reserved for CLI-managed PIDs

The CLI is intentionally thin. Everything that actually runs the app lives in the upstream repo's service_scripts/ and Docker setup — the CLI orchestrates those.

---

Troubleshooting

deepinspect: command not found The installer fell back to ~/.local/bin. Add it to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

**Not installed at ~/.deepinspect/app. Run \deepinspect install` first.** The CLI expects the clone of local-training-app. Run deepinspect installbeforestart, stop, update, or doctor`.

training_app_container: not found The upstream Docker container hasn't been built on this host yet. Run the setup scripts under linux_docker_setup/ in the cloned app first, then deepinspect start.

Vault is SEALED deepinspect doctor detected a sealed Vault. Run deepinspect start — the upstream start script handles unsealing from /root/etc/training-app/unseal.key.

Port 3000 or 8000 is in use

deepinspect doctor --fix   # kills whatever is holding the port

deepinspect-cli supports Linux only. You're on macOS or Windows. The upstream app requires Linux + Docker + NVIDIA. No fallback is provided.

---

Development

git clone https://github.com/switchontech/deepinspect-cli.git
cd deepinspect-cli
npm install
node bin/deepinspect.js --help

Project layout:

bin/
└── deepinspect.js          ← CLI entry (Commander)
src/
├── paths.js                ← constants (home dir, ports, repo URL)
├── platform.js             ← Linux-only guard
├── logger.js               ← colored console helpers
├── shell.js                ← spawn / port / pid helpers
├── state.js                ← state.json read/write
└── commands/
    ├── install.js
    ├── start.js
    ├── stop.js
    ├── update.js
    └── doctor.js
install.sh                  ← one-click bootstrap

All modules are ESM. No build step, no bundler — just Node.

---

Uninstall

deepinspect stop                   # stop running services
rm -rf ~/.deepinspect              # remove app clone + state
rm -rf ~/.deepinspect-cli          # remove the CLI
rm -f "$(command -v deepinspect)"  # remove the symlink

---

License

Copyright © SwitchOn. All rights reserved.