@anvil-works/anvil-cli 0.3.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Anvil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,358 @@
+# anvil-cli
+
+A CLI tool for syncing Anvil apps between your local filesystem and the Anvil IDE. Edit your Anvil apps in your favorite editor and sync changes in real-time.
+
+## Features
+
+-   **Real-time Sync**: Watch for file changes and automatically sync to Anvil
+-   **OAuth Authentication**: Secure authentication via OAuth with automatic token refresh
+-   **Auto-detection**: Automatically detects app IDs from git remotes or commit history
+-   **Python Module Support**: Syncs server-side and client-side Python modules
+-   **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. Sync Your Changes
+
+Navigate to your local Anvil app directory and start syncing:
+
+```bash
+cd /path/to/your/anvil/app
+anvil sync
+```
+
+Or use the `watch` alias (for backward compatibility):
+
+```bash
+anvil watch
+```
+
+Or use the short form:
+
+```bash
+anvil w
+```
+
+You can specify the app ID explicitly:
+
+```bash
+anvil sync -A YOUR_APP_ID
+```
+
+**Sync Options:**
+
+-   `-A, --appid <APP_ID>` - Specify app ID directly
+-   `-f, --first` - Auto-select first detected app ID without confirmation
+-   `-s, --staged-only` - Only sync staged changes (use `git add` to stage files)
+-   `-a, --auto` - Auto mode: restart on branch changes and sync when behind
+-   `-u, --url <ANVIL_URL>` - Specify Anvil server URL (e.g., `anvil.works`, `localhost:3000`)
+-   `-V, --verbose` - Show detailed output
+
+**Tip:** Open your app in the [Anvil IDE](https://anvil.works) to see your local changes appear in real-time. Changes made in the IDE will also sync back to your local files.
+
+## How It Works
+
+### Architecture
+
+```
+┌──────────────┐      ┌──────────────┐      ┌──────────────┐      ┌──────────────┐
+│ Local Files  │◄────►│  anvil-cli   │◄────►│ Anvil Server │◄────►│  Anvil IDE   │
+│(your editor) │      │ (Node.js CLI)│      │(anvil.works) │      │  (Browser)   │
+└──────────────┘      └──────────────┘      └──────────────┘      └──────────────┘
+```
+
+The diagram shows bidirectional sync:
+
+-   **Local → Anvil**: Your local file changes are synced to Anvil via API calls through anvil-cli
+-   **Anvil → Local**: Changes made in the Anvil IDE are automatically detected and synced back to your local files via git fetch through anvil-cli
+
+### CLI Commands
+
+| Command                                | Description                                                          |
+| -------------------------------------- | -------------------------------------------------------------------- |
+| `anvil sync [path]`                    | Watch directory for changes and sync to Anvil                        |
+| `anvil sync -V` or `--verbose`         | Sync with verbose logging (detailed output)                          |
+| `anvil watch [path]`                   | Alias for sync (backward compatibility)                              |
+| `anvil w [path]`                       | Short form for sync                                                  |
+| `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                                                |
+| `anvil version`                        | Show version information                                             |
+| `anvil -h, --help`                     | Show help message                                                    |
+| `anvil -v, --version`                  | Show version number                                                  |
+
+### App ID Detection
+
+anvil-cli can auto-detect your app ID using multiple strategies:
+
+1. **Git Remotes**: Checks for Anvil git remotes in the repository
+
+2. **Commit Lookup**: Queries Anvil API with current commit ID and branch to find matching app
+
+If auto-detection fails, you can specify the app ID explicitly:
+
+```bash
+anvil sync -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)
+
+**Examples:**
+
+```bash
+# Auto-detect from git remote
+anvil sync
+
+# Specify URL explicitly
+anvil sync --url anvil.works
+anvil sync --url localhost:3000
+anvil sync --url anvil.mycompany.com
+
+# If multiple accounts, you'll be prompted to select
+anvil sync
+# ? Multiple Anvil installations found. Which one would you like to use?
+# ❯ https://anvil.works
+#   https://anvil.company.com
+#   Cancel
+```
+
+## Configuration
+
+### 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.
+
+### Verbose Logging
+
+By default, anvil-cli shows minimal output. For more detailed logging:
+
+**One-time:** Use the `-V` or `--verbose` flag:
+
+```bash
+anvil sync --verbose
+```
+
+**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.
+
+### Enterprise Configuration
+
+If you're using an Anvil server other than `anvil.works` (e.g., enterprise/on-premise installation), you can work with multiple installations:
+
+**Option 1: Login with URL** (recommended)
+
+```bash
+# Login to your enterprise installation
+anvil login anvil.mycompany.com
+
+# Or with full URL
+anvil login https://anvil.mycompany.com
+```
+
+**Option 2: Specify URL when syncing**
+
+```bash
+# Sync with specific URL
+anvil sync --url anvil.mycompany.com
+```
+
+**Option 3: Set global default**
+
+```bash
+anvil config set anvilUrl https://anvil.mycompany.com
+anvil login
+```
+
+**Multiple Installations:**
+
+anvil-cli supports multiple Anvil installations simultaneously. Each installation has its own authentication tokens:
+
+```bash
+# Login to multiple installations
+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 sync --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`:
+    - Production: `https://anvil.works`
+    - Development: `http://localhost:3000`
+
+View all configuration:
+
+```bash
+anvil config list
+```
+
+### Logout
+
+Logout from Anvil installations:
+
+**Logout from all accounts:**
+
+```bash
+anvil logout
+```
+
+**Logout from specific installation:**
+
+```bash
+anvil logout anvil.works
+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
+-   Cancel
+
+## Troubleshooting
+
+### "No app ID found"
+
+-   Ensure you're in an Anvil app directory with `anvil.yaml`
+-   Check git remotes: `git remote -v`
+-   Specify app ID explicitly: `anvil sync -A YOUR_APP_ID`
+-   Use `-f, --first` to auto-select the first detected app ID: `anvil sync -f`
+
+### "Authentication failed" or "Not logged in to [URL]"
+
+-   Run `anvil login [url]` to authenticate with the specific Anvil installation
+-   If you see "Not logged in to [URL]", you need to login to that specific URL:
+
+```bash
+anvil login https://anvil.mycompany.com
+```
+
+-   Your access token may have expired and refresh failed - re-login to get new tokens
+-   For multiple installations, make sure you're logged in to the correct one
+
+### Switch back to hosted Anvil
+
+-   Reset the server URL to the default cloud host:
+
+    ```bash
+    anvil config set anvilUrl https://anvil.works
+    ```
+
+-   Or reset all config values (also clears custom URLs):
+
+    ```bash
+    anvil config reset
+    ```
+
+## License
+
+ISC