@anvil-works/anvil-cli 0.4.3 → 0.5.1

package/README.md

@@ -11,87 +11,64 @@ A CLI tool for syncing Anvil apps between your local filesystem and the Anvil ID
 -   **Form Support**: Syncs forms with templates and code
 -   **Theme Assets**: Syncs theme assets and configuration
 
-## Installation
-
-```bash
-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
-```
+## Installation
+
+### macOS/Linux
+
+```bash
+curl -fsSL https://anvil.works/install/anvil-cli/install.sh | sh
+```
+
+### Windows PowerShell
+
+```powershell
+irm https://anvil.works/install/anvil-cli/install.ps1 | iex
+```
+
+### Windows CMD
+
+```cmd
+curl -fsSL https://anvil.works/install/anvil-cli/install.cmd -o install.cmd && install.cmd && del install.cmd
+```
+
+### Manual Fallback
+
+```bash
+npm install -g @anvil-works/anvil-cli
+```
 
-**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 +99,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 +156,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 +288,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 +426,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 +434,4 @@ anvil login https://anvil.mycompany.com
 
 ## License
 
-ISC
+MIT