# ws command reference

> Every ws command and option, what each does, and examples of its output.

## Commands

The first command you run signs you in through your browser. Every command run inside a site's folder works on that site.

| Command | What it does |
|---|---|
| `ws new "Name"` | Makes a site with that display name and writes a starter folder. Options: `--subdomain`, `--languages`, `--time-zone`. The folder is a Git clone of the site's repository, with one starter commit. `--here` makes the site from the files already in this folder, which must not be a Git repository yet: it runs `git init` and commits them. `ws` keeps the site's ID in `.ws/`, which Git ignores in this clone (`.git/info/exclude`). |
| `ws preview` | Builds the folder on the platform and prints a private link, with a QR code when it writes to a terminal. A missing translation does not stop it: the page shows the main language there, and `ws preview` lists what is missing, which `ws push` refuses. Anyone with the link can open the preview for the site's preview length, 7 days unless changed with `ws site --preview-expires`: opening it signs that browser in to the preview. Run it again to update the same link and start that length again. `--new-link` replaces the link, and every browser the old link signed in loses access. |
| `ws preview --watch` | Keeps running. Each time you save a file, it sends only the changed files, and every open page of the preview updates. Stop it with Ctrl+C. |
| `ws clone NAME` | Makes a new folder, named after the subdomain or given as a second argument, with a Git clone of the site with that subdomain, history included, and sets up Git to ask `ws` for its password. It writes a `.gitignore` for the files a site leaves out when the repository has none, to commit. It never writes into a folder that exists. |
| `ws push` | Pushes the checked-out commit to your own branch, `push/<builder>`, never to `main`. It refuses a folder with uncommitted changes. The platform moves `main` to the commit once its version is saved. The push makes a new version, publishes a sample at once, and runs its checks in the background. A bought site waits for the checks to pass. Only committed work is sent. If `main` has newer commits, the push is refused: run `git pull`, then `ws push`. `--request N` answers request N; `--needs-approval` sends the change to the owner instead (see [Approval](https://docs.websitestrategy.com/reference/checks-and-approval/#approval)). |
| `ws publish` | In a clone, the same as `ws push`. |
| `ws git-credential` | Used by Git, never typed. Git runs it to get a short-lived password for the site's repository, so you never see or store one. |
| `ws pull` | In a Git clone, prints "This folder is a Git clone. Run git pull." Use `git pull` to bring in newer versions. |
| `ws status` | Shows which version the folder holds, whether a newer one exists, whether there are unpublished commits or uncommitted changes, any change waiting for approval, and check results for the newest version. `git status` lists the files. |
| `ws versions` | Lists every version, newest first, with who made it, its note and, where the owner approved it, when. |
| `ws undo N` | Makes a new version that reverses only what version N changed, and publishes it. Takes `--request N`. |
| `ws rollback N` | Makes a new version with the files and settings of version N, after you confirm, and publishes it. |
| `ws withdraw A1` | Takes back change A1, which is waiting for approval, before the owner approves it, and puts its changes back into this folder. |
| `ws requests` | Lists the owner's open requests; `--all` lists them for every site you have published a version of. `ws requests N` shows one, with the file and line it points at. |
| `ws sources` | Lists the sources of live data. `ws sources connect NAME PLACE` links one to this site, such as `ws sources connect weather "Mahone Bay NS"`. |
| `ws libraries` | Lists the shared libraries, such as three.js, with an import map to paste into a page. |
| `ws site` | Shows the site's settings. Change them with `--name`, `--subdomain`, `--languages`, `--time-zone`, `--form-email`, `--approval`, `--expires` or `--preview-expires`. A change to a setting makes a new version, like a change to a file. |
| `ws login`, `ws logout` | Sign in or out ahead of time. `ws login --device` is for a computer with no browser. |

Every command takes `--json` for output an agent can read, and `--profile` to choose the environment: `production`, `staging` or `local` ([part 1](https://docs.websitestrategy.com/guides/install-ws/#choose-the-environment)). `ws profile show` prints the one in use, and `ws version` prints the version of `ws`. No command stops to ask a question when its output goes to another program; `ws rollback` then needs `--yes`.

### Examples

```
$ ws login --device
On another device, open https://outport.app/oauth/device and enter 55NB-64GH.
Signed in as Jordan Bell.
```

```
$ ws site --name "Saltmere Marina & Boatyard"
Published version 7 of "Saltmere Marina": the display name changed.
```

```
$ ws site --expires 60d
The sample's private link now lasts 60 days from each publish.
Published version 8 of "Saltmere Marina": how long the link lasts changed.
```

```
$ ws libraries
three   0.181.0   /_ws/lib/three@0.181.0/three.module.js
gsap    3.13.0    /_ws/lib/gsap@3.13.0/index.js
Import map: <script type="importmap">{"imports":{"three":"/_ws/lib/three@0.181.0/three.module.js"}}</script>
```

```
$ ws status --json
{"site":"saltmere-marina","version":8,"newest":8,"unpublished_commits":false,"uncommitted_changes":true,"behind_published":false,"waiting_for_approval":[],"checkStatus":{"state":"running","lines":["Automatic checks for version 8 are running."]}}
```

If `ws push` loses its connection, run it again. The platform knows the first try by an ID that `ws` sent with it, so the second try reports the version the first one made instead of making another.

### How watching works

`ws preview --watch` follows the model of Shopify's `shopify theme dev`, which sends a theme's changed files to a hosted copy of the store as you save them. `ws` notices each saved file and waits about 200 milliseconds, so a save of several files counts as one. It then sends only the files that changed. The platform rebuilds the pages those files affect and tells every browser that has the preview open: "build 14 of the preview is ready, and these files changed". Each `ws preview`, and each save while watching, makes a new numbered build of the preview; builds are not versions. A changed style sheet is swapped in place, with no reload. Any other change reloads the page, at the same scroll position. Phones get the update too, because the message comes from the platform, not from your computer. You never run the platform on your own computer.

