@anvil-works/anvil-cli 0.4.2 → 0.5.0

package/README.md

@@ -17,83 +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
-```
-
-> **Note:** `anvil sync` still works but is deprecated. Use `anvil watch` instead.
-
-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
@@ -124,12 +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 sync [path]`                    | Deprecated alias for `watch`                                         |
-| `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                                                |
@@ -153,13 +109,15 @@ anvil watch -A YOUR_APP_ID
 
 ### Anvil URL Detection
 
-anvil-cli automatically detects which Anvil server to use:
-
-1. **Explicit URL**: If you specify `--url` or `-u` flag
-2. **Git Remotes**: Automatically extracts URL from git remotes in your repository
-3. **User Prompt**: If multiple accounts are available, prompts you to select one
-4. **Global Config**: Falls back to `anvilUrl` in config file
-5. **Default**: Uses `https://anvil.works` (or `http://localhost:3000` in dev mode)
+anvil-cli automatically detects which Anvil server to use:
+
+1. **Explicit URL**: If you specify `--url` or `-u` flag
+2. **Git Remotes**: Automatically extracts URL from git remotes in your repository
+3. **Logged-in URLs**:
+    - If one logged-in URL is available, uses it automatically
+    - If multiple logged-in URLs are available, prompts you to select one
+4. **Global Config**: Falls back to `anvilUrl` in config file
+5. **Default**: Uses `https://anvil.works` (or `http://localhost:3000` in dev mode)
 
 **Examples:**
 
@@ -172,46 +130,133 @@ anvil watch --url anvil.works
 anvil watch --url localhost:3000
 anvil watch --url anvil.mycompany.com
 
-# If multiple accounts, you'll be prompted to select
-anvil watch
-# ? Multiple Anvil installations found. Which one would you like to use?
-# ❯ https://anvil.works
-#   https://anvil.company.com
-#   Cancel
-```
-
-## Configuration
-
-### Config File Location
+# If multiple logged-in URLs, you'll be prompted to select
+anvil watch
+# ? Multiple Anvil installations found. Which one would you like to use?
+# ❯ https://anvil.works
+#   https://anvil.company.com
+#   Cancel
+```
+
+### 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
 
@@ -223,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
-```
-
-Verbose output is prefixed with `[VERBOSE]` and includes file routing details, sync status checks, and other internal processing information.
+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 includes timestamped diagnostic lines with file routing details, sync status checks, and other internal processing information.
 
 ### Enterprise Configuration
 
@@ -269,18 +326,21 @@ anvil login anvil.works
 anvil login anvil.company-a.com
 anvil login anvil.company-b.com
 
-# When syncing, you'll be prompted to select which one to use
-# Or specify explicitly:
-anvil watch --url anvil.company-a.com
-```
+# If URL is not resolved from git remotes and multiple logged-in URLs exist,
+# you'll be prompted to select which one to use
+# Or specify explicitly:
+anvil watch --url anvil.company-a.com
+```
 
 **URL Resolution Priority:**
 
-1. Explicit `--url` flag
-2. Git remote detection (from current repository)
-3. User prompt (if multiple accounts available)
-4. `anvilUrl` in config file
-5. Default based on `NODE_ENV`:
+1. Explicit `--url` flag
+2. Git remote detection (from current repository)
+3. Logged-in URL selection:
+    - One URL: auto-select
+    - Multiple URLs: prompt to select
+4. `anvilUrl` in config file
+5. Default based on `NODE_ENV`:
     - Production: `https://anvil.works`
     - Development: `http://localhost:3000`
 
@@ -308,10 +368,13 @@ anvil logout anvil.mycompany.com
 anvil logout --url localhost:3000
 ```
 
-**Multiple accounts:** If you have multiple accounts and run `anvil logout` without specifying a URL, you'll be prompted to:
-
--   Logout from one account (then select which one)
--   Logout from all accounts
+**Without URL:** `anvil logout` uses total logged-in account count across all URLs:
+
+-   If you have **one account total**, it logs out immediately
+-   If you have **multiple accounts total**, you'll be prompted to:
+
+-   Logout from one account (then select which one)
+-   Logout from all accounts
 -   Cancel
 
 ## Troubleshooting
@@ -343,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
@@ -351,4 +414,4 @@ anvil login https://anvil.mycompany.com
 
 ## License
 
-ISC
+MIT