Skip to content

🚀 Roaming CLI — Multi-Device Bootstrap

The Problem

You use Copilot CLI across multiple devices (💻 Laptop, ☁️ W365, 🍎 Mac). When you open CLI on a stale or new device, it's missing:

  • Recent brain files (instructions, journal, starter prompts)
  • Latest code from git repos
  • npm dependencies
  • Possibly even basic tools (pwsh, hugo, etc.)

Goal: One command respawns a fully working CLI environment on any machine.

The 3-Layer Sync System

┌──────────────────────────────────────────────────────────┐
│                    OneDrive Personal                      │
│   CopilotCLI_Sync/          CopilotCLI_Backups/          │
│   ├─ copilot-instructions.md  ├─ backup_2026-05-29_...   │
│   ├─ copilot-instructions-    ├─ backup_2026-05-28_...   │
│   │  reference.md             ├─ ...last 30 backups      │
│   ├─ session-journal.md       └─ learning-docs-backup/   │
│   ├─ starter-prompts/                                     │
│   ├─ sync-brain.ps1       ← auto-sync on terminal open   │
│   └─ bootstrap-cli.ps1   ← full respawn command          │
├──────────────────────────────────────────────────────────┤
│                     GitHub Repos                          │
│   susanthgit/aguidetocloud-revamp  (Hugo main site)       │
│   susanthgit/guided                (Astro cert platform)  │
│   susanthgit/learning-docs         (MkDocs portal)        │
├──────────────────────────────────────────────────────────┤
│                Google Drive Mirror                        │
│   CopilotCLI_Backups/ ← robocopy mirror of OneDrive      │
└──────────────────────────────────────────────────────────┘
Layer What When Direction
🧠 Brain Sync 3 brain files + starter prompts Every terminal open Bidirectional (newer wins)
📦 Git Repos All source code Background fetch hourly, pull on bootstrap Pull from GitHub
💾 Backups Full ~/.copilot + learning-docs Twice daily (8 AM + 6 PM) via Task Scheduler Laptop → OneDrive → Google Drive

What Each Script Does

sync-brain.ps1 — Lightweight auto-sync

Runs automatically every time you open a terminal (via $PROFILE).

  • Brain files: Compares timestamps between OneDrive and local ~/.copilot/. Newer file wins. Copies in the winning direction.
  • Repo fetch: Background git fetch --prune on all 3 repos (non-blocking, max once per hour). Does NOT pull or merge — just makes updates available so git pull is instant when you need it.
  • Bootstrap function: Loads the bootstrap command so it's always available.

bootstrap-cli.ps1 — Full respawn

Run manually with the bootstrap command. Does everything needed to go from stale to fully operational:

  1. Brain sync — same as above
  2. Git repos — pulls (if clean + on default branch) or clones (if missing)
  3. Dependencies — npm ci for guided (Astro) if node_modules missing
  4. Tool check — verifies pwsh, git, gh, node, npm, hugo, python + gh auth status
  5. Health report — colour-coded table showing what's ready vs what needs attention

Flags:

Flag What
-DryRun Preview what would happen, no changes
-SkipInstall Skip npm ci (faster if you only need brain + code)

Safety features:

  • Only pulls repos with clean working trees on default branch (--ff-only)
  • Dirty trees and non-default branches are skipped with a warning
  • Lock file prevents concurrent runs (10 min timeout)
  • OneDrive hydration timeout (skips files that take >5s to read)

backup-instructions.ps1 — Full backup

Runs on a schedule via Windows Task Scheduler (laptop only):

  • Copies ~/.copilot (config, secrets, session state, MCP config)
  • Creates environment manifest (tool versions, cloned repos)
  • Backs up YouTube MCP OAuth credentials
  • Backs up Windows Terminal settings
  • Backs up learning-docs Markdown content
  • Mirrors everything to Google Drive via robocopy
  • Keeps last 30 backups, auto-prunes older ones

First-Time Setup on a New Device

Prerequisites

The device needs:

  • [x] OneDrive Personal signed in and syncing
  • [x] PowerShell 7+ (winget install Microsoft.PowerShell)
  • [x] Git (winget install Git.Git)
  • [x] GitHub CLI (winget install GitHub.cli → then gh auth login)

Steps

# 1. Install pwsh (if not already)
winget install Microsoft.PowerShell

# 2. Open pwsh (close old terminal, open new one)

# 3. Set up PowerShell profile to auto-sync
if (!(Test-Path $PROFILE)) { New-Item $PROFILE -Force }
Add-Content $PROFILE '. "$env:USERPROFILE\OneDrive\CopilotCLI_Sync\sync-brain.ps1"'

# 4. Close and reopen terminal (loads the profile)

# 5. Run bootstrap
bootstrap

# 6. If git clone/push fails, authenticate GitHub
gh auth login

After this, every future terminal open will auto-sync brain files and background-fetch repos.

What's NOT Synced (Limitations)

Item Why Workaround
Session store DB (session-store.db) Device-local SQLite, not designed for roaming Cloud session store has partial coverage; accept this gap
MCP OAuth tokens Device-specific browser auth Re-authenticate on each device (one-time)
npm node_modules Too large for OneDrive, platform-specific bootstrap runs npm ci automatically
Hugo cache/public Build artifacts, regenerated on build Just run the build
Windows Terminal settings Backed up but not auto-synced Restore from backup if needed

Troubleshooting

Symptom Cause Fix
Brain files are weeks old Sync script hasn't run Open terminal (triggers sync) or run bootstrap
bootstrap command not found Profile not set up Run the $PROFILE setup from "First-Time Setup" above
Git pull fails Auth expired or dirty tree gh auth login or commit/stash changes
OneDrive files hang/timeout Cloud-only files not hydrated Open OneDrive, right-click sync folder → "Always keep on this device"
Backup Task Scheduler stopped Laptop was sleeping/lid closed at scheduled time Check Task Scheduler → re-enable the task
Enrichment starter not found File wasn't committed to git Check guided/files/ after git pull

Maintenance Checklist

Frequency Task
Every terminal open Automatic — brain sync + repo fetch handled by sync-brain.ps1
When switching devices Run bootstrap once to fully sync
Monthly Verify backup Task Scheduler is running on laptop
When adding new repos Add to $repos array in bootstrap-cli.ps1
When adding new tools Add to $tools array in bootstrap-cli.ps1