@anvil-works/anvil-cli 0.5.8 → 0.5.9

package/README.md

@@ -1,19 +1,17 @@
-# 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
-
-### macOS/Linux
+# anvil-cli
+
+`anvil-cli` is the command-line tool for developing Anvil apps locally.
+
+Use it to:
+
+- check out an Anvil app into a local folder
+- edit code in your own editor
+- keep that local folder synced with Anvil while you work
+- switch between local code editing and the Anvil designer in the same workflow
+
+## Install
+
+### macOS or Linux
 
 ```bash
 curl -fsSL https://anvil.works/install-cli.sh | sh
@@ -31,433 +29,348 @@ irm https://anvil.works/install-cli.ps1 | iex
 curl -fsSL https://anvil.works/install-cli.cmd -o install.cmd && install.cmd && del install.cmd
 ```
 
-### Manual Fallback
+### npm fallback
 
 ```bash
 npm install -g @anvil-works/anvil-cli@latest
 ```
-
-## Quick Start
 
-### 1. Run Configure (Recommended First Step)
+## Quickstart
+
+This is the main happy path:
+
+1. Install `anvil-cli`.
+2. Run `anvil configure`.
+3. Run `anvil checkout`.
+4. Change into the app directory.
+5. Run `anvil watch`.
+
+### 1. Configure the CLI
 
-Start with guided setup for your default server URL and login:
+Run:
 
 ```bash
 anvil configure
 ```
 
-When prompted for **Default Anvil server URL**, press Enter unless you're
-running a dedicated enterprise/on-prem Anvil installation.
-`anvil configure` does not run checkout automatically; it ends by suggesting `anvil checkout`.
+This guided setup helps you:
 
-### 2. Check Out Your App from the IDE URL
+- set your default Anvil server URL
+- choose a preferred editor, if you want one
+- log in to Anvil
 
-Copy your app URL from the Anvil IDE (for example
-`https://anvil.works/build/apps/W36XUTXGNPDK6VEA`) and run:
+If you use `anvil.works`, you can usually accept the default server when prompted.
+
+### 2. Check out your app
+
+Run:
+
+```bash
+anvil checkout
+```
+
+This opens an interactive app picker and creates the app directory for you.
+
+If you already have the app URL from the Anvil editor, you can also run:
 
 ```bash
 anvil checkout https://anvil.works/build/apps/W36XUTXGNPDK6VEA my-app
 cd my-app
 ```
 
-### 3. Watch Your Changes
+You can also check out by app ID:
 
-When you're ready to sync local edits in real-time:
+```bash
+anvil checkout W36XUTXGNPDK6VEA my-app --url anvil.works
+cd my-app
+```
+
+### 3. Start syncing
+
+Inside the app directory, run:
 
 ```bash
 anvil watch
 ```
 
-**Watch 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
--   `-O, --open` - Open watched path in your preferred editor (or default app)
--   `-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 watch [path]`                   | Watch directory for changes and sync to Anvil                        |
-| `anvil watch [path] -O`                | Open watched path in preferred editor/default app                    |
-| `anvil watch -V` or `--verbose`        | Watch with verbose logging (detailed output)                         |
-| `anvil w [path]`                       | Short form for watch                                                 |
-| `anvil configure`                      | Guided setup for default URL and login                               |
-| `anvil checkout [input] [directory]`   | Check out an app by URL/app ID, or interactively with no input       |
-| `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 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. **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:**
-
-```bash
-# Auto-detect from git remote
-anvil watch
-
-# Specify URL explicitly
-anvil watch --url anvil.works
-anvil watch --url localhost:3000
-anvil watch --url anvil.mycompany.com
-
-# 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
+Leave this running while you work.
+
+With `anvil watch` running:
+
+- local code changes sync into Anvil
+- compatible changes made in Anvil sync back into your local files
+- you can keep using the Anvil designer when you need it
+
+## Core Commands
+
+These are the commands that matter most for normal local development:
+
+### `anvil configure`
+
+Guided setup for your default server URL, editor preference, and login.
+
+```bash
+anvil configure
 ```
 
-### Checkout Apps
+### `anvil checkout`
+
+Create a local app folder from an editor URL, Git URL, app ID, or interactive picker.
+
+```bash
+anvil checkout [input] [directory]
+anvil co [input] [directory]
+```
 
-`anvil checkout` accepts an editor URL, git URL, bare app ID, or no input for interactive selection:
+Common examples:
 
 ```bash
-# Interactive search/select (ordered by most recently edited)
 anvil checkout
+anvil checkout https://anvil.works/build/apps/W36XUTXGNPDK6VEA my-app
+anvil checkout W36XUTXGNPDK6VEA my-app --url anvil.works
+anvil co -Q "dashboard"
 ```
 
-In interactive mode, apps are displayed as `App Name (APPID)` and support:
--   Arrow-key selection
--   Auto-pagination (fetch-ahead with local cache)
--   Search by app name or app ID
+Useful options:
+
+- `-O, --open` open the app folder after checkout
+- `-b, --branch <BRANCH>` check out a specific branch
+- `-Q, --query <QUERY>` prefill the interactive search
+- `-u, --url <ANVIL_URL>` choose the Anvil installation explicitly
+- `-U, --user <USERNAME>` choose the logged-in account explicitly
+- `-f, --force` override destination safety checks
 
-In non-interactive mode, pass an explicit app input:
--   `anvil checkout APPID`
--   `anvil checkout https://anvil.works/git/APPID.git`
+### `anvil watch`
+
+Keep your local app folder synced with Anvil while you work.
 
 ```bash
-# Checkout from editor URL
-anvil checkout http://localhost:3000/build/apps/MHVELZG5SZXK2POE/code/assets/theme.css
+anvil watch [path]
+anvil w [path]
+```
 
-# Checkout from git URL
-anvil checkout https://anvil.works/git/MHVELZG5SZXK2POE.git
+Common examples:
 
-# Checkout from app ID (specify URL when needed)
-anvil checkout MHVELZG5SZXK2POE --url anvil.works
+```bash
+anvil watch
+anvil watch -s
+anvil watch -a
+anvil watch -O
+anvil watch --url anvil.company.com
+```
 
-# Explicit destination directory
-anvil checkout MHVELZG5SZXK2POE my-local-app --url anvil.works
+Useful options:
 
-# Clone-style options
-anvil checkout MHVELZG5SZXK2POE --branch master --depth 1 --single-branch
-anvil checkout MHVELZG5SZXK2POE --origin upstream
-anvil checkout MHVELZG5SZXK2POE --quiet
+- `-A, --appid <APP_ID>` specify the app directly
+- `-s, --staged-only` sync only staged files
+- `-a, --auto` handle some branch and sync transitions automatically
+- `-O, --open` open the watched path in your preferred editor
+- `-u, --url <ANVIL_URL>` choose the Anvil installation explicitly
+- `-U, --user <USERNAME>` choose the logged-in account explicitly
 
-# Seed interactive search query
-anvil checkout -Q "dashboard"
-anvil checkout --query "dashboard"
+### Other useful commands
 
-# Open watched path in editor/default app
-anvil watch -O
-anvil watch ./my-app -O
+```bash
+anvil login
+anvil logout
+anvil config list
+anvil config get <key>
+anvil config set <key> <value>
+anvil config reset
+anvil version
+anvil update
+anvil --help
+anvil <command> --help
+```
+
+Global options:
+
+- `-V, --verbose` show detailed output
+- `--json` output NDJSON for scripting or LLM tooling
+
+## Recommended Workflows
+
+### Work between your editor and the Anvil designer
+
+The basic loop is:
+
+1. Run `anvil watch` in your app folder.
+2. Edit Python locally in your editor.
+3. Open the same app in Anvil when you need the designer.
+4. Keep `anvil watch` running while you move between them.
+
+### Use branches by default
+
+Create or switch to a branch before you start watching:
+
+```bash
+git checkout -b my-feature
+anvil watch
 ```
 
-Safety behavior:
+If you switch branches while watching, `anvil watch` may prompt you to restart or resync. If you want the CLI to handle that automatically, use:
 
--   Blocks checkout into non-empty destination directories (unless `--force`).
--   Blocks checkout into paths inside an existing git repository (unless `--force`).
+```bash
+anvil watch --auto
+```
+
+### Use staged-only mode when experimenting
+
+If you want tighter control over what syncs to Anvil, use:
+
+```bash
+anvil watch --staged-only
+git add server_code/MyModule.py
+```
+
+Only staged files will sync.
 
-Git HTTPS credentials:
+### Work with AI assistants
 
--   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.
+A simple pattern is:
 
-Checkout options:
+1. Start `anvil watch`.
+2. Open the app folder in Cursor, VS Code, or another editor.
+3. Make or review AI-generated changes locally.
+4. Test the synced result in Anvil.
 
--   `-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`
--   `--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 you are iterating on messy changes, combine this with `--staged-only`.
 
-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.
+## Multiple Accounts and Enterprise Installs
 
-## Configuration
+Most users on `anvil.works` do not need to think about this.
 
-### Authentication
+If you work across multiple Anvil installations or multiple logged-in accounts, the CLI can usually infer the right choice. If it cannot, you can override it with:
 
-Use `anvil login` to authenticate with Anvil:
+- `--url` to choose the Anvil installation
+- `--user` to choose the logged-in account
+
+Examples:
+
+```bash
+anvil login anvil.company.com
+anvil checkout APPID my-app --url anvil.company.com
+anvil watch --url anvil.company.com --user user@example.com
+anvil logout --url anvil.company.com --user user@example.com
+```
+
+If you want to change the default server permanently:
+
+```bash
+anvil config set anvilUrl https://anvil.company.com
+```
+
+## Troubleshooting
+
+### `anvil` command not found
+
+Try the install command again, then open a new terminal and run:
+
+```bash
+anvil --help
+```
+
+If the install script fails, use the npm fallback.
+
+### Login or account selection problems
+
+Try:
 
 ```bash
 anvil login
+anvil config list
+```
+
+If you use a self-hosted installation:
+
+```bash
+anvil login anvil.company.com
 ```
 
-The login flow will:
+### `anvil checkout` cannot find the app
 
-1. Open your browser to the Anvil OAuth authorization page
-2. Prompt you to authorize anvil-cli
-3. Complete authentication automatically in the CLI
+Try using the app URL directly from the Anvil editor, or pass `--url` and `--user` if the CLI is looking at the wrong installation or account.
 
-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`
+### Local changes are not appearing in Anvil
 
-Smart URL handling:
+Make sure you are in the correct app directory and restart:
 
 ```bash
-# anvil automatically adds https://
-anvil login anvil.works
-anvil login anvil.mycompany.com
+anvil watch
+```
+
+If you are using `--staged-only`, remember that only staged files sync.
+
+### Changes from Anvil are not appearing locally
 
-# localhost uses http://localhost:3000
-anvil login localhost:3000
+Make sure `anvil watch` is still running. If the watch session looks unhealthy or branch state changed underneath it, stop it and start it again from the correct branch and app folder.
 
-# full URLs also work
-anvil login https://anvil.works
+### The CLI is using the wrong server
+
+Check your current config:
+
+```bash
+anvil config list
 ```
 
-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
-
-`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
-            }
-        }
-    }
-}
+Set the default explicitly if needed:
+
+```bash
+anvil config set anvilUrl https://anvil.company.com
 ```
 
-If keychain is unavailable (for example some CI/headless environments), tokens
-fall back to `config.json`.
-
-### Verbose Logging
-
-By default, anvil-cli shows minimal output. For more detailed logging:
-
-**One-time:** Use the `-V` or `--verbose` flag:
-
-```bash
-anvil watch --verbose
-```
-
-**Persistent:** Set verbose mode in config:
-
-```bash
-anvil config set verbose true
+## Config File
+
+`anvil-cli` stores local settings in `config.json`.
+
+Common locations:
+
+- macOS: `~/Library/Preferences/anvil-cli/config.json`
+- Linux: `~/.config/anvil-cli/config.json`
+- Windows: `%APPDATA%\\anvil-cli\\Config\\config.json`
+
+This includes settings such as:
+
+- `anvilUrl`
+- `preferredEditor`
+- `verbose`
+
+Authentication secrets are stored in the OS keychain when available.
+
+## Developing `anvil-cli`
+
+Build the CLI:
+
+```bash
+pnpm build
+```
+
+Run in watch mode:
+
+```bash
+pnpm dev
 ```
 
-### Preferred Editor
+Type-check:
 
-Set this during `anvil configure`.
+```bash
+pnpm tsc --noEmit
+```
 
-If needed later, you can still set it manually with:
+Run tests:
 
 ```bash
-anvil config set preferredEditor <editor>
+source tests/setup-test-env.sh
+pnpm test
 ```
 
-`preferredEditor` is used by checkout for post-checkout guidance and `-O/--open`.
-It is also used by `anvil watch -O`.
-
-Verbose output includes timestamped diagnostic lines with 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 watch --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
-
-# 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
+Run one test file:
+
+```bash
+source tests/setup-test-env.sh
+pnpm rstest tests/some.test.ts
 ```
-
-**URL Resolution Priority:**
-
-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`
-
-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
-```
-
-**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
-
-### "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 watch -A YOUR_APP_ID`
--   Use `-f, --first` to auto-select the first detected app ID: `anvil watch -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 and logs out all accounts):
-
-    ```bash
-    anvil config reset
-    ```
-
-## License
-
+
+## License
+
 MIT

package/package.json

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