@anvil-works/anvil-cli 0.4.3 → 0.5.0

package/README.md

@@ -17,81 +17,38 @@ A CLI tool for syncing Anvil apps between your local filesystem and the Anvil ID
 npm install -g @anvil-works/anvil-cli
 ```
 
-## Quick Start
-
-### 0. Clone Your App (Required)
-
-`anvil` watches a local clone of your Anvil app. If you haven't cloned the
-app yet, follow the [cloning guide](https://anvil.works/docs/version-control/git/direct-checkout#cloning-your-app)
-first:
-
-```bash
-git clone https://anvil.works/git/YOUR_APP_ID my-app
-cd my-app
-```
-
-> **SSH-only tip:** If you sign in to Anvil with Google (and therefore don't
-> have an Anvil password), Git requires SSH. Add your public key in the Anvil
-> account settings, start `ssh-agent`, run `ssh-add`, then use the `git clone`
-> command above.
-
-### 1. Login
-
-Authenticate with Anvil using OAuth:
-
-```bash
-anvil login
-```
-
-This will:
-
-1. Open your browser to the Anvil OAuth authorization page
-2. Prompt you to authorize anvil-cli to access your Anvil account
-3. Automatically complete the authentication flow
-
-Your access and refresh tokens are stored in:
-- **macOS**: `~/Library/Preferences/anvil-cli/config.json`
-- **Linux**: `~/.config/anvil-cli/config.json`
-- **Windows**: `%APPDATA%\anvil-cli\Config\config.json`
-
-**Smart URL Handling:** You can specify the Anvil server URL directly:
-
-```bash
-# These all work - anvil automatically adds https://
-anvil login anvil.works
-anvil login anvil.mycompany.com
-
-# localhost automatically uses http://
-anvil login localhost:3000
-
-# Full URLs also work
-anvil login https://anvil.works
-```
-
-**Multiple Accounts:** anvil-cli supports multiple Anvil installations simultaneously. Each URL has its own authentication tokens, so you can work with different enterprise installations or switch between them easily.
-
-### 2. Watch Your Changes
-
-Navigate to your local Anvil app directory and start watching:
-
-```bash
-cd /path/to/your/anvil/app
-anvil watch
-```
-
-Or use the short form:
-
-```bash
-anvil w
-```
-
-You can specify the app ID explicitly:
-
-```bash
-anvil watch -A YOUR_APP_ID
-```
-
-**Watch Options:**
+## Quick Start
+
+### 1. Run Onboarding (Recommended First Step)
+
+Start with guided setup for your default server URL, login, and optional checkout:
+
+```bash
+anvil onboard
+```
+
+When prompted for **Default Anvil server URL**, press Enter unless you're
+running a dedicated enterprise/on-prem Anvil installation.
+
+### 2. Check Out Your App from the IDE URL
+
+Copy your app URL from the Anvil IDE (for example
+`https://anvil.works/build/apps/W36XUTXGNPDK6VEA`) and run:
+
+```bash
+anvil checkout https://anvil.works/build/apps/W36XUTXGNPDK6VEA my-app
+cd my-app
+```
+
+### 3. Watch Your Changes
+
+When you're ready to sync local edits in real-time:
+
+```bash
+anvil watch
+```
+
+**Watch Options:**
 
 -   `-A, --appid <APP_ID>` - Specify app ID directly
 -   `-f, --first` - Auto-select first detected app ID without confirmation
@@ -122,11 +79,13 @@ The diagram shows bidirectional sync:
 
 | Command                                | Description                                                          |
 | -------------------------------------- | -------------------------------------------------------------------- |
-| `anvil watch [path]`                   | Watch directory for changes and sync to Anvil                        |
-| `anvil watch -V` or `--verbose`        | Watch with verbose logging (detailed output)                         |
-| `anvil w [path]`                       | Short form for watch                                                 |
-| `anvil login [anvil-server-url]`       | Authenticate with Anvil using OAuth (supports smart URL handling)    |
-| `anvil l [anvil-server-url]`           | Short form for login                                                 |
+| `anvil watch [path]`                   | Watch directory for changes and sync to Anvil                        |
+| `anvil watch -V` or `--verbose`        | Watch with verbose logging (detailed output)                         |
+| `anvil w [path]`                       | Short form for watch                                                 |
+| `anvil onboard`                        | Guided setup for default URL, login, and optional checkout           |
+| `anvil checkout <input> [directory]`   | Check out an Anvil app locally from editor URL, git URL, or app ID  |
+| `anvil login [anvil-server-url]`       | Authenticate with Anvil using OAuth (supports smart URL handling)    |
+| `anvil l [anvil-server-url]`           | Short form for login                                                 |
 | `anvil logout [anvil-server-url]`      | Logout from Anvil (optionally specify URL for specific installation) |
 | `anvil config <action> [key] [value]`  | Manage configuration (set, get, list)                                |
 | `anvil c <action> [key] [value]`       | Short form for config                                                |
@@ -177,40 +136,127 @@ anvil watch
 # ❯ https://anvil.works
 #   https://anvil.company.com
 #   Cancel
-```
-
-## Configuration
-
-### Config File Location
+```
+
+### Checkout Apps
+
+`anvil checkout` accepts an editor URL, git URL, or bare app ID:
+
+```bash
+# Checkout from editor URL
+anvil checkout http://localhost:3000/build/apps/MHVELZG5SZXK2POE/code/assets/theme.css
+
+# Checkout from git URL
+anvil checkout https://anvil.works/git/MHVELZG5SZXK2POE.git
+
+# Checkout from app ID (specify URL when needed)
+anvil checkout MHVELZG5SZXK2POE --url anvil.works
+
+# Explicit destination directory
+anvil checkout MHVELZG5SZXK2POE my-local-app --url anvil.works
+
+# Clone-style options
+anvil checkout MHVELZG5SZXK2POE --branch master --depth 1 --single-branch
+anvil checkout MHVELZG5SZXK2POE --origin upstream
+anvil checkout MHVELZG5SZXK2POE --quiet
+```
+
+Safety behavior:
+
+-   Blocks checkout into non-empty destination directories (unless `--force`).
+-   Blocks checkout into paths inside an existing git repository (unless `--force`).
+
+Git HTTPS credentials:
+
+-   Checkout configures a clean HTTPS remote URL plus a repo-local Git credential helper (`anvil git-credential`).
+-   The helper retrieves short-lived access tokens from your logged-in account and refreshes them as needed.
+-   Per-app bindings are stored in local git config (`anvil.auth.<APPID>.url` and `anvil.auth.<APPID>.username`) so multi-account repos stay deterministic.
+
+Checkout options:
+
+-   `-O, --open` - Open destination after checkout
+-   `-b, --branch <BRANCH>` - Checkout a specific branch
+-   `--depth <N>` - Shallow clone with `N` commits of history
+-   `--single-branch` - Clone only one branch
+-   `--origin <NAME>` - Use custom remote name instead of `origin`
+-   `-q, --quiet` - Suppress git clone progress output
+-   `--verbose` - Verbose git clone output
+-   `-f, --force` - Override destination safety checks
+-   `-u, --url <ANVIL_URL>` - Override detected Anvil URL
+-   `-U, --user <USERNAME>` - Use a specific logged-in account
+
+If multiple accounts are logged in for the same URL, `anvil checkout` will
+prompt you to select one (interactive mode) or require `--user` in
+non-interactive mode.
+
+## Configuration
+
+### Authentication
+
+Use `anvil login` to authenticate with Anvil:
+
+```bash
+anvil login
+```
+
+The login flow will:
+
+1. Open your browser to the Anvil OAuth authorization page
+2. Prompt you to authorize anvil-cli
+3. Complete authentication automatically in the CLI
+
+Your access and refresh tokens are stored in:
+- **macOS**: `~/Library/Preferences/anvil-cli/config.json`
+- **Linux**: `~/.config/anvil-cli/config.json`
+- **Windows**: `%APPDATA%\anvil-cli\Config\config.json`
+
+Smart URL handling:
+
+```bash
+# anvil automatically adds https://
+anvil login anvil.works
+anvil login anvil.mycompany.com
+
+# localhost uses http://localhost:3000
+anvil login localhost:3000
+
+# full URLs also work
+anvil login https://anvil.works
+```
+
+anvil-cli supports multiple Anvil installations simultaneously. Each URL has
+its own authentication tokens.
+
+### Config File Location
 
 -   **macOS**: `~/Library/Preferences/anvil-cli/config.json`
 -   **Linux**: `~/.config/anvil-cli/config.json`
 -   **Windows**: `%APPDATA%\anvil-cli\Config\config.json`
 
-### Stored Configuration
-
-```json
-{
-    "authTokens": {
-        "https://anvil.works": {
-            "authToken": "your-access-token",
-            "refreshToken": "your-refresh-token",
-            "authTokenExpiresAt": 1234567890,
-            "username": "user@example.com"
-        },
-        "https://anvil.company.com": {
-            "authToken": "another-token",
-            "refreshToken": "another-refresh",
-            "authTokenExpiresAt": 1234567890,
-            "username": "user@company.com"
-        }
-    },
-    "anvilUrl": "https://anvil.works",
-    "verbose": false
-}
-```
-
-**Note:** The `authTokens` object stores tokens per URL, allowing you to work with multiple Anvil installations simultaneously. Legacy `authToken`, `refreshToken`, and `authTokenExpiresAt` fields are maintained for backward compatibility.
+### Stored Configuration
+
+`config.json` stores settings and auth metadata. OAuth secrets are stored in the
+OS keychain when available.
+
+```json
+{
+    "anvilUrl": "https://anvil.works",
+    "verbose": false,
+    "preferredEditor": "cursor",
+    "authTokens": {
+        "https://anvil.works": {
+            "user@example.com": {
+                "authToken": null,
+                "refreshToken": null,
+                "authTokenExpiresAt": 1735689600
+            }
+        }
+    }
+}
+```
+
+If keychain is unavailable (for example some CI/headless environments), tokens
+fall back to `config.json`.
 
 ### Verbose Logging
 
@@ -222,13 +268,25 @@ By default, anvil-cli shows minimal output. For more detailed logging:
 anvil watch --verbose
 ```
 
-**Persistent:** Set verbose mode in config:
+**Persistent:** Set verbose mode in config:
 
 ```bash
-anvil config set verbose true
-```
+anvil config set verbose true
+```
+
+### Preferred Editor
+
+Set this during `anvil onboard`.
+
+If needed later, you can still set it manually with:
+
+```bash
+anvil config set preferredEditor <editor>
+```
+
+`preferredEditor` is used by checkout for post-checkout guidance and `-O/--open`.
 
-Verbose output is prefixed with `[VERBOSE]` and includes file routing details, sync status checks, and other internal processing information.
+Verbose output includes timestamped diagnostic lines with file routing details, sync status checks, and other internal processing information.
 
 ### Enterprise Configuration
 
@@ -348,7 +406,7 @@ anvil login https://anvil.mycompany.com
     anvil config set anvilUrl https://anvil.works
     ```
 
--   Or reset all config values (also clears custom URLs):
+-   Or reset all config values (also clears custom URLs and logs out all accounts):
 
     ```bash
     anvil config reset
@@ -356,4 +414,4 @@ anvil login https://anvil.mycompany.com
 
 ## License
 
-ISC
+MIT

package/dist/cli.js

@@ -42459,8 +42459,31 @@ var __webpack_exports__ = {};
     }
     const configDefaults = {
         devMode: false,
-        verbose: false
+        verbose: false,
+        preferredEditor: ""
+    };
+    const preferredEditors = [
+        "vscode",
+        "cursor",
+        "nvim",
+        "zed",
+        "windsurf",
+        "pycharm"
+    ];
+    const preferredEditorCommandByValue = {
+        vscode: "code",
+        cursor: "cursor",
+        nvim: "nvim",
+        zed: "zed",
+        windsurf: "windsurf",
+        pycharm: "charm"
     };
+    const settableConfigKeys = [
+        "anvilUrl",
+        "devMode",
+        "verbose",
+        "preferredEditor"
+    ];
     function isTestMode() {
         return "test" === process.env.NODE_ENV || !!process.env.RSTEST;
     }
@@ -42532,6 +42555,23 @@ var __webpack_exports__ = {};
         }
         return value;
     }
+    function parseConfigSetValue(key, value) {
+        if (!settableConfigKeys.includes(key)) throw new Error(`✖ Error: unknown config key '${key}'. Allowed keys: ${settableConfigKeys.join(", ")}`);
+        if ("preferredEditor" === key) {
+            let normalized = value.trim().toLowerCase();
+            if ("code" === normalized) normalized = "vscode";
+            if (!preferredEditors.includes(normalized)) throw new Error(`✖ Error: preferredEditor must be one of: ${preferredEditors.join(", ")} (alias: code -> vscode)`);
+            return normalized;
+        }
+        if ("anvilUrl" === key) return value.trim().replace(/\/+$/, "");
+        return coerceConfigValue(key, value);
+    }
+    function getPreferredEditorCommand(preferredEditorValue) {
+        const normalized = preferredEditorValue.trim().toLowerCase();
+        if ("code" === normalized) return "code";
+        if (preferredEditors.includes(normalized)) return preferredEditorCommandByValue[normalized];
+        return preferredEditorValue;
+    }
     function getAllConfig() {
         return config_config.store;
     }
@@ -47584,6 +47624,7 @@ var __webpack_exports__ = {};
             });
             this.ws.on("error", (error)=>{
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, `Error: ${error.message}`);
+                if (this.isClosing) return;
                 if (error.message.includes("502")) logger_logger.error(chalk_source.red("WebSocket connection failed (502 Bad Gateway) - likely a temporary server issue"));
                 else logger_logger.error(chalk_source.red(`WebSocket error: ${error.message}`));
                 this.emit("error", {
@@ -47684,15 +47725,20 @@ var __webpack_exports__ = {};
         }
         teardownSocket() {
             this.stopHeartbeat();
-            if (!this.ws) return;
+            const socket = this.ws;
+            this.ws = null;
+            if (!socket) return;
             try {
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, "Closing WebSocket");
-                this.ws.removeAllListeners();
-                if (this.ws.readyState === ws_wrapper.OPEN || this.ws.readyState === ws_wrapper.CONNECTING) this.ws.terminate();
+                if (socket.readyState === ws_wrapper.CONNECTING) {
+                    socket.once("error", ()=>{});
+                    socket.terminate();
+                    return;
+                }
+                if (socket.readyState === ws_wrapper.OPEN) return void socket.close();
             } catch (e) {
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, "Error closing WebSocket (ignoring):", e);
             }
-            this.ws = null;
         }
     }
     async function detectRemoteChanges(gitService, oldCommitId, newCommitId) {
@@ -49956,6 +50002,121 @@ var __webpack_exports__ = {};
         session.hasUncommittedChanges = hasUncommittedChanges;
         return session;
     }
+    function getUrlConfigKey(appId) {
+        return `anvil.auth.${appId}.url`;
+    }
+    function getUsernameConfigKey(appId) {
+        return `anvil.auth.${appId}.username`;
+    }
+    async function getLocalConfigValue(repoPath, key) {
+        try {
+            const value = (await esm_default(repoPath).raw([
+                "config",
+                "--local",
+                "--get",
+                key
+            ])).trim();
+            return value || void 0;
+        } catch  {
+            return;
+        }
+    }
+    async function getAppAuthBinding(repoPath, appId) {
+        const [url, username] = await Promise.all([
+            getLocalConfigValue(repoPath, getUrlConfigKey(appId)),
+            getLocalConfigValue(repoPath, getUsernameConfigKey(appId))
+        ]);
+        return {
+            url: url ? normalizeAnvilUrl(url) : void 0,
+            username: username || void 0
+        };
+    }
+    async function setAppAuthBinding(repoPath, appId, binding) {
+        const git = esm_default(repoPath);
+        if (binding.url) await git.raw([
+            "config",
+            "--local",
+            getUrlConfigKey(appId),
+            normalizeAnvilUrl(binding.url)
+        ]);
+        if (binding.username) await git.raw([
+            "config",
+            "--local",
+            getUsernameConfigKey(appId),
+            binding.username
+        ]);
+    }
+    function getCleanGitRemoteUrl(appId, anvilUrl) {
+        const normalized = normalizeAnvilUrl(anvilUrl);
+        const url = new URL(normalized);
+        return `${url.protocol}//${url.host}/git/${appId}.git`;
+    }
+    async function configureCredentialHelperForUrl(repoPath, anvilUrl) {
+        const normalized = normalizeAnvilUrl(anvilUrl);
+        const url = new URL(normalized);
+        const scope = `${url.protocol}//${url.host}`;
+        const git = esm_default(repoPath);
+        try {
+            await git.raw([
+                "config",
+                "--local",
+                "--unset-all",
+                `credential.${scope}.helper`
+            ]);
+        } catch  {}
+        await git.raw([
+            "config",
+            "--local",
+            "--add",
+            `credential.${scope}.helper`,
+            ""
+        ]);
+        await git.raw([
+            "config",
+            "--local",
+            "--add",
+            `credential.${scope}.helper`,
+            "!anvil git-credential"
+        ]);
+        await git.raw([
+            "config",
+            "--local",
+            `credential.${scope}.useHttpPath`,
+            "true"
+        ]);
+        await git.raw([
+            "config",
+            "--local",
+            `credential.${scope}.username`,
+            "git"
+        ]);
+    }
+    async function hardenCheckoutGitAuth(options) {
+        const { repoPath, appId, anvilUrl, username } = options;
+        const remoteName = options.remoteName || "origin";
+        const cleanRemoteUrl = getCleanGitRemoteUrl(appId, anvilUrl);
+        const git = esm_default(repoPath);
+        await git.raw([
+            "remote",
+            "set-url",
+            remoteName,
+            cleanRemoteUrl
+        ]);
+        await configureCredentialHelperForUrl(repoPath, anvilUrl);
+        await setAppAuthBinding(repoPath, appId, {
+            url: anvilUrl,
+            username
+        });
+        return {
+            cleanRemoteUrl
+        };
+    }
+    function parseAppIdFromGitPath(pathValue) {
+        if (!pathValue) return;
+        const normalizedPath = pathValue.startsWith("/") ? pathValue : `/${pathValue}`;
+        const match = normalizedPath.match(/\/git\/([A-Z0-9]+)\.git(?:$|\/)/);
+        return match ? match[1] : void 0;
+    }
     function decideFallbackUrl(explicitUrl, availableUrls = getAvailableAnvilUrls()) {
         if (explicitUrl) return {
             source: "explicit",
@@ -50546,14 +50707,24 @@ var __webpack_exports__ = {};
             let anvilUrl;
             let username = explicitUsername;
             let fallbackUrl;
+            let shouldPersistUsernameBinding = false;
             if (explicitAppId) {
                 finalAppId = explicitAppId;
+                const binding = await getAppAuthBinding(repoPath, explicitAppId);
+                if (binding.url && !explicitUrl) {
+                    anvilUrl = normalizeAnvilUrl(binding.url);
+                    logger_logger.verbose(chalk_source.cyan("Resolved URL from binding for app ID: ") + chalk_source.bold(anvilUrl));
+                }
+                if (binding.username && !explicitUsername) {
+                    username = binding.username;
+                    logger_logger.verbose(chalk_source.cyan("Resolved username from binding for app ID: ") + chalk_source.bold(username));
+                }
                 const remoteInfo = lookupRemoteInfoForAppId(explicitAppId, detectedFromAllRemotes);
-                if (remoteInfo.detectedUrl && !explicitUrl) {
+                if (remoteInfo.detectedUrl && !explicitUrl && !anvilUrl) {
                     anvilUrl = normalizeAnvilUrl(remoteInfo.detectedUrl);
                     logger_logger.verbose(chalk_source.cyan("Resolved URL from remote for app ID: ") + chalk_source.bold(anvilUrl));
                 }
-                if (remoteInfo.detectedUsername && !explicitUsername) {
+                if (remoteInfo.detectedUsername && !explicitUsername && !username) {
                     username = remoteInfo.detectedUsername;
                     logger_logger.verbose(chalk_source.cyan("Resolved username from remote for app ID: ") + chalk_source.bold(username));
                 }
@@ -50608,6 +50779,16 @@ var __webpack_exports__ = {};
                     if (selected.detectedUsername && !username) username = selected.detectedUsername;
                 }
             }
+            const binding = await getAppAuthBinding(repoPath, finalAppId);
+            if (binding.url && !explicitUrl) {
+                anvilUrl = normalizeAnvilUrl(binding.url);
+                logger_logger.verbose(chalk_source.cyan("Using app binding URL: ") + chalk_source.bold(anvilUrl));
+            }
+            if (binding.username && !explicitUsername) {
+                username = binding.username;
+                logger_logger.verbose(chalk_source.cyan("Using app binding username: ") + chalk_source.bold(username));
+            }
+            shouldPersistUsernameBinding = !binding.username && !explicitUsername;
             if (explicitUrl) anvilUrl = normalizeAnvilUrl(explicitUrl);
             else if (!anvilUrl) if (fallbackUrl) anvilUrl = fallbackUrl;
             else {
@@ -50627,6 +50808,13 @@ var __webpack_exports__ = {};
                 process.exit(0);
             }
             username = resolvedUsername;
+            if (shouldPersistUsernameBinding && username && auth_getAccountsForUrl(anvilUrl).length > 1) {
+                await setAppAuthBinding(repoPath, finalAppId, {
+                    url: anvilUrl,
+                    username
+                });
+                logger_logger.verbose(chalk_source.cyan("Saved app account binding for future non-interactive use."));
+            }
             if (username) logger_logger.verbose(chalk_source.cyan("Using account: ") + chalk_source.bold(username));
             if (!hasTokensForUrl(anvilUrl, username)) {
                 if (username) logger_logger.error(`Not logged in to ${anvilUrl} as ${username}`);
@@ -50685,7 +50873,6 @@ var __webpack_exports__ = {};
         });
         return watchCommand;
     }
-    var external_http_ = __webpack_require__("http");
     const external_node_url_namespaceObject = require("node:url");
     var external_node_child_process_ = __webpack_require__("node:child_process");
     let isDockerCached;
@@ -51148,6 +51335,7 @@ var __webpack_exports__ = {};
     defineLazyProperty(open_apps, 'browser', ()=>'browser');
     defineLazyProperty(open_apps, 'browserPrivate', ()=>'browserPrivate');
     const node_modules_open = open_open;
+    var external_http_ = __webpack_require__("http");
     const successPage = `<!DOCTYPE html>
   <html lang="en">
     <head>
@@ -51305,6 +51493,9 @@ var __webpack_exports__ = {};
     </body>
   </html>`;
     }
+    function oauth_login_base64url(buf) {
+        return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    }
     async function waitForOAuthWithPrompt(authUrl, oauthPromise) {
         const rl = external_readline_namespaceObject.createInterface({
             input: process.stdin,
@@ -51329,8 +51520,382 @@ var __webpack_exports__ = {};
         process.stdout.write("\r" + " ".repeat(60) + "\r");
         return result.oauth;
     }
-    function login_base64url(buf) {
-        return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    async function runInteractiveLoginFlow(anvilUrl) {
+        const codeVerifier = external_crypto_.randomBytes(48).toString("hex");
+        const codeChallenge = oauth_login_base64url(external_crypto_.createHash("sha256").update(codeVerifier, "ascii").digest());
+        const state = external_crypto_.randomBytes(16).toString("hex");
+        const server = external_http_.createServer();
+        await new Promise((resolve)=>server.listen(0, "127.0.0.1", resolve));
+        const address = server.address();
+        if (!address || "string" == typeof address) throw new Error("No address");
+        const port = address.port;
+        const redirectUri = `http://127.0.0.1:${port}/oauth-callback`;
+        const SCOPES = "apps:read apps:write user:read";
+        const authUrl = new URL(`${anvilUrl}/oauth/authorize`);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("client_id", "anvil-sync");
+        authUrl.searchParams.set("redirect_uri", redirectUri);
+        authUrl.searchParams.set("scope", SCOPES);
+        authUrl.searchParams.set("state", state);
+        authUrl.searchParams.set("code_challenge", codeChallenge);
+        authUrl.searchParams.set("code_challenge_method", "S256");
+        const codePromise = new Promise((resolve, reject)=>{
+            server.on("request", (req, res)=>{
+                if (!req.url) return;
+                const url = new URL(req.url, `http://127.0.0.1:${port}`);
+                if ("/oauth-callback" !== url.pathname) return;
+                const code = url.searchParams.get("code") || void 0;
+                const error = url.searchParams.get("error") || void 0;
+                const recvState = url.searchParams.get("state");
+                if (!recvState || !code && !error) {
+                    res.statusCode = 400;
+                    res.end("Missing code, error or state");
+                    reject(new Error("Missing code/state/error"));
+                    server.close();
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/html; charset=utf-8");
+                if (code) res.end(successPage);
+                else res.end(errorPage(error || "unknown"));
+                resolve({
+                    code,
+                    error,
+                    recvState
+                });
+                server.closeAllConnections();
+                server.close();
+            });
+        });
+        logger_logger.info(chalk_source.blue("Link to your Anvil account to continue."));
+        console.log();
+        logger_logger.info(chalk_source.gray(`   ${authUrl}`));
+        console.log();
+        const { code, error, recvState } = await waitForOAuthWithPrompt(authUrl, codePromise);
+        if (recvState !== state) throw new Error("Invalid state received from OAuth callback");
+        if (error) throw new Error(`Error received from OAuth callback: ${error}`);
+        const tokenResponse = await fetch(`${anvilUrl}/oauth/token`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded"
+            },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code: code,
+                redirect_uri: redirectUri,
+                client_id: "anvil-sync",
+                code_verifier: codeVerifier
+            })
+        });
+        if (!tokenResponse.ok) {
+            const errorText = await tokenResponse.text();
+            throw new Error(`Failed to exchange authorization code for token. ${errorText}`);
+        }
+        const tokenData = await tokenResponse.json();
+        return login(anvilUrl, {
+            access_token: tokenData.access_token,
+            refresh_token: tokenData.refresh_token,
+            expires_in: tokenData.expires_in,
+            scope: tokenData.scope
+        });
+    }
+    const defaultCheckoutDeps = {
+        getValidAuthToken: auth_getValidAuthToken,
+        validateAppId: validateAppId,
+        runInteractiveLoginFlow: runInteractiveLoginFlow,
+        clone: async (repoUrl, destinationPath, options)=>{
+            const cloneArgs = [];
+            if (options?.branch) cloneArgs.push("--branch", options.branch);
+            if ("number" == typeof options?.depth) cloneArgs.push("--depth", String(options.depth));
+            if (options?.singleBranch) cloneArgs.push("--single-branch");
+            if (options?.origin) cloneArgs.push("--origin", options.origin);
+            if (options?.quiet) cloneArgs.push("--quiet");
+            if (options?.verbose) cloneArgs.push("--verbose");
+            await esm_default().clone(repoUrl, destinationPath, cloneArgs);
+        },
+        hardenCheckoutGitAuth: hardenCheckoutGitAuth
+    };
+    function parseCheckoutInput(input) {
+        const trimmed = input.trim();
+        if (!trimmed) throw new Error("Input is required.");
+        if (/^[A-Z0-9]+$/.test(trimmed)) return {
+            appId: trimmed
+        };
+        const asUrl = /^https?:\/\//.test(trimmed) ? trimmed : normalizeAnvilUrl(trimmed);
+        let parsed;
+        try {
+            parsed = new URL(asUrl);
+        } catch  {
+            throw new Error("Input must be an editor URL, /git URL, or bare app ID.");
+        }
+        const gitMatch = parsed.pathname.match(/\/git\/([A-Z0-9]+)\.git(?:$|\/)/);
+        if (gitMatch) return {
+            appId: gitMatch[1],
+            detectedUrl: `${parsed.protocol}//${parsed.host}`
+        };
+        const appsMatch = parsed.pathname.match(/\/apps\/([A-Z0-9]+)(?:\/|$)/);
+        if (appsMatch) return {
+            appId: appsMatch[1],
+            detectedUrl: `${parsed.protocol}//${parsed.host}`
+        };
+        throw new Error("Could not extract app ID. Expected URL path containing /apps/<APPID> or /git/<APPID>.git.");
+    }
+    function sanitizeDirectoryName(name) {
+        return name.trim().replace(/\s+/g, "_").replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+    }
+    function formatPathForDisplay(destinationPath) {
+        const relative = external_path_default().relative(process.cwd(), destinationPath);
+        if ("" === relative) return ".";
+        if (relative.startsWith("..")) return destinationPath;
+        return relative.startsWith(".") ? relative : `./${relative}`;
+    }
+    function getDefaultDestinationDirectory(appId, appName) {
+        if (appName) {
+            const sanitized = sanitizeDirectoryName(appName);
+            if (sanitized) return sanitized;
+        }
+        return appId;
+    }
+    async function resolveCheckoutUrl(explicitUrl, parsedUrl) {
+        if (explicitUrl) return normalizeAnvilUrl(explicitUrl);
+        if (parsedUrl) return normalizeAnvilUrl(parsedUrl);
+        const decision = decideFallbackUrl(void 0);
+        if ("available-multiple" !== decision.source) return decision.url;
+        const choices = decision.urls.map((url)=>({
+                name: url,
+                value: url
+            }));
+        choices.push({
+            name: "Cancel",
+            value: null
+        });
+        return logger_logger.select("Multiple logged-in Anvil URLs found. Which one would you like to use?", choices, decision.urls[0]);
+    }
+    async function isPathInsideGitRepo(targetPath) {
+        const resolved = external_path_default().resolve(targetPath);
+        let current = resolved;
+        while(!external_fs_.existsSync(current)){
+            const parent = external_path_default().dirname(current);
+            if (parent === current) return false;
+            current = parent;
+        }
+        try {
+            const output = (await esm_default(current).raw([
+                "rev-parse",
+                "--is-inside-work-tree"
+            ])).trim();
+            return "true" === output;
+        } catch  {
+            return false;
+        }
+    }
+    async function isDirectoryNonEmpty(destinationPath) {
+        if (!external_fs_.existsSync(destinationPath)) return false;
+        const stats = await external_fs_.promises.stat(destinationPath);
+        if (!stats.isDirectory()) return true;
+        const entries = await external_fs_.promises.readdir(destinationPath);
+        return entries.length > 0;
+    }
+    async function validateCheckoutDestination(destinationPath, force = false) {
+        const nonEmpty = await isDirectoryNonEmpty(destinationPath);
+        if (nonEmpty && !force) throw new Error(`Destination '${destinationPath}' already exists and is not empty.`);
+        const insideGit = await isPathInsideGitRepo(destinationPath);
+        if (insideGit && !force) throw new Error(`Destination '${destinationPath}' is inside an existing Git repository.`);
+        if (force && nonEmpty) logger_logger.warn(`--force set: destination '${destinationPath}' is non-empty and clone may still fail.`);
+        if (force && insideGit) logger_logger.warn("--force set: cloning inside an existing Git repository.");
+    }
+    async function ensureCheckoutAuthToken(anvilUrl, username, deps = defaultCheckoutDeps) {
+        try {
+            return await deps.getValidAuthToken(anvilUrl, username);
+        } catch (e) {
+            const interactive = process.stdin.isTTY && process.stdout.isTTY;
+            if (!interactive) throw errors_createAuthError.required(`Not logged in to ${anvilUrl}. Run 'anvil login ${anvilUrl}' and retry.`);
+            const shouldLogin = await logger_logger.confirm(`Not logged in to ${anvilUrl}. Log in now?`, true);
+            if (!shouldLogin) throw errors_createAuthError.required(`Not logged in to ${anvilUrl}. Run 'anvil login ${anvilUrl}' and retry.`);
+            await deps.runInteractiveLoginFlow(anvilUrl);
+            return deps.getValidAuthToken(anvilUrl, username);
+        }
+    }
+    async function resolveCheckoutUsername(anvilUrl, explicitUsername, getAccounts = auth_getAccountsForUrl) {
+        if (explicitUsername) return explicitUsername;
+        const accounts = getAccounts(anvilUrl);
+        if (0 === accounts.length) return;
+        if (1 === accounts.length) {
+            logger_logger.verbose(chalk_source.cyan("Auto-selected account: ") + chalk_source.bold(accounts[0]));
+            return accounts[0];
+        }
+        const interactive = process.stdin.isTTY && process.stdout.isTTY;
+        if (!interactive) throw new Error(`Multiple accounts found for ${anvilUrl}. Use --user <USERNAME> to choose one.`);
+        const choices = accounts.map((acct)=>({
+                name: acct,
+                value: acct
+            }));
+        choices.push({
+            name: "Cancel",
+            value: null
+        });
+        return logger_logger.select(`Multiple accounts found for ${anvilUrl}. Which account should be used for checkout?`, choices, accounts[0]);
+    }
+    async function executeCheckout(options, deps = defaultCheckoutDeps) {
+        const parsed = parseCheckoutInput(options.input);
+        const anvilUrl = await resolveCheckoutUrl(options.url, parsed.detectedUrl);
+        if (!anvilUrl) return void logger_logger.info("Checkout cancelled.");
+        const resolvedUsername = await resolveCheckoutUsername(anvilUrl, options.user);
+        if (null === resolvedUsername) return void logger_logger.info("Checkout cancelled.");
+        const authToken = await ensureCheckoutAuthToken(anvilUrl, resolvedUsername, deps);
+        let checkoutUsername = resolvedUsername;
+        if (!checkoutUsername) {
+            const inferredUsername = await resolveCheckoutUsername(anvilUrl, void 0);
+            if (null === inferredUsername) return void logger_logger.info("Checkout cancelled.");
+            if (!inferredUsername) throw new Error(`Could not determine account for ${anvilUrl}. Use --user <USERNAME> so checkout can bind repository credentials.`);
+            checkoutUsername = inferredUsername;
+        }
+        const validation = await deps.validateAppId(parsed.appId, anvilUrl, checkoutUsername);
+        if (!validation.valid) throw new Error(validation.error || `App '${parsed.appId}' is not accessible on ${anvilUrl}.`);
+        const destinationDir = options.directory || getDefaultDestinationDirectory(parsed.appId, validation.app_name);
+        const destinationPath = external_path_default().resolve(process.cwd(), destinationDir);
+        const destinationDisplay = formatPathForDisplay(destinationPath);
+        await validateCheckoutDestination(destinationPath, options.force);
+        const cloneUrl = getGitPushUrl(parsed.appId, authToken, anvilUrl);
+        logger_logger.progress("checkout", `Checking out app ${parsed.appId} from ${anvilUrl}`);
+        logger_logger.info(chalk_source.gray(`   Destination directory: ${destinationDisplay}`));
+        await deps.clone(cloneUrl, destinationPath, {
+            branch: options.branch,
+            depth: options.depth,
+            singleBranch: options.singleBranch,
+            origin: options.origin,
+            quiet: options.quiet,
+            verbose: options.verbose
+        });
+        const remoteName = options.origin || "origin";
+        try {
+            await deps.hardenCheckoutGitAuth({
+                repoPath: destinationPath,
+                appId: parsed.appId,
+                anvilUrl,
+                username: checkoutUsername,
+                remoteName
+            });
+        } catch (e) {
+            throw new Error(`Checkout clone succeeded, but failed to configure repository credentials: ${errors_getErrorMessage(e)}. The repository exists at ${destinationDisplay}, but Git auth bridge setup is incomplete.`);
+        }
+        logger_logger.progressEnd("checkout", `Checked out ${parsed.appId} into ${destinationDisplay}`);
+        const preferredEditor = String(getConfig("preferredEditor") || "").trim();
+        const preferredEditorCommand = preferredEditor ? getPreferredEditorCommand(preferredEditor) : "";
+        if (options.open) if (preferredEditorCommand) await openInPreferredEditor(preferredEditorCommand, destinationPath);
+        else {
+            await node_modules_open(destinationPath);
+            logger_logger.info(chalk_source.gray(`Opened ${destinationDisplay}`));
+        }
+        if (preferredEditorCommand && !options.open) logger_logger.info(chalk_source.cyan(`Next: ${preferredEditorCommand} ${destinationDisplay}`));
+    }
+    async function openInPreferredEditor(editorCommand, destinationPath) {
+        await new Promise((resolve, reject)=>{
+            const child = (0, external_child_process_.spawn)(editorCommand, [
+                destinationPath
+            ], {
+                shell: true,
+                stdio: "inherit"
+            });
+            child.on("error", reject);
+            child.on("exit", (code)=>{
+                if (0 === code || null === code) resolve();
+                else reject(new Error(`Editor command '${editorCommand}' exited with code ${code}`));
+            });
+        });
+    }
+    function registerCheckoutCommand(program) {
+        const checkoutCommand = program.command("checkout <input> [directory]").description("Check out an Anvil app locally from editor URL, git URL, or app ID").alias("co").option("-O, --open", "Open destination after checkout").option("-b, --branch <BRANCH>", "Checkout a specific branch").option("--depth <N>", "Create a shallow clone with history truncated to N commits", (value)=>parseInt(value, 10)).option("--single-branch", "Clone only one branch").option("--origin <NAME>", "Use a custom remote name instead of origin").option("-q, --quiet", "Suppress git clone progress output").option("--verbose", "Enable verbose git clone output").option("-u, --url <ANVIL_URL>", "Specify Anvil server URL").option("-U, --user <USERNAME>", "Specify which user account to use").option("-f, --force", "Override safety checks for destination path").action(async (input, directory, options)=>{
+            try {
+                if ("number" == typeof options?.depth && (!Number.isFinite(options.depth) || options.depth <= 0)) throw new Error("--depth must be a positive integer");
+                await executeCheckout({
+                    input,
+                    directory,
+                    open: options?.open,
+                    branch: options?.branch,
+                    depth: options?.depth,
+                    singleBranch: options?.singleBranch,
+                    origin: options?.origin,
+                    quiet: options?.quiet,
+                    verbose: options?.verbose,
+                    url: options?.url,
+                    user: options?.user,
+                    force: options?.force
+                }, defaultCheckoutDeps);
+            } catch (e) {
+                logger_logger.error("Error: " + errors_getErrorMessage(e));
+                process.exit(1);
+            }
+        });
+        checkoutCommand.addHelpText("after", "\n" + chalk_source.bold("Examples:") + "\n  anvil checkout http://localhost:3000/build/apps/APPID/code/assets/theme.css\n  anvil checkout https://anvil.works/git/APPID.git\n  anvil checkout APPID --url anvil.works\n  anvil checkout APPID --branch master --depth 1 --single-branch\n  anvil checkout APPID -O  # open editor/file browser after checkout\n  anvil checkout APPID my-local-folder --force\n");
+    }
+    const defaultDeps = {
+        getValidAuthToken: auth_getValidAuthToken,
+        getAccountsForUrl: auth_getAccountsForUrl,
+        getAppAuthBinding: getAppAuthBinding,
+        cwd: ()=>process.cwd()
+    };
+    function parseGitCredentialRequest(rawInput) {
+        const out = {};
+        const lines = rawInput.split(/\r?\n/);
+        for (const line of lines){
+            if (!line) continue;
+            const eqIdx = line.indexOf("=");
+            if (eqIdx <= 0) continue;
+            const key = line.slice(0, eqIdx);
+            const value = line.slice(eqIdx + 1);
+            if ("protocol" === key || "host" === key || "path" === key || "username" === key) out[key] = value;
+        }
+        return out;
+    }
+    async function buildGitCredentialResponse(operation, request, deps = defaultDeps) {
+        if ("get" !== operation) return null;
+        if (!request.protocol || !request.host) return null;
+        const appId = parseAppIdFromGitPath(request.path);
+        if (!appId) return null;
+        const requestUrl = normalizeAnvilUrl(`${request.protocol}://${request.host}`);
+        const binding = await deps.getAppAuthBinding(deps.cwd(), appId);
+        const anvilUrl = binding.url ? normalizeAnvilUrl(binding.url) : requestUrl;
+        let username = binding.username;
+        if (!username) {
+            const accounts = deps.getAccountsForUrl(anvilUrl);
+            if (1 === accounts.length) username = accounts[0];
+            else if (accounts.length > 1) throw new Error(`Multiple accounts found for ${anvilUrl}; bind one with anvil checkout --user.`);
+            else throw new Error(`No account found for ${anvilUrl}. Run 'anvil login ${anvilUrl}'.`);
+        }
+        const token = await deps.getValidAuthToken(anvilUrl, username);
+        return {
+            username: "git",
+            password: token
+        };
+    }
+    async function readStdin() {
+        const chunks = [];
+        for await (const chunk of process.stdin)chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    function writeGitCredentialResponse(response) {
+        if (!response) return;
+        const lines = [];
+        for (const [k, v] of Object.entries(response))lines.push(`${k}=${v}`);
+        process.stdout.write(lines.join("\n") + "\n\n");
+    }
+    async function executeGitCredentialOperation(operation, deps = defaultDeps) {
+        const raw = await readStdin();
+        const request = parseGitCredentialRequest(raw);
+        const response = await buildGitCredentialResponse(operation, request, deps);
+        writeGitCredentialResponse(response);
+    }
+    function registerGitCredentialCommand(program) {
+        program.command("git-credential <operation>", {
+            hidden: true
+        }).description("Internal helper command for Git HTTPS authentication").action(async (operation)=>{
+            try {
+                await executeGitCredentialOperation(operation);
+            } catch  {
+                process.exit(1);
+            }
+        });
     }
     function registerLoginCommand(program) {
         const loginCommand = program.command("login [anvil-server-url]").description("Log in to Anvil using OAuth").alias("l").action(async (anvilUrl)=>{
@@ -51339,93 +51904,8 @@ var __webpack_exports__ = {};
                     anvilUrl = normalizeAnvilUrl(anvilUrl.trim());
                     setConfig("anvilUrl", anvilUrl);
                 } else anvilUrl = resolveAnvilUrl();
-                const codeVerifier = external_crypto_.randomBytes(48).toString("hex");
-                const codeChallenge = login_base64url(external_crypto_.createHash("sha256").update(codeVerifier, "ascii").digest());
-                const state = external_crypto_.randomBytes(16).toString("hex");
-                const server = external_http_.createServer();
-                await new Promise((resolve)=>server.listen(0, "127.0.0.1", resolve));
-                const address = server.address();
-                if (!address || "string" == typeof address) throw new Error("No address");
-                const port = address.port;
-                const redirectUri = `http://127.0.0.1:${port}/oauth-callback`;
-                const SCOPES = "apps:read apps:write user:read";
-                const authUrl = new URL(`${anvilUrl}/oauth/authorize`);
-                authUrl.searchParams.set("response_type", "code");
-                authUrl.searchParams.set("client_id", "anvil-sync");
-                authUrl.searchParams.set("redirect_uri", redirectUri);
-                authUrl.searchParams.set("scope", SCOPES);
-                authUrl.searchParams.set("state", state);
-                authUrl.searchParams.set("code_challenge", codeChallenge);
-                authUrl.searchParams.set("code_challenge_method", "S256");
-                const codePromise = new Promise((resolve, reject)=>{
-                    server.on("request", (req, res)=>{
-                        if (!req.url) return;
-                        const url = new URL(req.url, `http://127.0.0.1:${port}`);
-                        if ("/oauth-callback" !== url.pathname) return;
-                        const code = url.searchParams.get("code") || void 0;
-                        const error = url.searchParams.get("error") || void 0;
-                        const recvState = url.searchParams.get("state");
-                        if (!recvState || !code && !error) {
-                            res.statusCode = 400;
-                            res.end("Missing code, error or state");
-                            reject(new Error("Missing code/state/error"));
-                            server.close();
-                            return;
-                        }
-                        res.statusCode = 200;
-                        res.setHeader("Content-Type", "text/html; charset=utf-8");
-                        if (code) res.end(successPage);
-                        else res.end(errorPage(error || "unknown"));
-                        resolve({
-                            code,
-                            error,
-                            recvState
-                        });
-                        server.closeAllConnections();
-                        server.close();
-                    });
-                });
-                logger_logger.info(chalk_source.blue("Link to your Anvil account to continue."));
-                console.log();
-                logger_logger.info(chalk_source.gray(`   ${authUrl}`));
-                console.log();
-                const { code, error, recvState } = await waitForOAuthWithPrompt(authUrl, codePromise);
-                if (recvState !== state) {
-                    logger_logger.error("Invalid state received from OAuth callback");
-                    process.exit(1);
-                }
-                if (error) {
-                    logger_logger.error(`Error received from OAuth callback: ${error}`);
-                    process.exit(1);
-                }
-                const tokenResponse = await fetch(`${anvilUrl}/oauth/token`, {
-                    method: "POST",
-                    headers: {
-                        "Content-Type": "application/x-www-form-urlencoded"
-                    },
-                    body: new URLSearchParams({
-                        grant_type: "authorization_code",
-                        code: code,
-                        redirect_uri: redirectUri,
-                        client_id: "anvil-sync",
-                        code_verifier: codeVerifier
-                    })
-                });
-                if (tokenResponse.ok) {
-                    const tokenData = await tokenResponse.json();
-                    const result = await login(anvilUrl, {
-                        access_token: tokenData.access_token,
-                        refresh_token: tokenData.refresh_token,
-                        expires_in: tokenData.expires_in,
-                        scope: tokenData.scope
-                    });
-                    logger_logger.success("Logged in as " + chalk_source.bold(result.email));
-                } else {
-                    logger_logger.error("Failed to exchange authorization code for token.");
-                    const errorText = await tokenResponse.text();
-                    logger_logger.error(`   Server response: ${errorText}`);
-                    process.exit(1);
-                }
+                const result = await runInteractiveLoginFlow(anvilUrl);
+                logger_logger.success("Logged in as " + chalk_source.bold(result.email));
             } catch (e) {
                 logger_logger.error("Error: " + e.message);
                 process.exit(1);
@@ -51529,6 +52009,14 @@ var __webpack_exports__ = {};
         });
         logoutCommand.addHelpText("after", "\n" + chalk_source.bold("Examples:") + "\n  anvil logout                    Logout from all accounts (or prompt if multiple)\n  anvil logout anvil.works        Logout from anvil.works\n  anvil logout -u anvil.works     Logout from anvil.works (using option)\n  anvil logout -u anvil.works -U user@example.com  Logout specific user\n");
     }
+    const defaultConfigResetDeps = {
+        logout: logout,
+        resetConfig: resetConfig
+    };
+    async function performConfigReset(deps = defaultConfigResetDeps) {
+        await deps.logout();
+        deps.resetConfig();
+    }
     function registerConfigCommand(program) {
         const configCommand = program.command("config").description("Manage configuration").alias("c");
         configCommand.command("get <key>").description("Get a configuration value").action(async (key)=>{
@@ -51547,8 +52035,7 @@ var __webpack_exports__ = {};
         });
         configCommand.command("set <key> <value>").description("Set a configuration value").action(async (key, value)=>{
             try {
-                let typedValue = coerceConfigValue(key, value);
-                if ("anvilUrl" === key && "string" == typeof typedValue) typedValue = typedValue.trim().replace(/\/+$/, "");
+                const typedValue = parseConfigSetValue(key, value);
                 setConfig(key, typedValue);
                 logger_logger.success(`Set ${key} = ${typedValue}`);
             } catch (error) {
@@ -51608,7 +52095,7 @@ var __webpack_exports__ = {};
         });
         configCommand.command("reset").description("Reset configuration to defaults").action(async ()=>{
             try {
-                resetConfig();
+                await performConfigReset();
                 logger_logger.success("Configuration reset to defaults.");
             } catch (e) {
                 logger_logger.error("Error: " + e.message);
@@ -51624,6 +52111,136 @@ var __webpack_exports__ = {};
             console.log();
         });
     }
+    const onboard_defaultDeps = {
+        getLatestVersion: getLatestVersion,
+        getAccountsForUrl: auth_getAccountsForUrl,
+        runInteractiveLoginFlow: runInteractiveLoginFlow,
+        executeCheckout: executeCheckout
+    };
+    const DEFAULT_ANVIL_SERVER_URL_PROMPT = "Default Anvil server URL";
+    async function getOnboardVersionStatus(currentVersion, latestVersionGetter = getLatestVersion) {
+        const latestVersion = await latestVersionGetter();
+        if (!latestVersion) return {
+            currentVersion,
+            latestVersion: null,
+            isOutdated: null
+        };
+        if (!semver_default().valid(currentVersion) || !semver_default().valid(latestVersion)) return {
+            currentVersion,
+            latestVersion,
+            isOutdated: null
+        };
+        return {
+            currentVersion,
+            latestVersion,
+            isOutdated: semver_default().lt(currentVersion, latestVersion)
+        };
+    }
+    function formatLoggedInAccounts(accounts) {
+        if (0 === accounts.length) return "no account";
+        if (1 === accounts.length) return accounts[0];
+        return `${accounts.length} accounts`;
+    }
+    function isInteractiveSession() {
+        return !!(process.stdin.isTTY && process.stdout.isTTY);
+    }
+    async function runOnboardFlow(version, deps = onboard_defaultDeps) {
+        if (!isInteractiveSession()) throw new Error("`anvil onboard` is interactive and requires a TTY terminal.");
+        console.log();
+        logger_logger.info(chalk_source.cyan.bold("Anvil Onboarding"));
+        console.log();
+        logger_logger.progress("onboard-version", "Checking CLI version...");
+        const versionStatus = await getOnboardVersionStatus(version, deps.getLatestVersion);
+        logger_logger.progressEnd("onboard-version");
+        logger_logger.info(chalk_source.cyan("CLI version: ") + chalk_source.bold(versionStatus.currentVersion));
+        if (versionStatus.latestVersion) {
+            logger_logger.info(chalk_source.cyan("Latest version: ") + chalk_source.bold(versionStatus.latestVersion));
+            if (versionStatus.isOutdated) {
+                logger_logger.warn("Your anvil-cli is out of date.");
+                logger_logger.info(chalk_source.gray("Run `anvil update` to see update commands."));
+                const continueOnOldVersion = await logger_logger.confirm("Continue onboarding anyway?", true);
+                if (!continueOnOldVersion) return void logger_logger.info("Onboarding cancelled.");
+            }
+        } else logger_logger.warn("Could not determine latest published version.");
+        console.log();
+        const currentUrl = resolveAnvilUrl();
+        logger_logger.info(chalk_source.gray("Leave this blank unless you're using a dedicated enterprise/on-prem Anvil installation."));
+        const urlAnswer = await logger_logger.prompt([
+            {
+                type: "input",
+                name: "anvilUrl",
+                message: DEFAULT_ANVIL_SERVER_URL_PROMPT,
+                default: currentUrl
+            }
+        ]);
+        const configuredAnvilUrl = parseConfigSetValue("anvilUrl", urlAnswer.anvilUrl);
+        setConfig("anvilUrl", configuredAnvilUrl);
+        logger_logger.success(`Set default Anvil server URL (anvilUrl) = ${configuredAnvilUrl}`);
+        const currentEditor = String(getConfig("preferredEditor") || "").trim().toLowerCase();
+        const editorChoices = [
+            {
+                name: "None",
+                value: ""
+            },
+            ...preferredEditors.map((editor)=>({
+                    name: editor,
+                    value: editor
+                }))
+        ];
+        const selectedEditor = await logger_logger.select("Preferred editor", editorChoices, editorChoices.some((choice)=>choice.value === currentEditor) ? currentEditor : "");
+        setConfig("preferredEditor", selectedEditor);
+        if (selectedEditor) logger_logger.success(`Set preferredEditor = ${selectedEditor}`);
+        else logger_logger.info("Left preferredEditor unset.");
+        const currentVerbose = !!getConfig("verbose");
+        const enableVerbose = await logger_logger.confirm("Enable verbose logging?", currentVerbose);
+        setConfig("verbose", enableVerbose);
+        logger_logger.success(`Set verbose = ${enableVerbose}`);
+        console.log();
+        const existingAccounts = deps.getAccountsForUrl(configuredAnvilUrl);
+        if (existingAccounts.length > 0) logger_logger.success(`Already logged in to ${configuredAnvilUrl} as ${formatLoggedInAccounts(existingAccounts)}.`);
+        else {
+            const shouldLogin = await logger_logger.confirm(`You're not logged in to ${configuredAnvilUrl}. Log in now?`, true);
+            if (shouldLogin) {
+                const loginResult = await deps.runInteractiveLoginFlow(configuredAnvilUrl);
+                logger_logger.success("Logged in as " + chalk_source.bold(loginResult.email));
+            } else logger_logger.warn("Skipping login.");
+        }
+        console.log();
+        const shouldCheckout = await logger_logger.confirm("Check out an app now?", true);
+        if (shouldCheckout) {
+            const checkoutAnswer = await logger_logger.prompt([
+                {
+                    type: "input",
+                    name: "input",
+                    message: "App ID or app URL to checkout"
+                }
+            ]);
+            const checkoutInput = checkoutAnswer.input.trim();
+            if (checkoutInput) {
+                const preferredEditorCommand = getPreferredEditorCommand(selectedEditor);
+                let openAfterCheckout = false;
+                if (preferredEditorCommand) openAfterCheckout = await logger_logger.confirm(`Open checked out app in ${preferredEditorCommand} after checkout?`, true);
+                else logger_logger.info("No preferred editor is configured, so open-in-editor is skipped.");
+                await deps.executeCheckout({
+                    input: checkoutInput,
+                    url: configuredAnvilUrl,
+                    open: openAfterCheckout
+                });
+            } else logger_logger.info("No app provided; skipping checkout.");
+        } else logger_logger.info("Skipping checkout.");
+        console.log();
+        logger_logger.success("Onboarding complete.");
+    }
+    function registerOnboardCommand(program, version) {
+        program.command("onboard").description("Guided setup for configuration, login, and optional app checkout").action(async ()=>{
+            try {
+                await runOnboardFlow(version, onboard_defaultDeps);
+            } catch (e) {
+                logger_logger.error("Error: " + errors_getErrorMessage(e));
+                process.exit(1);
+            }
+        });
+    }
     const packageJson = JSON.parse((0, external_fs_.readFileSync)((0, external_path_namespaceObject.join)(__dirname, "../package.json"), "utf-8"));
     const VERSION = packageJson.version;
     setLogger(new CLILogger({
@@ -51687,14 +52304,17 @@ var __webpack_exports__ = {};
         });
         if (!opts.json) {
             const commandName = actionCommand?.name();
-            if ("update" !== commandName) checkVersionAndWarn();
+            if ("update" !== commandName && "git-credential" !== commandName) checkVersionAndWarn();
         }
     });
     const cli_watchCommand = registerWatchCommand(cli_program);
+    registerCheckoutCommand(cli_program);
+    registerGitCredentialCommand(cli_program);
     registerLoginCommand(cli_program);
     registerLogoutCommand(cli_program);
     registerConfigCommand(cli_program);
     registerVersionCommand(cli_program, VERSION);
+    registerOnboardCommand(cli_program, VERSION);
     cli_program.command("update").description("Update anvil to the latest version").alias("u").action(async ()=>{
         await handleUpdateCommand();
     });

package/dist/index.js

@@ -20042,7 +20042,8 @@ var __webpack_exports__ = {};
     }
     const configDefaults = {
         devMode: false,
-        verbose: false
+        verbose: false,
+        preferredEditor: ""
     };
     function isTestMode() {
         return "test" === process.env.NODE_ENV || !!process.env.RSTEST;
@@ -22721,6 +22722,7 @@ var __webpack_exports__ = {};
             });
             this.ws.on("error", (error)=>{
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, `Error: ${error.message}`);
+                if (this.isClosing) return;
                 if (error.message.includes("502")) logger_logger.error(chalk_source.red("WebSocket connection failed (502 Bad Gateway) - likely a temporary server issue"));
                 else logger_logger.error(chalk_source.red(`WebSocket error: ${error.message}`));
                 this.emit("error", {
@@ -22821,15 +22823,20 @@ var __webpack_exports__ = {};
         }
         teardownSocket() {
             this.stopHeartbeat();
-            if (!this.ws) return;
+            const socket = this.ws;
+            this.ws = null;
+            if (!socket) return;
             try {
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, "Closing WebSocket");
-                this.ws.removeAllListeners();
-                if (this.ws.readyState === ws_wrapper.OPEN || this.ws.readyState === ws_wrapper.CONNECTING) this.ws.terminate();
+                if (socket.readyState === ws_wrapper.CONNECTING) {
+                    socket.once("error", ()=>{});
+                    socket.terminate();
+                    return;
+                }
+                if (socket.readyState === ws_wrapper.OPEN) return void socket.close();
             } catch (e) {
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, "Error closing WebSocket (ignoring):", e);
             }
-            this.ws = null;
         }
     }
     async function detectRemoteChanges(gitService, oldCommitId, newCommitId) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvil-works/anvil-cli",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "CLI tool for developing Anvil apps locally",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",