# Updates

sitemd checks for new versions in the background and notifies you when one is available — in the CLI, on dev server startup, and in every `sitemd_status` response your AI agent sees.

## Proactive Notifications

You don't need to remember to check for updates. sitemd surfaces them wherever you already are.

**Interactive CLI (`sitemd`)** — when you open the menu, an update line appears between the status block and the menu if a newer version is available:

```text
  Project:   My Site
  Pages:     12 files
  Auth:      you@example.com
  Deploy:    example.com → cloudflare

  Update: v1.0.0 → v1.2.0  sitemd update
```

**Dev server (`sitemd launch`)** — the startup banner shows a notification if an update is waiting:

```text
  Dev server running at http://localhost:4747
  Press Ctrl+C to stop
  Update available: v1.0.0 → v1.2.0  sitemd update
```

**AI agents** — every `sitemd_status` MCP response includes a `version` block. When an update is available, it appears as the first action item so the agent can mention it proactively:

```json
{
  "version": {
    "current": "1.0.0",
    "latest": "1.2.0",
    "hasUpdate": true,
    "releaseNotes": "### What's new in 1.2.0\n- ...",
    "releaseUrl": "https://github.com/sitemd-cc/sitemd/releases/tag/v1.2.0"
  },
  "actions": [
    { "command": "update", "description": "Update available: v1.0.0 → v1.2.0" }
  ]
}
```

Notifications are instant — they read from a local cache, adding zero latency to any command.

## How the Cache Works

sitemd fetches version info at most once per hour and stores it at `~/.sitemd/update-check.json`. The first CLI or server invocation after the cache expires triggers a background refresh — no waiting, no blocking. The next invocation picks up the result.

```json
{
  "latest": "1.2.0",
  "checkedAt": "2026-03-17T10:00:00.000Z",
  "releaseNotes": "### What's new in 1.2.0\n- Website cloning via /clone\n- Auto-update with in-place engine replacement",
  "releaseUrl": "https://github.com/sitemd-cc/sitemd/releases/tag/v1.2.0"
}
```

If the network is unavailable, the check is skipped silently. No error, no disruption.

## Manual Update Check

Run `sitemd update` at any time for a fresh check and full release notes:

```bash
sitemd update
```

Output when an update is available:

```text
  Current version: 1.0.0
  Checking for updates...

  Update available: 1.0.0 → 1.2.0

  ### What's new in 1.2.0
  - Website cloning via /clone skill
  - Auto-update with in-place engine replacement
  - Proactive update notifications in CLI and MCP

  Release: https://github.com/sitemd-cc/sitemd/releases/tag/v1.2.0

  Update engine and theme in this project now? (yes/no):
```

If you're already on the latest version:

```text
  Up to date! v1.2.0
```

## Self-Update

When you run `sitemd update` from inside a project directory and confirm, sitemd downloads the latest release and replaces `engine/` and `theme/` in-place:

```text
  Downloading v1.2.0...
  Updating engine...
  Updating theme...

  Updated! v1.2.0
  engine/ and theme/ replaced. pages/, settings/, and media/ unchanged.

  If you have an MCP server running, restart it to use the new version.
```

**What gets replaced:** `engine/` and `theme/`

**What is never touched:** `pages/`, `settings/`, `media/`, `.mcp.json`, `package.json` content

**Project config safe:** `.sitemd/config.json` (your deployment credentials and service keys) lives outside `engine/` and `theme/`, so it's never affected by updates.

### npm installs

If you installed sitemd globally via npm, update the global package first:

```bash
npm update -g @sitemd-cc/sitemd
```

Then run `sitemd update` from your project directory to apply the new engine and theme files locally.

### git clones

If your project is a git clone, you can `git pull` to update, or use `sitemd update` for the in-place replacement. Both work.

## MCP Tool

AI agents can explicitly check for updates with the `sitemd_update_check` tool. Unlike the passive version info in `sitemd_status`, this always fetches fresh data from the registry:

```text
sitemd_update_check()
→ { current, latest, hasUpdate, releaseNotes, releaseUrl }
```

Use `sitemd_status` for passive awareness. Use `sitemd_update_check` when the user explicitly asks whether a new version is available.

Note: self-update is not available via MCP. Replacing the engine while the MCP server is running would break the active session. Run `sitemd update` from the CLI instead, then restart the MCP server.

## Related

- [CLI Config](/docs/cli-config) — managing backend credentials and service config
- [Getting Started](/docs/getting-started) — initial installation
- [Feedback](/docs/feedback) — reporting issues or requesting features