sternway-cli

sternway-cli uses the running desktop app from a terminal or a script, over a socket (Linux, macOS) or a named pipe (Windows) only your user can reach. It never opens a network port and does nothing while the app is locked. How to set it up and use it: Use the command line.

Usage

This is what sternway-cli help prints:

Usage: sternway-cli <command> [options]

Commands (each needs a token with its scope; make one in Sternway › Settings › CLI tokens):
  whoami                                  the token's name, scopes and expiry
  hosts                                   list the saved hosts (scope: hosts)
  connect <host>                          open a terminal to a host in the app (scope: connect)
  run <snippet> --hosts <a,b,…> [--var name=value]…
                                          run a saved snippet on hosts and print what each printed (scope: run)
  cp <host>:<file> <local folder>         copy a file from a host (scope: sftp)
  cp <local file> <host>:<folder>         copy a file to a host (scope: sftp, not read-only)
  help, version

A host or snippet is named by its label or its id. Options:
  --json             print the result as JSON
  --overwrite        cp: replace a file that is already there (default: leave it and say so)
  --token-file <f>   read the token from a file only you can read (default: the STERNWAY_TOKEN variable)

The token is read from the STERNWAY_TOKEN environment variable, or from the file --token-file names. It is never taken from the command line.

Scopes

A token is made in Settings › CLI tokens with one or more scopes. whoami needs none.

Scope	Allows
hosts	sternway-cli hosts
connect	sternway-cli connect <host>
run	sternway-cli run <snippet> --hosts <a,b,…>
sftp	sternway-cli cp <host>:<file> <local folder>, sternway-cli cp <local file> <host>:<folder>
read-only	Takes away sternway-cli connect <host>, sternway-cli run <snippet> --hosts <a,b,…>, sternway-cli cp <local file> <host>:<folder> and a download with --overwrite, whatever else the token has.

Errors and exit status

The command exits 0 when it is done and 2 on a usage error it finds itself. When the app refuses or fails a request, the code it answers decides the exit status:

Code	Exit status	Meaning
BAD_REQUEST	2	The command line or a value in it cannot be used (an unknown option, a path with .., too many hosts).
UNAUTHORIZED	3	No token, or a token this app did not make or has revoked.
EXPIRED	3	The token has expired. Make a new one.
FORBIDDEN	3	The token does not have the scope the command needs, or it is read-only and the command changes something.
LOCKED	4	Sternway is locked. Unlock it and run the command again.
NOT_FOUND	1	No host or snippet has that label or id.
AMBIGUOUS	1	Two hosts (or snippets) share that label: name it by its id.
FAILED	1	The command ran and failed, or it failed on at least one host.

When Sternway is not running, or something else answers where it listens, the command exits 4 and sends nothing.

Limits

• A token starts with stw_ and always expires, at most 366 days after it was made. A profile holds at most 50 tokens.
• run takes at most 200 hosts in one request.