CLI — Subnomic Docs

subnomic is the command-line client for your workspace: sign in, deploy sites and services, open a terminal on a server and read the activity feed.

Install

curl -fsSL https://get.subnomic.com | bash

Sign in

subnomic login      # endpoint, email or username, password (and a 2FA code)
subnomic whoami     # the current user, workspace and role
subnomic logout     # revokes the session and clears local state

The session is stored in ~/.subnomic/config.json; point SUBNOMIC_CONFIG elsewhere to keep another one. The API endpoint defaults to https://api.subnomic.com and is remembered after login; override it with --api or SUBNOMIC_API. Expired sessions are refreshed on their own.

Commands

Command	What it does
`login`	Authenticate and store the session
`logout`	Revoke the session server-side and clear local state
`whoami`	Show the current user, workspace and role
`servers`	List servers with their online status
`ssh [server]`	Open an interactive terminal on a server, by name, hostname or id — or pick one from a list
`logs [--limit N]`	Print the recent workspace activity
`sites`	Create, deploy and roll back sites and services

Sites

From the directory you want to publish:

subnomic sites create              # asks for an address, writes subnomic.json
npm run build
subnomic sites deploy --prod       # prints the live URL on stdout

On a directory with no site linked, sites deploy offers to create one, so the first deploy can be a single command. The build output is remembered in subnomic.json; when it is not, it is detected — dist, build, out, .output/public, public, whichever holds an index.html. Pass --dir to say so yourself.

Command	What it does
`sites ls`	List the workspace’s sites (`--json` for structured output)
`sites create [<address>]`	Create a site and link this directory to it (`--name`, `--dir`, `--spa`, `--not-found`, `--no-link`)
`sites link [<address>]`	Link this directory to an existing site; picks one when no address is given
`sites deploy`	Publish the build output, as files or as a service (`--dir`, `--prod`, `--site`, `--create`, `--size`)
`sites rollback [--to <id>]`	Make a previous deployment live again; picks one when `--to` is omitted
`sites open`	Open the linked site in a browser
`sites rm --site <s> --yes`	Delete a site, its deployments and all of its files

Services

deploy publishes files unless it finds something to run, in which case the deployment becomes a service on a microVM of its own. Two shapes are recognised, in this order:

Found	Deployed as	Entrypoint
`.output/nitro.json` from a `node-server` build	`node`	the build’s own preview command
one Linux executable in `bin`, `dist`, `build`, `out` or the project root	`binary`	that file

Only Linux executables count, so the shell scripts in a repository root are never mistaken for a service.
A macOS or Windows binary is refused with the GOOS=linux line that fixes it, and the architecture of a Linux binary is printed.
A Nitro build for another platform (vercel, cloudflare-pages, …) is refused by name, unless it also produced a publishable site.
nuxt generate output deploys as files, and a directory with an index.html wins over a stray binary.

The first time a site is deployed as a service, deploy asks which size to run on and remembers the answer:

subnomic sites deploy --prod                # asks once, on a terminal
subnomic sites deploy --prod --size nano    # or say so and skip the question
subnomic sites deploy --prod --size ""      # hand the choice back to the platform

In CI

Authenticate with SUBNOMIC_TOKEN — a workspace API key — together with SUBNOMIC_API. Give a deploy job only the sites.deploy scope. --size needs sites.write, which that scope does not carry, so set the size once from the console. Without a terminal, --create only runs when it is given an address with --site.

URL=$(subnomic sites deploy --prod)

Only the URL goes to stdout; progress goes to stderr.

Terminal behaviour

The login form, pickers, spinners and upload bar appear only when stdin and stderr are both terminals, and they draw on stderr. Redirect either one and every command prints plain tab-separated tables on stdout and plain progress on stderr, and refuses instead of asking a question — so subnomic servers | awk and a CI job behave the same. Colour honours NO_COLOR. Cancelling a picker or a form prints cancelled and exits with status 130.