Getting started

With Node.js 22.12 or newer, install the command once with npm:

npm install -g @scm-js/cli
scmjs info "(2)Ridge.scx"

Or run it without installing. npx fetches it the first time:

npx @scm-js/cli info "(2)Ridge.scx"

Without Node, download the command as a single program instead: see Without Node.

Without Node#

Each release also carries scmjs as one program with Node inside it, for Windows, macOS and Linux. It runs every command the npm package runs, and nothing else needs installing.

Each holds scmjs (scmjs.exe on Windows), its licence and the licences of what is inside it, Node's among them. Put the program in a folder on your PATH so that scmjs works from any folder. On Windows, make a folder such as C:\Tools, unpack scmjs.exe into it, and add the folder under Settings ▸ System ▸ About ▸ Advanced system settings ▸ Environment Variables ▸ Path. On macOS and Linux:

curl -L https://github.com/scm-js/scm-js/releases/latest/download/scmjs-cli-linux-x64.tar.gz | tar -xz scmjs
sudo mv scmjs /usr/local/bin/

The programs are not code-signed. The first time, Windows may show SmartScreen's "Windows protected your PC": choose More info, then Run anyway. macOS refuses a program downloaded in a browser because "the developer cannot be verified"; clear the quarantine flag once in Terminal, or allow it under System Settings ▸ Privacy & Security:

xattr -d com.apple.quarantine scmjs

A file fetched with curl carries no quarantine flag. The release's SHA256SUMS lists each file's checksum; sha256sum -c SHA256SUMS --ignore-missing (shasum -a 256 -c on macOS) checks the files you downloaded.

A package manager installs the same program and updates it with the rest of your software:

scoop bucket add scm-js https://github.com/scm-js/scoop-bucket
scoop install scmjs                  # Windows, Scoop
winget install scm-js.scmjs          # Windows, winget
brew install scm-js/tap/scmjs        # macOS and Linux, Homebrew

One thing still needs Node: map build, and a plugin written in TypeScript, compile with TypeScript, which is installed with npm. The program looks for it in the map's project (npm install typescript there) and in npm's global folder. Everything else is the same as the npm package: the same cache folder, the same copy of StarCraft, the same Docker for bots. For Claude Code, register the program itself: claude mcp add scmjs -- scmjs mcp (scmjs doctor prints the line for your copy).

The commands#

scmjs on its own, or scmjs --help, prints the overview above. Most commands sit under a noun: map, replay, plugin, bot and account. scmjs map --help lists the map commands, and every command has its own --help with its options and examples. The command reference lists them all on one page.

A command that takes several files takes as many as you name, so a shell pattern works:

scmjs map check maps/*.scx

A file that cannot be read is reported and the others carry on. The Windows Command Prompt and PowerShell do not expand *.scx for a program, so there you name the files.

First commands#

scmjs info "(2)Ridge.scx"         # what the map holds: size, players, units, triggers
scmjs map check maps/*.scx        # Check Map over a folder of maps
scmjs map open "(2)Ridge.scx"     # open it in scmJS

scmjs info reads whatever it is given: a map, a replay or a built bot (.scmbot).

Checking your setup#

Most commands need nothing more than the command itself. A few need more: TypeScript, Docker, or your copy of StarCraft. scmjs doctor says what this computer has, what each thing is for, and the command that installs what is missing. It ends with the commands that cannot run yet and the one thing each lacks.

scmjs 0.9.1 · the newest · Node v24.13.0 · linux x64

  Tools
  ✔ TypeScript   6.0.3          ~/maps/node_modules/typescript
  ▲ Docker       not found
      scmjs bot new|init|build run the bot toolchain in it.
      https://docs.docker.com/get-docker/
  ✔ Desktop app  scmJS.exe      /mnt/c/Users/you/AppData/Local/Programs/scmJS/scmJS.exe
  · Claude Code  scmjs mcp not added
      claude mcp add scmjs -- npx -y @scm-js/cli mcp
  · scmjs.dev    not signed in
      scmjs login

  The game
  ✔ StarCraft    Remastered     /mnt/c/Program Files (x86)/StarCraft
  ✔ Game engine  1248410ad2a0   ~/.cache/scmjs/engine

  Not ready
  ✖ bot new|build  Docker not found

What it looks for:

A dot instead of a tick means the thing is not there and nothing is wrong: ffmpeg, the desktop app, Claude Code and a scmjs.dev sign-in are all optional. Only a missing thing has lines under it. The Claude Code line looks for scmjs mcp among the servers Claude Code knows, for every folder or for this one, and says so when Claude Code is not installed.

The game engine line names the engine's build. Each command that plays the game drives the engine with a runner of its own; an engine fetched before the play page had a runner lacks that one, and the line says which it holds. The next command that needs a missing runner fetches it. Before anything is fetched the line says "not fetched yet".

The first line says which scmjs this is: the npm package says nothing more, and the single program says "single executable", with the package manager it came from. --json prints the checks, how this copy was installed and the list of ready commands as JSON. The doctor changes nothing, and exits with 1 only when Node itself is too old (the single program carries its own).

Commands that need StarCraft#

map preview draws a map with the game's graphics and map generate lays its ground with the game's tilesets. map trace, map cost, map coverage, map rush, map test, map heatmap, map balance, replay watch, replay export, bot run and bot ladder run the game itself. They need two things on your computer:

• Your copy of StarCraft, Remastered or 1.16.1. It is found in the usual places; otherwise name its folder with --starcraft <folder> or the SCMJS_STARCRAFT setting. Nothing of the game is fetched or carried by the command.
• The game engine, for the commands that run the game. It is the engine of scmjs.dev/play, about 25 MB, fetched the first time a command needs it and kept in your cache folder (~/.cache/scmjs on Linux, the usual place on other systems; SCMJS_CACHE moves it).

None of these run on a build server such as GitHub's, which has no copy of the game.

Updating#

scmjs about prints this version, whether a newer one is out and the line that installs it, how this copy was installed, the desktop app and Docker if they are installed, and the addresses of the editor, the docs and the source. To update the npm package:

npm install -g @scm-js/cli@latest

The single program updates through the package manager that installed it:

scoop update scmjs
winget upgrade scm-js.scmjs
brew upgrade scmjs

A downloaded one is replaced by downloading the newer file from the releases page over it. Both kinds are released together, with the same version.

Shell completion#

scmjs completion bash, zsh or fish prints a completion script with every command and option in it. Install it once:

eval "$(scmjs completion bash)"                        # in ~/.bashrc
scmjs completion zsh > ~/.zsh/completions/_scmjs       # a folder on $fpath
scmjs completion fish > ~/.config/fish/completions/scmjs.fish