/frappe-ops-bench

name: frappe-ops-bench
description: >
  Use when running bench commands, managing sites, configuring multi-tenancy, or setting up domains.
  Prevents misconfigured bench environments, broken site routing, and DNS mismatches.
  Covers bench CLI commands, site creation, bench init, multi-tenancy setup, DNS-based routing, common-site-config.
  Keywords: bench, site, multi-tenancy, domains, bench init, bench new-site, bench setup, common_site_config, bench command not working, site setup, multi-tenant, domain routing, new site..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

Bench CLI Complete Reference

Complete bench CLI reference for site management, app lifecycle, configuration, and multi-tenancy.

**Version**: v14/v15/v16

---

Quick Reference: Essential Commands

| Task | Command | |------|---------| | Create bench | `bench init myproject --frappe-branch version-15` | | Create site | `bench new-site mysite.localhost --admin-password admin` | | Set default site | `bench use mysite.localhost` | | Get app | `bench get-app erpnext --branch version-15` | | Install app | `bench --site mysite install-app erpnext` | | Start dev server | `bench start` | | Run migrations | `bench --site mysite migrate` | | Build assets | `bench build --app myapp` | | Backup site | `bench --site mysite backup` | | Restore backup | `bench --site mysite restore /path/to/backup.sql.gz` | | Open console | `bench --site mysite console` | | Open DB shell | `bench --site mysite mariadb` | | Check scheduler | `bench doctor` | | View pending jobs | `bench show-pending-jobs` | | Update everything | `bench update` | | Drop site | `bench drop-site mysite --force` |

---

Workflow 1: Creating a New Bench

# Initialize bench with specific Frappe version
bench init myproject --frappe-branch version-15

# With Python version
bench init myproject --frappe-branch version-15 --python python3.11

# Enter bench directory (REQUIRED for all subsequent commands)
cd myproject

**What `bench init` creates:**

myproject/
├── apps/           # Installed Frappe apps (frappe is default)
├── sites/          # All sites and shared config
│   └── common_site_config.json
├── config/         # Redis, Procfile, supervisor configs
├── env/            # Python virtual environment
├── logs/           # Log files
└── Procfile        # Process definitions for bench start

Critical Rules

• **ALWAYS** specify `--frappe-branch` to pin Frappe version
• **ALWAYS** run commands from inside the bench directory
• **NEVER** run bench commands as root — use a dedicated frappe user

---

Workflow 2: Site Management

Creating Sites

# Basic site creation
bench new-site mysite.localhost --admin-password admin

# With specific database
bench new-site mysite.localhost --db-name mysite_db --admin-password admin

# With MariaDB root password
bench new-site mysite.localhost --mariadb-root-password rootpass --admin-password admin

# Install apps during creation
bench new-site mysite.localhost --admin-password admin --install-app erpnext

Setting Default Site

bench use mysite.localhost
# OR set environment variable for current session:
export FRAPPE_SITE=mysite.localhost

Dropping a Site

bench drop-site mysite.localhost --force
# Deletes database and archives site directory

Site Directory Structure

sites/mysite.localhost/
├── site_config.json     # Site-specific config (db credentials)
├── private/             # Auth-required files, backups
├── public/              # Publicly accessible files
├── locks/               # Scheduler lock files
└── task-logs/           # Scheduler task logs

---

Workflow 3: App Management

# Download app from GitHub
bench get-app erpnext --branch version-15
bench get-app https://github.com/org/custom-app.git --branch main

# Install app on a site
bench --site mysite install-app erpnext

# List installed apps
bench --site mysite list-apps

# Remove app from site (creates backup first)
bench --site mysite uninstall-app custom_app

# Remove app from bench entirely
bench remove-app custom_app

# Switch app branch
bench switch-to-branch version-15 erpnext frappe

# Exclude app from updates
bench exclude-app custom_app

# Re-include app in updates
bench include-app custom_app

Critical Rules

• **ALWAYS** `get-app` before `install-app` — get downloads, install activates
• **ALWAYS** backup before `uninstall-app` — it deletes app-related data
• **NEVER** manually delete app folders — use `bench remove-app`

---

Workflow 4: bench update: What It Does

# Full update (pull + migrate + build + restart)
bench update

# Update specific app only
bench update --pull --app erpnext

# Skip build step
bench update --no-build

# Skip backup
bench update --no-backup

# Reset to upstream (DESTROYS local changes)
bench update --reset

**`bench update` executes these steps in order:** 1. Backup all sites 2. Pull latest code for all apps (`git pull`) 3. Install Python/Node requirements 4. Build static assets (`bench build`) 5. Run migrations on all sites (`bench migrate`) 6. Restart bench processes

Critical Rules

• **ALWAYS** run `bench update` in a screen/tmux session — it takes time
• **NEVER** use `--reset` in production without understanding it does `git reset --hard`
• **ALWAYS** test updates on staging first

---

Workflow 5: bench migrate

# Migrate specific site
bench --site mysite migrate

# Migrate all sites
bench --site all migrate

# Check if safe to migrate (no pending jobs)
bench --site mysite ready-for-migration

**What `bench migrate` does:** 1. Runs schema sync (DocType changes → database) 2. Runs patches (data migrations) 3. Rebuilds search index 4. Syncs translations 5. Rebuilds Dashboard cache

When to Migrate

• After `bench update` (done automatically)
• After changing hooks.py
• A