openbootdotdev · fullstackjam · Apr 19, 2026 · Apr 19, 2026
diff --git a/src/docs/cli-reference.md b/src/docs/cli-reference.md
diff --git a/src/docs/dotfiles-shell.md b/src/docs/dotfiles-shell.md
@@ -26,7 +26,7 @@ After installation, restart your terminal or run `source ~/.zshrc` to pick up th
 If you manage your shell config yourself:
 
 ```
-openboot --shell skip
+openboot install --shell skip
 ```
 
 ## Dotfiles
@@ -50,8 +50,8 @@ Control how OpenBoot handles dotfiles with the `--dotfiles` flag:
 | `skip` | Don't touch dotfiles |
 
 ```
-openboot --dotfiles link
-openboot --dotfiles skip
+openboot install --dotfiles link
+openboot install --dotfiles skip
 ```
 
 ### Setting Up Your Dotfiles Repo
@@ -97,7 +97,7 @@ OpenBoot applies a curated set of developer-friendly macOS settings. These are a
 If you prefer your current settings:
 
 ```
-openboot --macos skip
+openboot install --macos skip
 ```
 
 See [Config Options](/docs/config-options) for the complete list of macOS preferences you can configure.
diff --git a/src/docs/env-vars.md b/src/docs/env-vars.md
@@ -1,71 +1,62 @@
 ---
 title: Environment Variables
-description: All environment variables for the install script and CLI — version pinning, install directory, Git identity, and more.
+description: All environment variables the install script and openboot CLI understand.
 group: Reference
 order: 12
 ---
 
 # Environment Variables
 
-All environment variables that control the install script and the `openboot` CLI.
+Every environment variable OpenBoot reads. Short list — v1.0 kept things minimal.
 
-## Install Script Variables
+## Install script (`install.sh`)
 
-These are used when running the `curl | bash` install command. The install script installs OpenBoot via Homebrew (`brew install openbootdotdev/tap/openboot`).
+Used when you run `curl -fsSL openboot.dev/install.sh | bash`. The script installs OpenBoot via Homebrew (`brew install openbootdotdev/tap/openboot`).
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `OPENBOOT_VERSION` | Install a specific version instead of latest | Latest release |
+| `OPENBOOT_VERSION` | Install a specific version instead of latest | `latest` |
 | `OPENBOOT_DRY_RUN` | Set to `true` to preview without changes | — |
 
-### Examples
-
 Preview the install script without making changes:
 
 ```
 OPENBOOT_DRY_RUN=true curl -fsSL https://openboot.dev/install.sh | bash
 ```
 
-## CLI Variables
+## CLI (`openboot`)
 
-These are used by the `openboot` binary at runtime.
+Used by the `openboot` binary at runtime.
 
 | Variable | Description |
 |----------|-------------|
-| `OPENBOOT_GIT_NAME` | Git user name — **only read in `--silent` mode** (required if Git isn't configured) |
-| `OPENBOOT_GIT_EMAIL` | Git user email — **only read in `--silent` mode** (required if Git isn't configured) |
-| `OPENBOOT_PRESET` | Default preset to use (overridden by `--preset` flag) |
-| `OPENBOOT_USER` | Default remote config to use (overridden by `--user` flag) |
-| `OPENBOOT_DOTFILES` | Dotfiles repository URL (overridden by config's `dotfiles_repo`) |
-| `OPENBOOT_API_URL` | Override the API base URL (default: `https://openboot.dev`) |
-| `OPENBOOT_DISABLE_AUTOUPDATE` | Set to `1` to disable auto-update checks |
-
-### Examples
+| `OPENBOOT_GIT_NAME` | Git user name — **read only in `--silent` mode** (required if Git isn't already configured) |
+| `OPENBOOT_GIT_EMAIL` | Git user email — **read only in `--silent` mode** (required if Git isn't already configured) |
+| `OPENBOOT_PRESET` | Default preset. Overridden by `-p` / `--preset` |
+| `OPENBOOT_USER` | Default cloud config (alias or `user/slug`). Overridden by `-u` / `--user` |
 
 Silent install with Git identity:
 
 ```
 OPENBOOT_GIT_NAME="Your Name" OPENBOOT_GIT_EMAIL="you@example.com" \
-  openboot --preset developer --silent
+  openboot install --preset developer --silent
 ```
 
-Set a default preset so `openboot` always starts with it:
+Set a default preset so `openboot install` always starts with it:
 
 ```
 export OPENBOOT_PRESET=developer
-openboot  # launches TUI with developer preset pre-selected
+openboot install  # TUI opens with developer preset pre-selected
 ```
 
-## File Locations
+## File locations
 
-These aren't environment variables, but useful to know:
+Not environment variables, but useful to know.
 
-| Path | What's There |
+| Path | What's there |
 |------|-------------|
-| `~/.openboot/auth.json` | Auth token (after `openboot login` or snapshot upload) |
+| `~/.openboot/auth.json` | Auth token (after `openboot login` or publishing a snapshot) |
 | `~/.openboot/snapshot.json` | Local snapshot (when using `--local`) |
-| `~/.openboot/config.json` | Auto-update settings |
-| `~/.openboot/install_state.json` | Tracks what was installed and when |
-| `~/.openboot/state.json` | UI reminder state |
-| `~/.openboot/update_state.json` | Auto-update check state |
+| `~/.openboot/install_state.json` | What was installed on this machine, and when |
+| `~/.openboot/sync_source.json` | The cloud config this machine is synced to |
 | `~/.dotfiles/` | Cloned dotfiles repo (when configured) |
diff --git a/src/docs/faq.md b/src/docs/faq.md
@@ -9,7 +9,7 @@ order: 13
 
 ## Is OpenBoot free?
 
-Yes. Free and open source (MIT license). Create configs, snapshot your setup, share with your team—no cost. Team management features (org accounts, access controls) might have paid tiers later.
+Yes. Free and open source (MIT license). Create configs, snapshot your setup, share with your team — no cost. Team features (org accounts, access controls) may have paid tiers later.
 
 ## Why not just use Homebrew directly?
 
@@ -19,32 +19,32 @@ If you're fine managing those separately, you don't need this. If you'd rather a
 
 ## Should I use Homebrew or the one-line installer?
 
-**Use Homebrew** (`brew install openboot`) if you:
+**Use Homebrew** (`brew install openbootdotdev/tap/openboot`) if you:
 - Already have Homebrew installed
 - Want cleaner updates (`brew upgrade openboot`)
-- Prefer package managers and the OpenBoot CLI over ad-hoc scripts
+- Prefer package managers over ad-hoc scripts
 
 **Use the one-line installer** if you:
 - Don't have Homebrew yet (it installs Homebrew for you)
 - Want the absolute fastest setup on a fresh Mac
-- Are running in CI/automation environments
+- Are running in CI / automation environments
 
 Both methods install the exact same binary.
 
 ## Is the one-line installer safe?
 
 Fair question. Here's how it works:
 
-- Install script is open source—review it at [github.com/openbootdotdev/openboot](https://github.com/openbootdotdev/openboot)
+- Install script is open source — review it at [github.com/openbootdotdev/openboot](https://github.com/openbootdotdev/openboot/blob/main/scripts/install.sh)
 - Hosted on openboot.dev (Cloudflare Workers), served over HTTPS
-- Zero telemetry—no analytics, no tracking, nothing phones home
+- Zero telemetry — no analytics, no tracking, nothing phones home
 - Installs OpenBoot via Homebrew (`brew install openbootdotdev/tap/openboot`), which handles integrity verification
 - You can inspect the script before running it:
 
 ```bash
 curl -fsSL https://openboot.dev/install.sh > install.sh
-cat install.sh  # Review the script
-bash install.sh  # Run it after review
+cat install.sh
+bash install.sh
 ```
 
 If you prefer, install via Homebrew instead (see above).
@@ -54,18 +54,28 @@ If you prefer, install via Homebrew instead (see above).
 If you share a config publicly on the Explore page, we display an install count. This is **not telemetry** in the traditional sense:
 
 - **Anonymous** — we don't track who installed it, only that someone did
-- **Opt-in** — only happens when you actively set visibility to "Public"
-- **No personal data** — no IP addresses, no user agents, no system info collected
-- **Zero tracking** — we don't follow your behavior, clicks, or usage patterns
+- **Opt-in** — only happens when visibility is set to "Public"
+- **No personal data** — no IP addresses, no user agents, no system info
+- **Zero tracking** — no behavior, clicks, or usage patterns
 
-"Zero telemetry" means the OpenBoot CLI never reports back to us. It doesn't track what you install, what commands you run, or any system information. Install counts are simply a counter for configs you chose to share publicly with the community.
+"Zero telemetry" means the OpenBoot CLI never reports back to us. It doesn't track what you install, what commands you run, or any system information. Install counts are simply a counter for configs you chose to share publicly.
 
-Think of it like GitHub's star count — it shows popularity, but doesn't track individual users.
+Think of it like GitHub's star count — shows popularity, doesn't track individuals.
 
 ## What if I already have Homebrew?
 
 OpenBoot detects existing Homebrew installs and skips the setup. It also skips already-installed packages — only new ones get installed. Re-running is fast and safe.
 
+## Does OpenBoot uninstall packages?
+
+No — by design. As of v1.0, OpenBoot is add-only:
+
+- `openboot install` never removes packages, even if they're not in the config you're installing from
+- There is no `openboot clean` or `openboot uninstall`
+- To remove something, run Homebrew directly: `brew uninstall <package>`
+
+This makes re-running `openboot install` always safe — you never lose packages you added manually.
+
 ## Can I use it without an account?
 
 Yes. No account needed for:
@@ -76,7 +86,7 @@ Yes. No account needed for:
 
 An account (GitHub or Google OAuth) is needed to:
 
-- Upload configs to openboot.dev and share them via URL
+- Publish configs to openboot.dev (`openboot snapshot --publish`)
 - Install private configs (run `openboot login` first)
 
 ## How do I update OpenBoot?
@@ -85,20 +95,16 @@ An account (GitHub or Google OAuth) is needed to:
 brew upgrade openboot
 ```
 
-Or use the built-in self-update:
+OpenBoot also does a lightweight auto-update check when you run `install`.
 
-```bash
-openboot update --self
-```
+The old `openboot update --self` command was removed in v1.0 — use `brew upgrade` instead.
 
-Your configs, snapshots, and auth tokens are unaffected by updates.
+Your configs, snapshots, and auth tokens are unaffected by upgrades.
 
 ## How do I uninstall OpenBoot?
 
 ### 1. Remove the binary
 
-Both installation methods use Homebrew, so the uninstall is the same:
-
 ```bash
 brew uninstall openboot
 brew untap openbootdotdev/tap
@@ -110,22 +116,21 @@ brew untap openbootdotdev/tap
 rm -rf ~/.openboot
 ```
 
-This deletes your auth token, local snapshots, install state, and update config. If you want to keep anything, back it up first — see [File Locations](/docs/env-vars#file-locations) for what's in there.
+This deletes your auth token, local snapshots, install state, and sync source. See [File Locations](/docs/env-vars#file-locations) for what's in there if you want to keep something.
 
 ### 3. Clean up shell config (optional)
 
-If OpenBoot configured your shell, open `~/.zshrc` and remove the block starting with `# OpenBoot additions` — it includes Homebrew init, PATH changes, CLI aliases, and tool integrations. If you're not sure which lines, look for the block between `# OpenBoot additions` and the next blank line or section.
+If OpenBoot configured your shell, open `~/.zshrc` and remove the block starting with `# OpenBoot additions` — it includes Homebrew init, PATH changes, CLI aliases, and tool integrations.
 
-If you used dotfiles linking, OpenBoot created `.openboot.bak` backups of your original files. To restore them:
+If you used dotfiles linking, OpenBoot created `.openboot.bak` backups of your original files. To restore:
 
 ```bash
-# Example: restore a backed-up .zshrc
 mv ~/.zshrc.openboot.bak ~/.zshrc
 ```
 
 ### 4. Packages and apps (optional)
 
-OpenBoot doesn't remove Homebrew packages or casks when you uninstall it — they're yours to keep. If you want to remove packages that were installed via OpenBoot, use `brew uninstall <package>` individually.
+OpenBoot doesn't remove Homebrew packages when you uninstall it — they're yours to keep. To remove packages installed via OpenBoot, use `brew uninstall <package>` individually.
 
 ## Where is my data stored?
 
@@ -134,7 +139,7 @@ OpenBoot doesn't remove Homebrew packages or casks when you uninstall it — the
 | Configs & user data | Cloudflare D1 on openboot.dev |
 | Auth token | `~/.openboot/auth.json` (local) |
 | Local snapshots | `~/.openboot/snapshot.json` (local) |
-| OpenBoot binary | Managed by Homebrew (run `which openboot` to find it) |
+| OpenBoot binary | Managed by Homebrew (`which openboot`) |
 
 Configs are **unlisted** by default — not listed on your profile, but the install URL works if shared. You can set them to **public** (listed on profile) or **private** (requires authentication to install). See [Custom Configs — Visibility](/docs/custom-configs#visibility) for details.
 
@@ -154,6 +159,6 @@ Not yet. OpenBoot is macOS-only. Linux support is being explored.
 
 ## Can I use it with my existing dotfiles?
 
-Yes. Set your dotfiles repo URL in your config and OpenBoot will clone and link it with GNU Stow. See [Dotfiles & Shell](/docs/dotfiles-shell) for details.
+Yes. Set your dotfiles repo URL in your config and OpenBoot will clone and link it with GNU Stow. See [Dotfiles & Shell](/docs/dotfiles-shell).
 
 Your existing dotfiles repo structure works as-is — OpenBoot doesn't require any special format.