boxel-cli: add boxel realm milestone command

packages/boxel-cli/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "boxel-cli",
   "description": "Claude Code skills for working with Boxel realms via @cardstack/boxel-cli. Requires @cardstack/boxel-cli >= 0.0.1 installed on PATH (npm install -g @cardstack/boxel-cli).",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "author": {
     "name": "Cardstack",
     "url": "https://boxel.ai"

packages/boxel-cli/plugin/skills/realm-sync/SKILL.md

@@ -21,7 +21,8 @@ Wraps the `boxel realm` subcommands that move data between a local directory and
 | "push my changes" / "deploy" | `boxel realm push <local-dir> <realm-url>` |
 | "download a realm" / "pull it locally" | `boxel realm pull <realm-url> <local-dir>` |
 | "sync" / "keep them in lockstep" | `boxel realm sync <local-dir> <realm-url> --prefer-newest` (or `--prefer-local` / `--prefer-remote`) |
-| "watch the realm" / "live-mirror remote changes locally" | `boxel realm watch <realm-url> <local-dir>` |
+| "watch the realm" / "live-mirror remote changes locally" | `boxel realm watch start <realm-url> <local-dir>` |
+| "stop watching" / "kill the watcher" | `boxel realm watch stop <local-dir>` |
 | "make a new realm" | `boxel realm create <realm-name> <display-name>` |
 | "delete this realm" / "remove a realm" | `boxel realm remove <realm-url>` |
 | "what realms do I have access to" | `boxel realm list` |
@@ -66,9 +67,24 @@ Bidirectional sync between a local directory and a Boxel realm
 - `--dry-run` — Preview without making changes
 - `--realm-secret-seed` — Administrative auth: prompt for a realm secret seed and mint a JWT locally instead of using a Matrix profile (env: BOXEL_REALM_SECRET_SEED)
 
-### `boxel realm watch`
+### `boxel realm watch start <realm-url> <local-dir>`
 
-Watch a Boxel realm; subcommands manage watch processes
+Start watching a Boxel realm for server-side changes and pull them into a local directory
+
+**Arguments:**
+
+- `<realm-url>` — The URL of the realm to watch (e.g., https://app.boxel.ai/demo/)
+- `<local-dir>` — The local directory to write changes into
+
+**Options:**
+
+- `-i, --interval <seconds>` — Polling interval in seconds
+- `-d, --debounce <seconds>` — Seconds to wait after a burst of changes before applying them
+- `--realm-secret-seed` — Administrative auth: prompt for a realm secret seed and mint a JWT locally instead of using a Matrix profile (env: BOXEL_REALM_SECRET_SEED)
+
+### `boxel realm watch stop`
+
+Stop all running boxel realm watch processes
 
 ### `boxel realm push <local-dir> <realm-url>`
 

packages/boxel-cli/scripts/build-plugin.ts

@@ -26,7 +26,8 @@ const SKILL_SPECS: SkillSpec[] = [
     skill: 'realm-sync',
     commands: [
       'realm sync',
-      'realm watch',
+      'realm watch start',
+      'realm watch stop',
       'realm push',
       'realm pull',
       'realm create',

packages/boxel-cli/src/commands/realm/index.ts

@@ -3,6 +3,7 @@ import { registerCancelIndexingCommand } from './cancel-indexing';
 import { registerCreateCommand } from './create';
 import { registerHistoryCommand } from './history';
 import { registerListCommand } from './list';
+import { registerMilestoneCommand } from './milestone';
 import { registerPullCommand } from './pull';
 import { registerPushCommand } from './push';
 import { registerRemoveCommand } from './remove';
@@ -19,6 +20,7 @@ export function registerRealmCommand(program: Command): void {
   registerCreateCommand(realm);
   registerHistoryCommand(realm);
   registerListCommand(realm);
+  registerMilestoneCommand(realm);
   registerPullCommand(realm);
   registerPushCommand(realm);
   registerRemoveCommand(realm);