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

curl -fsSL https://anvil.works/install-cli.sh | sh

Windows PowerShell

irm https://anvil.works/install-cli.ps1 | iex

Windows CMD

curl -fsSL https://anvil.works/install-cli.cmd -o install.cmd && install.cmd && del install.cmd

Manual Fallback

npm install -g @anvil-works/anvil-cli@latest

Quick Start

1. Run Configure (Recommended First Step)

Start with guided setup for your default server URL and login:

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.

2. Check Out Your App from the IDE URL

Copy your app URL from the Anvil IDE (for example https://anvil.works/build/apps/W36XUTXGNPDK6VEA) and run:

anvil checkout https://anvil.works/build/apps/W36XUTXGNPDK6VEA my-app
cd my-app

3. Watch Your Changes

When you're ready to sync local edits in real-time:

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

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:

# 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

Checkout Apps

anvil checkout accepts an editor URL, git URL, bare app ID, or no input for interactive selection:

# Interactive search/select (ordered by most recently edited)
anvil checkout

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

In non-interactive mode, pass an explicit app input:

• anvil checkout APPID
• anvil checkout https://anvil.works/git/APPID.git

# Checkout from editor URL
anvil checkout http://localhost:3000/build/apps/MHVELZG5SZXK2POE/code/assets/theme.css

# Checkout from git URL
anvil checkout https://anvil.works/git/MHVELZG5SZXK2POE.git

# Checkout from app ID (specify URL when needed)
anvil checkout MHVELZG5SZXK2POE --url anvil.works

# Explicit destination directory
anvil checkout MHVELZG5SZXK2POE my-local-app --url anvil.works

# Clone-style options
anvil checkout MHVELZG5SZXK2POE --branch master --depth 1 --single-branch
anvil checkout MHVELZG5SZXK2POE --origin upstream
anvil checkout MHVELZG5SZXK2POE --quiet

# Seed interactive search query
anvil checkout -Q "dashboard"
anvil checkout --query "dashboard"

# Open watched path in editor/default app
anvil watch -O
anvil watch ./my-app -O

Safety behavior:

• Blocks checkout into non-empty destination directories (unless --force).
• Blocks checkout into paths inside an existing git repository (unless --force).

Git HTTPS credentials:

• Checkout configures a clean HTTPS remote URL plus a repo-local Git credential helper (anvil git-credential).
• The helper retrieves short-lived access tokens from your logged-in account and refreshes them as needed.
• Per-app bindings are stored in local git config (anvil.auth.<APPID>.url and anvil.auth.<APPID>.username) so multi-account repos stay deterministic.

Checkout options:

• -O, --open - Open destination after checkout
• -b, --branch <BRANCH> - Checkout a specific branch
• --depth <N> - Shallow clone with N commits of history
• --single-branch - Clone only one branch
• --origin <NAME> - Use custom remote name instead of origin
• --quiet - Suppress git clone progress output
• --verbose - Verbose git clone output
• -f, --force - Override destination safety checks
• -u, --url <ANVIL_URL> - Override detected Anvil URL
• -U, --user <USERNAME> - Use a specific logged-in account

If multiple accounts are logged in for the same URL, anvil checkout will prompt you to select one (interactive mode) or require --user in non-interactive mode.

Configuration

Authentication

Use anvil login to authenticate with Anvil:

anvil login

The login flow will:

1. Open your browser to the Anvil OAuth authorization page
2. Prompt you to authorize anvil-cli
3. Complete authentication automatically in the CLI

Your access and refresh tokens are stored in:

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

Smart URL handling:

# anvil automatically adds https://
anvil login anvil.works
anvil login anvil.mycompany.com

# localhost uses http://localhost:3000
anvil login localhost:3000

# full URLs also work
anvil login https://anvil.works

anvil-cli supports multiple Anvil installations simultaneously. Each URL has its own authentication tokens.

Config File Location

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

Stored Configuration

config.json stores settings and auth metadata. OAuth secrets are stored in the OS keychain when available.

{
    "anvilUrl": "https://anvil.works",
    "verbose": false,
    "preferredEditor": "cursor",
    "authTokens": {
        "https://anvil.works": {
            "[email protected]": {
                "authToken": null,
                "refreshToken": null,
                "authTokenExpiresAt": 1735689600
            }
        }
    }
}

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:

anvil watch --verbose

Persistent: Set verbose mode in config:

anvil config set verbose true

Preferred Editor

Set this during anvil configure.

If needed later, you can still set it manually with:

anvil config set preferredEditor <editor>

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)

# 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

# Sync with specific URL
anvil watch --url anvil.mycompany.com

Option 3: Set global default

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:

# 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

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:

anvil config list

Logout

Logout from Anvil installations:

Logout from all accounts:

anvil logout

Logout from specific installation:

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:

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:

  anvil config set anvilUrl https://anvil.works

• Or reset all config values (also clears custom URLs and logs out all accounts):

  anvil config reset

License

MIT