@anvil-works/anvil-cli 0.5.8 → 0.5.10

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/dist/cli.js

@@ -42538,6 +42538,13 @@ var __webpack_exports__ = {};
     function getConfig(key) {
         return config_config.get(key);
     }
+    function deleteConfig(key) {
+        if (key in configDefaults) config_config.set(key, configDefaults[key]);
+        else {
+            const store = config_config.store;
+            if (store && "object" == typeof store && key in store) config_config.delete(key);
+        }
+    }
     function resetConfig() {
         for (const [key, value] of Object.entries(configDefaults))config_config.set(key, value);
         const currentStore = config_config.store;
@@ -42670,7 +42677,7 @@ var __webpack_exports__ = {};
             ...config
         };
     }
-    function globalConfig_getGlobalOutputConfig() {
+    function getGlobalOutputConfig() {
         return globalOutputConfig;
     }
     const logger_timestamp = ()=>new Date().toISOString();
@@ -42691,10 +42698,20 @@ var __webpack_exports__ = {};
     function writeJson(entry) {
         console.log(JSON.stringify(entry));
     }
+    function logJsonResult(success, options) {
+        if (getGlobalOutputConfig().jsonMode) writeJson({
+            type: "result",
+            success,
+            message: options?.message,
+            data: options?.data,
+            error: options?.error,
+            timestamp: logger_timestamp()
+        });
+    }
     class DefaultLogger {
         paused = false;
         get jsonMode() {
-            return globalConfig_getGlobalOutputConfig().jsonMode;
+            return getGlobalOutputConfig().jsonMode;
         }
         log(...args) {
             if (this.paused) return;
@@ -42796,7 +42813,7 @@ var __webpack_exports__ = {};
             this.sessionVerbose = options.verbose ?? false;
         }
         get jsonMode() {
-            return globalConfig_getGlobalOutputConfig().jsonMode;
+            return getGlobalOutputConfig().jsonMode;
         }
         isVerbose() {
             return this.sessionVerbose || getConfig("verbose");
@@ -50593,7 +50610,7 @@ var __webpack_exports__ = {};
     const execFile = (0, external_node_util_namespaceObject.promisify)(external_node_child_process_.execFile);
     const open_dirname = external_node_path_.dirname((0, external_node_url_namespaceObject.fileURLToPath)(__rslib_import_meta_url__));
     const localXdgOpenPath = external_node_path_.join(open_dirname, 'xdg-open');
-    const { platform, arch } = external_node_process_;
+    const { platform: open_platform, arch } = external_node_process_;
     async function getWindowsDefaultBrowserFromWsl() {
         const powershellPath = await powerShellPath();
         const rawCommand = String.raw`(Get-ItemProperty -Path "HKCU:\Software\Microsoft\Windows\Shell\Associations\UrlAssociations\http\UserChoice").ProgId`;
@@ -50686,13 +50703,13 @@ var __webpack_exports__ = {};
         let command;
         const cliArguments = [];
         const childProcessOptions = {};
-        if ('darwin' === platform) {
+        if ('darwin' === open_platform) {
             command = 'open';
             if (options.wait) cliArguments.push('--wait-apps');
             if (options.background) cliArguments.push('--background');
             if (options.newInstance) cliArguments.push('--new');
             if (app) cliArguments.push('-a', app);
-        } else if ('win32' !== platform && (!is_wsl || isInsideContainer() || app)) {
+        } else if ('win32' !== open_platform && (!is_wsl || isInsideContainer() || app)) {
             if (app) command = app;
             else {
                 const isBundled = !open_dirname || '/' === open_dirname;
@@ -50701,7 +50718,7 @@ var __webpack_exports__ = {};
                     await external_node_fs_promises_namespaceObject.access(localXdgOpenPath, external_node_fs_promises_namespaceObject.constants.X_OK);
                     exeLocalXdgOpen = true;
                 } catch  {}
-                const useSystemXdgOpen = external_node_process_.versions.electron ?? ('android' === platform || isBundled || !exeLocalXdgOpen);
+                const useSystemXdgOpen = external_node_process_.versions.electron ?? ('android' === open_platform || isBundled || !exeLocalXdgOpen);
                 command = useSystemXdgOpen ? 'xdg-open' : localXdgOpenPath;
             }
             if (appArguments.length > 0) cliArguments.push(...appArguments);
@@ -50727,7 +50744,7 @@ var __webpack_exports__ = {};
             }
             options.target = external_node_buffer_namespaceObject.Buffer.from(encodedArguments.join(' '), 'utf16le').toString('base64');
         }
-        if ('darwin' === platform && appArguments.length > 0) cliArguments.push('--args', ...appArguments);
+        if ('darwin' === open_platform && appArguments.length > 0) cliArguments.push('--args', ...appArguments);
         if (options.target) cliArguments.push(options.target);
         const subprocess = external_node_child_process_.spawn(command, cliArguments, childProcessOptions);
         if (options.wait) return new Promise((resolve, reject)=>{
@@ -50753,9 +50770,9 @@ var __webpack_exports__ = {};
         if (!archBinary) throw new Error(`${arch} is not supported`);
         return archBinary;
     }
-    function detectPlatformBinary({ [platform]: platformBinary }, { wsl }) {
+    function detectPlatformBinary({ [open_platform]: platformBinary }, { wsl }) {
         if (wsl && is_wsl) return detectArchBinary(wsl);
-        if (!platformBinary) throw new Error(`${platform} is not supported`);
+        if (!platformBinary) throw new Error(`${open_platform} is not supported`);
         return detectArchBinary(platformBinary);
     }
     const open_apps = {};
@@ -50882,6 +50899,11 @@ var __webpack_exports__ = {};
         if ("win32" === process.platform) return tokens.map(quoteForCmdShell).join(" ");
         return tokens.map(quoteForPosixShell).join(" ");
     }
+    function formatFallbackEditorLabel(preferredEditorCommand) {
+        const trimmed = preferredEditorCommand.trim();
+        if (!trimmed) return "your editor";
+        return trimmed;
+    }
     async function openPathInEditorOrDefault(targetPath, preferredEditorCommand, deps = defaultDeps) {
         if (preferredEditorCommand) if (deps.isCommandAvailable(preferredEditorCommand)) try {
             const tokens = parseCommandTokens(preferredEditorCommand);
@@ -50892,9 +50914,9 @@ var __webpack_exports__ = {};
             ]));
             return;
         } catch (error) {
-            logger_logger.warn(`Failed to open preferred editor '${preferredEditorCommand}': ${errors_getErrorMessage(error)}. Falling back to the system default app.`);
+            logger_logger.warn(`Failed to open ${formatFallbackEditorLabel(preferredEditorCommand)} automatically: ${errors_getErrorMessage(error)}.`);
         }
-        else logger_logger.warn(`Preferred editor command '${preferredEditorCommand}' was not found in PATH. Falling back to the system default app.`);
+        else logger_logger.info(`Open ${formatFallbackEditorLabel(preferredEditorCommand)} to edit your app.`);
         await deps.openSystem(targetPath);
     }
     function decideFallbackUrl(explicitUrl, availableUrls = getAvailableAnvilUrls()) {
@@ -51613,7 +51635,7 @@ var __webpack_exports__ = {};
                 if (username) logger_logger.error(`Not logged in to ${anvilUrl} as ${username}`);
                 else logger_logger.error(`Not logged in to ${anvilUrl}`);
                 logger_logger.verbose(chalk_source.yellow("Please log in first:"));
-                console.log(chalk_source.cyan(`   anvil login ${anvilUrl.replace(/^https?:\/\//, "")}`));
+                logger_logger.info(chalk_source.cyan(`   anvil login ${anvilUrl.replace(/^https?:\/\//, "")}`));
                 process.exit(1);
             }
             logger_logger.verbose(chalk_source.green("✓ Authentication tokens found"));
@@ -52803,6 +52825,54 @@ var __webpack_exports__ = {};
         await deps.logout();
         deps.resetConfig();
     }
+    function performConfigDelete(key) {
+        const allConfig = getAllConfig();
+        const existed = Object.prototype.hasOwnProperty.call(allConfig, key);
+        deleteConfig(key);
+        return {
+            existed
+        };
+    }
+    function getConfigListData() {
+        const allConfig = getAllConfig();
+        const resolvedUrl = resolveAnvilUrl();
+        const defaultUrl = isDevMode() ? "http://localhost:3000" : "https://anvil.works";
+        const authTokens = allConfig.authTokens;
+        const urls = authTokens && "object" == typeof authTokens ? Object.keys(authTokens).sort() : [];
+        const accounts = [];
+        for (const url of urls){
+            const urlData = authTokens?.[url];
+            if (!(!urlData || "object" != typeof urlData || Array.isArray(urlData))) for (const username of Object.keys(urlData).sort()){
+                const accountData = urlData[username];
+                const hasConfigTokens = !!(accountData?.authToken || accountData?.refreshToken);
+                const hasAnyTokens = hasTokensForUrl(url, username);
+                accounts.push({
+                    url,
+                    username,
+                    status: hasConfigTokens ? "config" : hasAnyTokens ? "keychain" : "none"
+                });
+            }
+        }
+        const skipKeys = new Set([
+            "anvilUrl",
+            "authTokens"
+        ]);
+        const values = {};
+        for (const [key, value] of Object.entries(allConfig))if (!skipKeys.has(key)) values[key] = value;
+        return {
+            anvilUrl: {
+                value: resolvedUrl,
+                defaultValue: defaultUrl,
+                isDefault: resolvedUrl === defaultUrl
+            },
+            authTokens: {
+                totalUrls: urls.length,
+                totalAccounts: accounts.filter((account)=>"none" !== account.status).length,
+                accounts
+            },
+            values
+        };
+    }
     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)=>{
@@ -52829,49 +52899,35 @@ var __webpack_exports__ = {};
                 process.exit(1);
             }
         });
+        configCommand.command("delete <key>").alias("unset").description("Delete a configuration value or reset it to its default").action(async (key)=>{
+            try {
+                const result = performConfigDelete(key);
+                if (result.existed) logger_logger.success(`Deleted ${key}`);
+                else logger_logger.warn(`Key '${key}' was not set; applied default/empty value if applicable.`);
+            } catch (error) {
+                logger_logger.error(error instanceof Error ? error.message : String(error));
+                process.exit(1);
+            }
+        });
         configCommand.command("list").description("List all configuration values").action(async ()=>{
             try {
-                const allConfig = getAllConfig();
+                const configData = getConfigListData();
+                if (getGlobalOutputConfig().jsonMode) return void logJsonResult(true, {
+                    data: configData
+                });
                 console.log(chalk_source.bold("\nConfiguration:"));
                 console.log(chalk_source.gray("─".repeat(50)));
-                const resolvedUrl = resolveAnvilUrl();
-                const defaultUrl = isDevMode() ? "http://localhost:3000" : "https://anvil.works";
-                const defaultHint = resolvedUrl === defaultUrl ? "" : chalk_source.gray(` (default: ${defaultUrl})`);
-                console.log(chalk_source.cyan("anvilUrl") + ` = ${resolvedUrl}${defaultHint}`);
-                const authTokens = allConfig.authTokens;
-                if (authTokens && "object" == typeof authTokens) {
-                    const urls = Object.keys(authTokens).sort();
-                    if (urls.length > 0) {
-                        let totalAccounts = 0;
-                        for (const url of urls){
-                            const urlData = authTokens[url];
-                            if (urlData && "object" == typeof urlData && !Array.isArray(urlData)) {
-                                const usernames = Object.keys(urlData);
-                                totalAccounts += usernames.filter((username)=>hasTokensForUrl(url, username)).length;
-                            }
-                        }
-                        console.log(chalk_source.cyan("authTokens") + ` = ${chalk_source.gray(`${totalAccounts} logged-in account(s) across ${urls.length} URL(s)`)}`);
-                        for (const url of urls){
-                            const urlData = authTokens[url];
-                            if (urlData && "object" == typeof urlData && !Array.isArray(urlData)) {
-                                const usernames = Object.keys(urlData).sort();
-                                if (usernames.length > 0) for (const username of usernames){
-                                    const accountData = urlData[username];
-                                    const hasConfigTokens = !!(accountData?.authToken || accountData?.refreshToken);
-                                    const hasAnyTokens = hasTokensForUrl(url, username);
-                                    const status = hasConfigTokens ? chalk_source.green("✓ logged in (config)") : hasAnyTokens ? chalk_source.green("✓ logged in (keychain)") : chalk_source.gray("(no tokens)");
-                                    console.log(chalk_source.gray(`  ${url}: ${username} ${status}`));
-                                }
-                            }
-                        }
-                    } else console.log(chalk_source.cyan("authTokens") + ` = ${chalk_source.gray("(no accounts)")}`);
+                const defaultHint = configData.anvilUrl.isDefault ? "" : chalk_source.gray(` (default: ${configData.anvilUrl.defaultValue})`);
+                console.log(chalk_source.cyan("anvilUrl") + ` = ${configData.anvilUrl.value}${defaultHint}`);
+                if (configData.authTokens.totalUrls > 0) {
+                    console.log(chalk_source.cyan("authTokens") + ` = ${chalk_source.gray(`${configData.authTokens.totalAccounts} logged-in account(s) across ${configData.authTokens.totalUrls} URL(s)`)}`);
+                    for (const account of configData.authTokens.accounts){
+                        const status = "config" === account.status ? chalk_source.green("✓ logged in (config)") : "keychain" === account.status ? chalk_source.green("✓ logged in (keychain)") : chalk_source.gray("(no tokens)");
+                        console.log(chalk_source.gray(`  ${account.url}: ${account.username} ${status}`));
+                    }
                 } else console.log(chalk_source.cyan("authTokens") + ` = ${chalk_source.gray("(none)")}`);
-                const skipKeys = new Set([
-                    "anvilUrl",
-                    "authTokens"
-                ]);
-                for (const [k, v] of Object.entries(allConfig))if (!skipKeys.has(k)) if (null === v) console.log(chalk_source.cyan(k) + ` = ${chalk_source.gray("null")}`);
-                else console.log(chalk_source.cyan(k) + ` = ${v}`);
+                for (const [key, value] of Object.entries(configData.values))if (null === value) console.log(chalk_source.cyan(key) + ` = ${chalk_source.gray("null")}`);
+                else console.log(chalk_source.cyan(key) + ` = ${value}`);
                 console.log(chalk_source.gray("─".repeat(50)));
                 console.log();
             } catch (e) {
@@ -52889,11 +52945,23 @@ var __webpack_exports__ = {};
             }
         });
     }
+    function getVersionInfo(version) {
+        return {
+            version,
+            nodeVersion: process.version,
+            platform: process.platform,
+            arch: process.arch
+        };
+    }
     function registerVersionCommand(program, version) {
         program.command("version").description("Show version information").action(()=>{
-            console.log(chalk_source.cyan.bold(`\n⚙ anvil ${version}`));
-            console.log(chalk_source.gray(`   Node.js ${process.version}`));
-            console.log(chalk_source.gray(`   Platform: ${process.platform} ${process.arch}`));
+            const info = getVersionInfo(version);
+            if (getGlobalOutputConfig().jsonMode) return void logJsonResult(true, {
+                data: info
+            });
+            console.log(chalk_source.cyan.bold(`\n⚙ anvil ${info.version}`));
+            console.log(chalk_source.gray(`   Node.js ${info.nodeVersion}`));
+            console.log(chalk_source.gray(`   Platform: ${info.platform} ${info.arch}`));
             console.log();
         });
     }
@@ -52903,6 +52971,68 @@ var __webpack_exports__ = {};
         runInteractiveLoginFlow: runInteractiveLoginFlow
     };
     const DEFAULT_ANVIL_SERVER_URL_PROMPT = "Default Anvil server URL";
+    const CUSTOM_EDITOR_CHOICE = "__custom_editor_command__";
+    function formatCustomEditorChoice(currentEditor) {
+        if (!currentEditor) return "Enter custom editor command";
+        return `Custom editor command (${currentEditor})`;
+    }
+    async function promptForPreferredEditor(currentEditor, installedEditors, ui) {
+        if (0 === installedEditors.length) {
+            ui.warn("No supported editor command was found in PATH.");
+            ui.info(chalk_source.gray("If your editor is installed, its shell command may not be available in this terminal."));
+            const action = await ui.select("Preferred editor", [
+                {
+                    name: "None",
+                    value: ""
+                },
+                {
+                    name: formatCustomEditorChoice(currentEditor),
+                    value: CUSTOM_EDITOR_CHOICE
+                }
+            ], currentEditor ? CUSTOM_EDITOR_CHOICE : "");
+            if (action !== CUSTOM_EDITOR_CHOICE) return action;
+            const customDefault = currentEditor && !preferredEditors.includes(currentEditor) ? currentEditor : "";
+            const answer = await ui.prompt([
+                {
+                    type: "input",
+                    name: "preferredEditorCommand",
+                    message: "Custom editor command",
+                    default: customDefault
+                }
+            ]);
+            return answer.preferredEditorCommand.trim();
+        }
+        if (installedEditors.length < preferredEditors.length) {
+            const unavailableCount = preferredEditors.length - installedEditors.length;
+            ui.verbose(chalk_source.gray(`${unavailableCount} supported editor(s) are not installed and were hidden.`));
+        }
+        const editorChoices = [
+            {
+                name: "None",
+                value: ""
+            },
+            ...installedEditors.map((editor)=>({
+                    name: editor,
+                    value: editor
+                })),
+            {
+                name: formatCustomEditorChoice(currentEditor),
+                value: CUSTOM_EDITOR_CHOICE
+            }
+        ];
+        const defaultValue = editorChoices.some((choice)=>choice.value === currentEditor) ? currentEditor : currentEditor ? CUSTOM_EDITOR_CHOICE : "";
+        const selectedEditor = await ui.select("Preferred editor", editorChoices, defaultValue);
+        if (selectedEditor !== CUSTOM_EDITOR_CHOICE) return selectedEditor;
+        const answer = await ui.prompt([
+            {
+                type: "input",
+                name: "preferredEditorCommand",
+                message: "Custom editor command",
+                default: currentEditor && !installedEditors.includes(currentEditor) ? currentEditor : ""
+            }
+        ]);
+        return answer.preferredEditorCommand.trim();
+    }
     async function getConfigureVersionStatus(currentVersion, latestVersionGetter = getLatestVersion) {
         const latestVersion = await latestVersionGetter();
         if (!latestVersion) return {
@@ -52961,25 +53091,11 @@ var __webpack_exports__ = {};
         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 currentEditor = String(getConfig("preferredEditor") || "").trim();
+        const currentEditorNormalized = currentEditor.toLowerCase();
         const installedEditors = getInstalledPreferredEditors();
-        if (0 === installedEditors.length) logger_logger.warn("No supported editor command was found in PATH. Leaving preferredEditor unset is recommended.");
-        else if (installedEditors.length < preferredEditors.length) {
-            const unavailableCount = preferredEditors.length - installedEditors.length;
-            logger_logger.verbose(chalk_source.gray(`${unavailableCount} supported editor(s) are not installed and were hidden.`));
-        }
-        const editorChoices = [
-            {
-                name: "None",
-                value: ""
-            },
-            ...installedEditors.map((editor)=>({
-                    name: editor,
-                    value: editor
-                }))
-        ];
-        if (currentEditor && !editorChoices.some((choice)=>choice.value === currentEditor)) logger_logger.warn(`Configured preferredEditor '${currentEditor}' is not currently available in PATH.`);
-        const selectedEditor = await logger_logger.select("Preferred editor", editorChoices, editorChoices.some((choice)=>choice.value === currentEditor) ? currentEditor : "");
+        if (currentEditor && installedEditors.length > 0 && !installedEditors.includes(currentEditorNormalized)) logger_logger.warn(`Configured preferredEditor '${currentEditor}' is not currently available in PATH.`);
+        const selectedEditor = await promptForPreferredEditor(currentEditor, installedEditors, logger_logger);
         setConfig("preferredEditor", selectedEditor);
         if (selectedEditor) logger_logger.success(`Set preferredEditor = ${selectedEditor}`);
         else logger_logger.info("Left preferredEditor unset.");
@@ -53025,11 +53141,23 @@ var __webpack_exports__ = {};
         getLatestVersion().then((latestVersion)=>{
             if (latestVersion && semver_default().valid(VERSION) && semver_default().valid(latestVersion) && semver_default().lt(VERSION, latestVersion)) {
                 logger_logger.warn("A new version of anvil is available!");
-                console.log(chalk_source.gray(`   Current: ${VERSION} → Latest: ${latestVersion}`) + chalk_source.cyan("\n   Run 'anvil update' to see update commands."));
-                console.log();
+                logger_logger.info(chalk_source.gray(`   Current: ${VERSION} → Latest: ${latestVersion}`) + chalk_source.cyan("\n   Run 'anvil update' to see update commands."));
             }
         }).catch(()=>{});
     }
+    function getUpdateInstructions(platform) {
+        if ("win32" === platform) return [
+            "try { irm https://anvil.works/install-cli.ps1 | iex } catch { npm install -g @anvil-works/anvil-cli@latest }",
+            "curl -fsSL https://anvil.works/install-cli.cmd -o install.cmd && install.cmd && del install.cmd || npm install -g @anvil-works/anvil-cli@latest",
+            "npm install -g @anvil-works/anvil-cli@latest",
+            "pnpm add -g @anvil-works/anvil-cli@latest"
+        ];
+        return [
+            "curl -fsSL https://anvil.works/install-cli.sh | sh || npm install -g @anvil-works/anvil-cli@latest",
+            "npm install -g @anvil-works/anvil-cli@latest",
+            "pnpm add -g @anvil-works/anvil-cli@latest"
+        ];
+    }
     async function handleUpdateCommand() {
         try {
             logger_logger.progress("update", "Checking for updates...");
@@ -53044,26 +53172,54 @@ var __webpack_exports__ = {};
                 process.exit(1);
             }
             if (semver_default().eq(VERSION, latestVersion)) {
-                logger_logger.success(`You're already using the latest version: ${VERSION}`);
-                console.log();
+                if (getGlobalOutputConfig().jsonMode) logJsonResult(true, {
+                    data: {
+                        currentVersion: VERSION,
+                        latestVersion,
+                        status: "up-to-date"
+                    }
+                });
+                else {
+                    logger_logger.success(`You're already using the latest version: ${VERSION}`);
+                    console.log();
+                }
                 return;
             }
             if (semver_default().gt(VERSION, latestVersion)) {
-                logger_logger.warn(`You're using version ${VERSION}, which is newer than the latest published version ${latestVersion}.`);
-                console.log(chalk_source.gray("   This might be a development build."));
-                console.log();
+                if (getGlobalOutputConfig().jsonMode) logJsonResult(true, {
+                    data: {
+                        currentVersion: VERSION,
+                        latestVersion,
+                        status: "ahead",
+                        note: "This might be a development build."
+                    }
+                });
+                else {
+                    logger_logger.warn(`You're using version ${VERSION}, which is newer than the latest published version ${latestVersion}.`);
+                    console.log(chalk_source.gray("   This might be a development build."));
+                    console.log();
+                }
                 return;
             }
+            const instructions = getUpdateInstructions(process.platform);
+            if (getGlobalOutputConfig().jsonMode) return void logJsonResult(true, {
+                data: {
+                    currentVersion: VERSION,
+                    latestVersion,
+                    status: "update-available",
+                    instructions
+                }
+            });
             logger_logger.warn(`↑ Update available: ${VERSION} → ${latestVersion}`);
             console.log();
             console.log(chalk_source.cyan("To update, run one of the following commands:"));
             console.log();
             if ("win32" === process.platform) {
-                console.log(chalk_source.gray("  PowerShell: ") + chalk_source.white("try { irm https://anvil.works/install-cli.ps1 | iex } catch { npm install -g @anvil-works/anvil-cli@latest }"));
-                console.log(chalk_source.gray("  CMD:        ") + chalk_source.white("curl -fsSL https://anvil.works/install-cli.cmd -o install.cmd && install.cmd && del install.cmd || npm install -g @anvil-works/anvil-cli@latest"));
-            } else console.log(chalk_source.gray("  macOS/Linux: ") + chalk_source.white("curl -fsSL https://anvil.works/install-cli.sh | sh || npm install -g @anvil-works/anvil-cli@latest"));
-            console.log(chalk_source.gray("  npm:         ") + chalk_source.white("npm install -g @anvil-works/anvil-cli@latest"));
-            console.log(chalk_source.gray("  pnpm:        ") + chalk_source.white("pnpm add -g @anvil-works/anvil-cli@latest"));
+                console.log(chalk_source.gray("  PowerShell: ") + chalk_source.white(instructions[0]));
+                console.log(chalk_source.gray("  CMD:        ") + chalk_source.white(instructions[1]));
+            } else console.log(chalk_source.gray("  macOS/Linux: ") + chalk_source.white(instructions[0]));
+            console.log(chalk_source.gray("  npm:         ") + chalk_source.white(instructions[instructions.length - 2]));
+            console.log(chalk_source.gray("  pnpm:        ") + chalk_source.white(instructions[instructions.length - 1]));
             console.log();
         } catch (e) {
             logger_logger.error("Error: " + e.message);
@@ -53071,7 +53227,7 @@ var __webpack_exports__ = {};
         }
     }
     function addGlobalOptionsHelp(command) {
-        if ("help" !== command.name()) command.addHelpText("after", "\n" + chalk_source.bold("Global Options:") + "\n  -V, --verbose  Show detailed output\n");
+        if ("help" !== command.name()) command.addHelpText("after", "\n" + chalk_source.bold("Global Options:") + "\n  --json         Output in JSON format (NDJSON) for scripting/LLM consumption\n  -V, --verbose  Show detailed output\n");
         command.commands.forEach((subcommand)=>addGlobalOptionsHelp(subcommand));
     }
     function buildProgram() {

package/package.json

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