anvil-sync

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

npm install -g @anvil-works/anvil-sync

Quick Start

0. Clone Your App (Required)

anvil-sync watches a local clone of your Anvil app. If you haven't cloned the app yet, follow the cloning guide first:

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:

anvil-sync login

This will:

1. Open your browser to the Anvil OAuth authorization page
2. Prompt you to authorize anvil-sync to access your Anvil account
3. Automatically complete the authentication flow

Your access and refresh tokens are stored in:

• macOS: ~/Library/Preferences/anvil-sync/config.json
• Linux: ~/.config/anvil-sync/config.json
• Windows: %APPDATA%\anvil-sync\Config\config.json

Smart URL Handling: You can specify the Anvil server URL directly:

# These all work - anvil-sync automatically adds https://
anvil-sync login anvil.works
anvil-sync login anvil.mycompany.com

# localhost automatically uses http://
anvil-sync login localhost:3000

# Full URLs also work
anvil-sync login https://anvil.works

Multiple Accounts: anvil-sync 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 for Changes

Navigate to your local Anvil app directory and start watching:

cd /path/to/your/anvil/app
anvil-sync

Or use the explicit watch command:

anvil-sync watch

Or use the short form:

anvil-sync w

You can specify the app ID explicitly:

anvil-sync -A YOUR_APP_ID

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
• -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 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-sync  │◄────►│ 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-sync
• Anvil → Local: Changes made in the Anvil IDE are automatically detected and synced back to your local files via git fetch through anvil-sync

CLI Commands

| Command | Description | | ------------------------------------------ | -------------------------------------------------------------------- | | anvil-sync or anvil-sync watch [path] | Watch directory for changes and sync to Anvil (default) | | anvil-sync watch -V or --verbose | Watch with verbose logging (detailed output) | | anvil-sync w [path] | Short form for watch | | anvil-sync login [anvil-server-url] | Authenticate with Anvil using OAuth (supports smart URL handling) | | anvil-sync l [anvil-server-url] | Short form for login | | anvil-sync logout [anvil-server-url] | Logout from Anvil (optionally specify URL for specific installation) | | anvil-sync config <action> [key] [value] | Manage configuration (set, get, list) | | anvil-sync c <action> [key] [value] | Short form for config | | anvil-sync version | Show version information | | anvil-sync -h, --help | Show help message | | anvil-sync -v, --version | Show version number |

App ID Detection

anvil-sync 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:

anvil-sync -A YOUR_APP_ID

Anvil URL Detection

anvil-sync 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:

# Auto-detect from git remote
anvil-sync watch

# Specify URL explicitly
anvil-sync watch --url anvil.works
anvil-sync watch --url localhost:3000
anvil-sync watch --url anvil.mycompany.com

# If multiple accounts, you'll be prompted to select
anvil-sync watch
# ? 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-sync/config.json
• Linux: ~/.config/anvil-sync/config.json
• Windows: %APPDATA%\anvil-sync\Config\config.json

Stored Configuration

{
    "authTokens": {
        "https://anvil.works": {
            "authToken": "your-access-token",
            "refreshToken": "your-refresh-token",
            "authTokenExpiresAt": 1234567890,
            "username": "[email protected]"
        },
        "https://anvil.company.com": {
            "authToken": "another-token",
            "refreshToken": "another-refresh",
            "authTokenExpiresAt": 1234567890,
            "username": "[email protected]"
        }
    },
    "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-sync shows minimal output. For more detailed logging:

One-time: Use the -V or --verbose flag:

anvil-sync watch --verbose

Persistent: Set verbose mode in config:

anvil-sync 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)

# Login to your enterprise installation
anvil-sync login anvil.mycompany.com

# Or with full URL
anvil-sync login https://anvil.mycompany.com

Option 2: Specify URL when watching

# Watch with specific URL
anvil-sync watch --url anvil.mycompany.com

Option 3: Set global default

anvil-sync config set anvilUrl https://anvil.mycompany.com
anvil-sync login

Multiple Installations:

anvil-sync supports multiple Anvil installations simultaneously. Each installation has its own authentication tokens:

# Login to multiple installations
anvil-sync login anvil.works
anvil-sync login anvil.company-a.com
anvil-sync login anvil.company-b.com

# When watching, you'll be prompted to select which one to use
# Or specify explicitly:
anvil-sync watch --url anvil.company-a.com

URL Resolution Priority:

1. Explicit --url flag
2. Git remote detection (from current repository)
3. User prompt (if multiple accounts available)
4. anvilUrl in config file
5. Default based on NODE_ENV:
   • Production: https://anvil.works
   • Development: http://localhost:3000

View all configuration:

anvil-sync config list

Logout

Logout from Anvil installations:

Logout from all accounts:

anvil-sync logout

Logout from specific installation:

anvil-sync logout anvil.works
anvil-sync logout anvil.mycompany.com
anvil-sync logout --url localhost:3000

Multiple accounts: If you have multiple accounts and run anvil-sync 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-sync 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:

anvil-sync 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:

  anvil-sync config set anvilUrl https://anvil.works

• Or reset all config values (also clears custom URLs):

  anvil-sync config reset

License

ISC