# @nippyhost/cli

Publish websites to [nippy.host](https://nippy.host) from the terminal, CI,
or Claude. Drop a folder, get a link — photos become a gallery, files become
a download page, sites just work. Links don't expire.

```bash
npx @nippyhost/cli login                       # one-time: approve in your browser, done
npx @nippyhost/cli deploy ./dist --site demo   # → https://demo.nippy.site
```

The bin is called `nippy`, so a global install gives you the short form:

```bash
npm i -g @nippyhost/cli
nippy deploy ./photos --site henderson-wedding
```

## Commands

| Command | What it does |
|---|---|
| `nippy login` | Opens your browser to approve the CLI on nippy.host (OAuth, no copy-paste) and stores the resulting scoped token in `~/.config/nippy/` (chmod 600). `--paste` for headless/SSH machines |
| `nippy deploy [path] --site <name>` | Publish a folder, single file, or zip. Existing site → updated **in place, same URL**; missing → created. `--new` forces a fresh site, `--json` for scripts |
| `nippy sites` / `nippy sites info <name>` | List sites / show one site's files |
| `nippy open <name>` | Open `https://<name>.nippy.site` |
| `nippy whoami` | Which credential is active, and does it work |
| `nippy mcp install [--client …]` | Add the MCP server to Claude Desktop, Claude Code, or Cursor |
| `nippy mcp serve` | Run the MCP server on stdio (assistants call this) |

## Use from Claude (MCP)

**On claude.ai (or any client that takes a remote MCP server): no install.**
Add a custom connector with the URL `https://api.nippy.host/mcp` — approval
is the same OAuth consent screen as `nippy login` (Streamable HTTP,
OAuth 2.1 + PKCE, dynamic client registration). The remote server has the
same tools plus `start_upload` / `start_revision` / `finalize_upload` /
`abort_upload` for files of any type and size.

**Claude Desktop, Claude Code, or Cursor (local, stdio):**

```bash
npx nippy-mcp                       # Claude Desktop
npx nippy-mcp --client claude-code  # Claude Code
npx nippy-mcp --client cursor      # Cursor
```

Then just ask: *"publish this page on Nippy"*. Tools include `publish_site`,
`update_site` (same URL, surgical file changes), `list_sites`,
`list_permanent_sites`, `read_site_file`, `check_site_name`, plus paid-plan
tools for passwords, SEO meta, search-indexing, and visitor analytics. Small
binaries (images, PDFs, fonts) go inline with `encoding: "base64"` — up to
4 MB per file, 12 MB per call; use `nippy deploy` for anything bigger.

### Previews

Assistants iterate, and most drafts are throwaway — so publishing has two
verbs. `publish_preview` puts a draft at `<slug>.preview.nippy.site`: it
expires 24 hours after its last update, is never indexed, and **doesn't use
up one of your site slots**. `update_preview` revises it (and resets the
clock), `list_previews` shows what's active with time remaining, and
`discard_preview` throws one away.

When a draft is worth keeping, `promote` makes it permanent — either as a new
site or by replacing an existing site's contents. The preview URL doesn't die:
it becomes a permanent redirect to the site, so a link you already shared keeps
working.

`publish_site` is unchanged and still means "permanent, counts against your
plan". Free accounts hold 5 active previews at a time; paid plans are
unlimited.

## Use in CI

```yaml
# any CI — the token comes from a secret
- run: NIPPY_TOKEN=${{ secrets.NIPPY_TOKEN }} npx @nippyhost/cli deploy ./dist --site docs --json
```

`NIPPY_TOKEN` always overrides the stored login.

## Tokens & security

- `nippy login` uses the same OAuth consent screen as Nippy's AI connectors;
  the login shows up under **Connected apps** in
  [Settings → API & MCP](https://nippy.host/settings/api-tokens), where you can
  disconnect it any time. For CI, create a token there instead — free account
  works (1 live site, 25 MB, no card).
- Tokens are **scoped** (deploy/read/manage/analytics) and revocable. They can never delete sites, touch billing, or manage your account — those need the dashboard.
- Plan limits are enforced server-side and reported honestly: hitting one tells you exactly what the limit is.

## Notes

- A folder without `index.html` becomes a gallery (all images) or a tidy
  download page (mixed files) automatically.
- Zips are unpacked locally before upload.
- Site names are subdomains of `nippy.site`: lowercase letters, digits,
  hyphens. If a name's taken you get the next free suffix back.

MIT · [nippy.host](https://nippy.host) · [help](https://nippy.host/help)

---

## About this repository

This is the **source mirror** for [`@nippyhost/cli`](https://www.npmjs.com/package/@nippyhost/cli)
and [`nippy-mcp`](https://www.npmjs.com/package/nippy-mcp). Development happens
in the Nippy monorepo (where the API client is generated and the test suites
run); the source here is published for reading, issues, and releases.

- `cli/` — the `nippy` command + MCP server (`@nippyhost/cli`)
- `sdk/` — the publish SDK: init → presigned upload → finalize choreography
- `upload-rules/` — client-side validation rules shared with the platform

**Bugs and feature requests → [Issues](https://github.com/nippyhost/cli/issues).**