Use the command line (sternway-cli)

sternway-cli lets a terminal or a script use the running desktop app: list your saved hosts, open a terminal to one in the app, run a saved snippet on hosts and print what each printed, and copy a file to or from a host. It talks only to the app on this computer, over a socket (Linux, macOS) or a named pipe (Windows) only your user can reach. It never opens a network port, and it does nothing while the app is locked.

Set it up

The command ships with the desktop app, in its resources/cli folder: sternway-cli.mjs and a launcher, sternway-cli (Linux, macOS) or sternway-cli.cmd (Windows). Settings › CLI tokens shows the launcher’s full path.

1. Link it into a folder on your PATH, for example on Linux:

   ln -s /opt/Sternway/resources/cli/sternway-cli ~/.local/bin/sternway-cli

   (or add its folder to PATH).

2. Install Node.js 18 or later if you do not have it: the command runs with the node on your PATH, not with the app’s own executable.

The Linux packages already install the app itself as sternway, which is why the command is called sternway-cli.

Make a token

Every request carries a token. In Settings › CLI tokens, choose to make a new one:

1. Give it a name, such as deploy script.
2. Tick what it may do:
   • List hosts (hosts): each host’s label, address and id, nothing else;
   • Open terminals (connect);
   • Run snippets (run);
   • Copy files (sftp);
   • Read-only: takes away everything that changes something (connect, run, uploads, and downloads that would replace a file), whatever else is ticked.
3. Choose when it expires (a day to a year; every token expires).
4. A token with Copy files gets one folder on this computer: the one you choose, or Sternway in your Downloads folder. Downloads go only into it and uploads come only from it. It must be new or empty.

The token is shown once, and copied to the clipboard for you (cleared again after the time set in Settings › Security). Sternway keeps only a hash of it and cannot show it again. Revoke deletes a token at once; the list shows when each was last used.

Use it

Give the command the token through the STERNWAY_TOKEN variable, or a file only you can read (chmod 600) named with --token-file. It is never taken from the command line, where other users and your shell history would see it.

export STERNWAY_TOKEN=stw_…
sternway-cli whoami                       # the token's name, scopes and expiry
sternway-cli hosts                        # label, address and id of each host
sternway-cli connect web-1                # opens a terminal to web-1 in the app
sternway-cli run uptime --hosts web-1,web-2
sternway-cli run deploy --hosts web-1 --var tag=v1.4 --json
sternway-cli cp web-1:/etc/os-release .
sternway-cli cp ./build.tar web-1:/srv/releases/ --overwrite

• A host or snippet is named by its label (exactly, then ignoring case) or its id. A label two hosts share is refused: use the id.
• run runs command snippets only, with {{$HOST}} and the other built-ins filled for each host, the same way Run on hosts › Collect results does. It shows in the app too.
• cp copies one file into a folder. A file already there is left alone unless you add --overwrite.
• --json prints the result as JSON for scripts.
• hosts leaves out the hosts of a team that blocks exports without encryption, and says on stderr how many it left out.

Commands run with sternway-cli run and files copied with cp are not recorded in session recordings or logs.

Exit status

0 done, 1 the command failed (or failed on a host), 2 a usage error, 3 the token was refused (unknown, revoked, expired or without the scope), 4 Sternway is not running or is locked.

How the command knows it is talking to Sternway

Each time it starts, the app listens under a new random name and writes it, with a fresh 32-byte key, into a file only you can read ($XDG_RUNTIME_DIR/sternway or ~/.sternway on Linux, ~/.sternway on macOS, %LOCALAPPDATA%\Sternway\cli on Windows). Before it sends your token, the command makes the app prove it holds that key; anything else that answers there gets “That is not the Sternway app” and nothing secret. On Windows the named pipe’s permissions have not been checked on a real machine.

Every command, scope and exit status: sternway-cli reference.