> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sontairo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sontairo CLI

> Deploy static sites to Sontairo Hosting from your terminal

The `sontairo` CLI deploys static sites to Sontairo Hosting: link a directory to a site, run a security and performance doctor, and ship to production or a preview. It has zero dependencies and requires Node.js 18+.

## Install

```bash theme={null}
npm i -g sontairo
```

The CLI ships from the `cli/` package of the Sontairo repository and exposes a single `sontairo` binary.

## Commands

```
sontairo — deploy static sites to Sontairo Hosting

Commands:
  sontairo link <siteId>    link this directory to a site
  sontairo doctor           run security + performance checks
  sontairo deploy           doctor + deploy to production
  sontairo deploy --preview doctor + deploy a preview
```

### `sontairo link <siteId>`

Links the current directory to a site. The site ID (starts with `site_`) is shown in the site's Settings. Linking writes a `sontairo.json` file in the directory recording the `siteId`.

### `sontairo doctor`

Runs security and performance checks on the current directory without deploying. Blocking issues (✖) must be fixed before a deploy will proceed; warnings (▲) are advisory.

**Blocking checks:**

| Check          | Rule                                                                                                                                               |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTML entry     | The directory must contain an HTML file (`index.html`)                                                                                             |
| File count     | Maximum 200 files                                                                                                                                  |
| Total size     | Maximum 8 MB                                                                                                                                       |
| Per-file size  | Maximum 2 MB per file                                                                                                                              |
| `.env` files   | Env files must not be deployed                                                                                                                     |
| Leaked secrets | Live Stripe secret keys, AWS access key IDs, private keys, GitHub personal access tokens, and Google API keys found in text files block the deploy |

**Warnings:**

| Check               | Rule                                                                         |
| ------------------- | ---------------------------------------------------------------------------- |
| Mixed content       | Insecure `http://` references in HTML — browsers will block or warn on these |
| Missing viewport    | HTML pages without `<meta name="viewport">` render poorly on phones          |
| Missing description | An `index.html` without `<meta name="description">` hurts search results     |
| `document.write()`  | Blocks rendering                                                             |
| Oversized images    | Images over 500 KB — compress or convert to WebP/AVIF                        |
| Oversized scripts   | Scripts over 1 MB — consider splitting or minifying                          |

### `sontairo deploy`

Deploys the current directory to production:

1. **Auth** — reads the site ID from `sontairo.json` and the deploy token from the `SONTAIRO_DEPLOY_TOKEN` environment variable
2. **Doctor** — runs all checks; any blocking issue stops the deploy
3. **Upload** — sends your files to Sontairo Hosting
4. On success, prints the live URL: `✓ Deployed <n> files — live at <url>`

Add `--preview` to deploy to the site's preview target instead of production.

The CLI automatically skips `node_modules`, `.git`, build caches, OS junk files, `sontairo.json`, and all `.env*` files.

## Deploy tokens

Deploys authenticate with a per-site deploy token instead of your login session:

* Generate a token in the site's **Settings → Deploy token**. Generating requires the **ADMIN** role.
* The token is **shown once** — store it immediately (for example in your CI secrets).
* Set it as the `SONTAIRO_DEPLOY_TOKEN` environment variable where you run `sontairo deploy`.
* Generating a new token **invalidates the previous one** — use this to rotate a token you suspect is compromised.

<Warning>
  Treat deploy tokens like passwords. Anyone with the token can deploy to your site. If a token leaks, rotate it from Settings → Deploy token.
</Warning>