frappe-ops-bench

# 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

```bash
# 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

```bash
# 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

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

### Dropping a Site

```bash
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

```bash
# 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

```bash
# 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

```bash
# 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
- After adding/modifying DocTypes
- After pulling code changes
- **NEVER** skip migrate after code changes — leads to schema mismatches

---

## Workflow 6: bench build

```bash
# Build all apps
bench build

# Build specific app
bench build --app myapp

# Build with bundle analyzer
bench build --app myapp --production

# Watch mode (auto-rebuild on file changes)
bench watch
```

### When to Build

- After changing JS/CSS files
- After `bench get-app` (done automatically)
- After modifying `package.json`
- **ALWAYS** build after modifying client-side assets

---

## Workflow 7: Console and Database Access

```bash
# IPython console (with Frappe loaded)
bench --site mysite console
#