diff --git a/CHANGELOG.md b/CHANGELOG.md
index efb246185..2decde1b3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@
 - Onboarding/Models: add catalog-backed default model picker to onboarding + configure. (#611) — thanks @jonasjancarik.
 - Agents/OpenCode Zen: update fallback models + defaults, keep legacy alias mappings. (#669) — thanks @magimetal.
 - Providers: unify group history context wrappers across providers with per-provider/per-account `historyLimit` overrides (fallback to `messages.groupChat.historyLimit`). Set `0` to disable. (#672) — thanks @steipete.
+- CLI: add `clawdbot update` (safe-ish git checkout update) + `--update` shorthand. (#673) — thanks @fm1randa.
 
 ### Fixes
 - Auto-reply: prefer `RawBody` for command/directive parsing (WhatsApp + Discord) and prevent fallback runs from clobbering concurrent session updates. (#643) — thanks @mcinteerj.
diff --git a/docs/cli/index.md b/docs/cli/index.md
index 7ea3b5056..cd499b273 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -14,6 +14,7 @@ This page describes the current CLI behavior. If commands change, update this do
 - `--dev`: isolate state under `~/.clawdbot-dev` and shift default ports.
 - `--profile <name>`: isolate state under `~/.clawdbot-<name>`.
 - `--no-color`: disable ANSI colors.
+- `--update`: shorthand for `clawdbot update` (source installs only).
 - `-V`, `--version`, `-v`: print version and exit.
 
 ## Output styling
@@ -47,6 +48,7 @@ clawdbot [--dev] [--profile <name>] <command>
   onboard
   configure (alias: config)
   doctor
+  update
   providers
     list
     status
diff --git a/docs/cli/update.md b/docs/cli/update.md
new file mode 100644
index 000000000..52a28abf5
--- /dev/null
+++ b/docs/cli/update.md
@@ -0,0 +1,47 @@
+---
+summary: "CLI reference for `clawdbot update` (safe-ish source update + optional daemon restart)"
+read_when:
+  - You want to update a source checkout safely
+  - You need to understand `--update` shorthand behavior
+---
+
+# `clawdbot update`
+
+Safely update a **source checkout** (git install) of Clawdbot.
+
+If you installed via **npm/pnpm** (global install, no git metadata), use the package manager flow in [Updating](/install/updating).
+
+## Usage
+
+```bash
+clawdbot update
+clawdbot update --restart
+clawdbot update --json
+clawdbot --update
+```
+
+## Options
+
+- `--restart`: restart the Gateway daemon after a successful update.
+- `--json`: print machine-readable `UpdateRunResult` JSON.
+- `--timeout <seconds>`: per-step timeout (default is 1200s).
+
+## What it does (git checkout)
+
+High-level:
+
+1. Requires a clean worktree (no uncommitted changes).
+2. Fetches and rebases against `@{upstream}`.
+3. Installs deps (pnpm/bun/npm depending on the checkout).
+4. Builds + builds the Control UI.
+5. Runs `clawdbot doctor` as the final “safe update” check.
+
+## `--update` shorthand
+
+`clawdbot --update` rewrites to `clawdbot update` (useful for shells and launcher scripts).
+
+## See also
+
+- [Updating](/install/updating)
+- [CLI reference](/cli)
+
diff --git a/docs/install/updating.md b/docs/install/updating.md
index c387a75ff..61db8509e 100644
--- a/docs/install/updating.md
+++ b/docs/install/updating.md
@@ -42,10 +42,25 @@ Notes:
 - If your Gateway runs as a service, `clawdbot daemon restart` is preferred over killing PIDs.
 - If you’re pinned to a specific version, see “Rollback / pinning” below.
 
+## Update (`clawdbot update`)
+
+For **source installs** (git checkout), prefer:
+
+```bash
+clawdbot update --restart
+```
+
+It runs a safe-ish update flow:
+- Requires a clean worktree.
+- Fetches + rebases against the configured upstream.
+- Installs deps, builds, builds the Control UI, and runs `clawdbot doctor`.
+
+If you installed via **npm/pnpm** (no git metadata), `clawdbot update` will skip. Use “Update (npm install)” instead.
+
 ## Update (Control UI / RPC)
 
 The Control UI has **Update & Restart** (RPC: `update.run`). It:
-1) Runs a git update (clean rebase) or package manager update.
+1) Runs the same source-update flow as `clawdbot update` (git checkout only).
 2) Writes a restart sentinel with a structured report (stdout/stderr tail).
 3) Restarts the gateway and pings the last active session with the report.
 
@@ -55,6 +70,14 @@ If the rebase fails, the gateway aborts and restarts without applying the update
 
 From the repo checkout:
 
+Preferred:
+
+```bash
+clawdbot update
+```
+
+Manual (equivalent-ish):
+
 ```bash
 git pull
 pnpm install