usm

One CLI for the boxes you SSH into.

33 tools for what you actually do on a remote machine — open a tunnel, find a free GPU, mount a blob container, serve a directory, kill whatever is holding port 8080 — behind a single command that installs in one line.

curl -fsSL https://raw.githubusercontent.com/HSPK/usm/main/scripts/install.sh | bash

Then, on any machine:

$ usm search proxy
2 match(es) for 'proxy'

     name           version   description
 ──────────────────────────────────────────────────────────────────────────
 ●   openai-proxy   v1.4.1    Local OpenAI + Anthropic compatible proxy fo…
 ○   proxy          v1.0.1    HTTP/SOCKS/Shadowsocks proxy server or simpl…

● cached  ○ not yet downloaded · 1/2 cached · usm <name> --help for details

Why

Every one of these started as a script pasted between machines until it rotted. usm is the version that stopped rotting: one install, one help system, and one set of conventions everywhere you work.

• Nothing to set up per machine. Scripts download on first use and are cached under ~/.cache/usm/scripts, pinned by SHA-256.
• No dependency roulette. Each script declares its own requirements and gets its own venv, so usm gpu never breaks because usm openai-proxy wanted a different httpx — and nothing lands in your system Python.
• Long-running things stay running. Tunnels, proxies, syncs, and mounts install as systemd/launchd units with enable, status, and logs.
• Consistent by design. Same verbs (ls, status, logs, enable), same output vocabulary, same --json where it matters. See the design system.

The package installs as usmo; the command is usm.

Commands

usm list                 # everything
usm list --cached        # just what's downloaded
usm search blob          # match names and descriptions
usm <command> --help     # help for one command

Network & remote

Files & storage

Machine & hardware

Dev workflow

Full reference: https://hspk.github.io/usm/commands/.

Examples

usm init                                          # bootstrap a fresh machine
usm tunnel local 8080:db:5432 user@bastion        # forward a port, keep it up
usm port kill 8080                                # evict whatever squats there
usm blobmount mount /mnt/data acct container      # mount blob, refresh the SAS
usm notify -- python train.py                     # ping your phone when it exits
usm share ./build --tunnel user@bastion           # hand someone a file, from anywhere
usm doctor                                        # is this machine healthy?
usm svc add api -- ./serve.sh                     # keep it running, and at boot
usm watch src -- pytest -q                        # re-run tests on every save

CUDA_VISIBLE_DEVICES=$(usm gpu free 2) python train.py   # grab the 2 idlest GPUs

Install any script as a short command on your PATH:

usm install clash cx     # `cx ...` now runs `usm clash ...`
usm uninstall cx

Updating

usm update               # refresh the catalog
usm update --all         # re-download every cached script
usm update tunnel        # refresh a single script

Scripts self-heal: if cached files stop matching the catalog's recorded hash, usm refreshes the manifest before building the environment, so a stale catalog can never pair old requirements with new code.

How it works

The CLI (src/usmo/cli/) is a thin frontend over the usmo.core SDK; the command manifest lives in scripts/_config.json. Adding a command means adding a script and an entry — no Python changes.

• Shell scripts run under bash; Python scripts run under the current interpreter, or in a persistent per-script venv when they declare requirements.
• Scripts are fetched from this repository and cached, pinned by content hash.
• --upgrade forces a fresh download; --debug runs the local file in scripts/ instead, so iterating feels like editing any other repo file.

See Architecture for the full picture, and Development to contribute a script.

Notes

• Some scripts target Ubuntu; init, clip, and tunnel are cross-platform.
• blobmount, azsync, and cp expect Azure CLI / azcopy / blobfuse2.

License

MIT © Hangxing Wei