bench-commands

name	bench-commands
description	Frappe Bench CLI command reference for site management, app management, development, and production operations. Use when running bench commands, managing sites, migrations, builds, or deployments.

Bench CLI Commands Reference

Complete reference for the Frappe Bench command-line interface for managing Frappe/ERPNext installations.

When to Use This Skill

• Running bench commands for development
• Managing Frappe sites
• Installing and updating apps
• Running migrations and builds
• Setting up production environments
• Troubleshooting common issues

Bench Directory Structure

frappe-bench/
├── apps/                   # Frappe apps
│   ├── frappe/            # Core framework
│   ├── erpnext/           # ERPNext (if installed)
│   └── my_app/            # Custom apps
├── sites/                  # Sites directory
│   ├── common_site_config.json
│   ├── apps.txt           # List of installed apps
│   └── my_site.local/     # Individual site
│       ├── site_config.json
│       ├── private/
│       └── public/
├── config/                 # Configuration files
├── logs/                   # Log files
├── env/                    # Python virtual environment
└── node_modules/          # Node.js dependencies

Site Management

Create Site

# Create new site
bench new-site mysite.local

# With specific database
bench new-site mysite.local --db-name mysite_db

# With MariaDB root password
bench new-site mysite.local --mariadb-root-password mypassword

# With admin password
bench new-site mysite.local --admin-password admin123

# From SQL file
bench new-site mysite.local --source_sql /path/to/backup.sql

# Skip creating default user
bench new-site mysite.local --no-mariadb-socket

Use Site

# Set default site
bench use mysite.local

# Run command on specific site
bench --site mysite.local migrate

# Run on all sites
bench --site all migrate

Site Operations

# List all sites
bench list-sites

# Drop site (delete)
bench drop-site mysite.local

# Drop with force
bench drop-site mysite.local --force

# Set site maintenance mode
bench --site mysite.local set-maintenance-mode on
bench --site mysite.local set-maintenance-mode off

# Disable scheduler
bench --site mysite.local disable-scheduler
bench --site mysite.local enable-scheduler

Backup & Restore

# Backup site
bench --site mysite.local backup

# Backup with files
bench --site mysite.local backup --with-files

# Backup all sites
bench --site all backup

# Restore from backup
bench --site mysite.local restore /path/to/backup.sql.gz

# Restore with files
bench --site mysite.local restore /path/to/backup.sql.gz \
  --with-private-files /path/to/private.tar \
  --with-public-files /path/to/public.tar

App Management

Get Apps

# Get app from GitHub
bench get-app https://github.com/frappe/erpnext

# Get specific branch
bench get-app https://github.com/frappe/erpnext --branch version-14

# Get specific tag
bench get-app https://github.com/frappe/erpnext --tag v14.0.0

# Get from local path
bench get-app /path/to/my_app

# Get and install on all sites
bench get-app erpnext --install-all

Install/Uninstall Apps

# Install app on site
bench --site mysite.local install-app erpnext

# Install app on all sites
bench --site all install-app my_app

# Uninstall app
bench --site mysite.local uninstall-app my_app

# Uninstall with force (removes data)
bench --site mysite.local uninstall-app my_app --yes --force

Create New App

# Create new app
bench new-app my_app

# App will be created in apps/ directory with:
# - my_app/my_app/
# - hooks.py
# - modules.txt
# - patches.txt
# - requirements.txt

Update Apps

# Update all apps
bench update

# Update without migrations
bench update --no-migrations

# Update specific app
bench update --apps erpnext

# Update without pulling
bench update --no-pull

# Update without building assets
bench update --no-build

# Reset to fresh install
bench update --reset

Remove App

# Remove app from bench (not from sites)
bench remove-app my_app

# Remove from site first
bench --site mysite.local uninstall-app my_app
bench remove-app my_app

Development Commands

Start Development Server

# Start development server (web + redis + scheduler)
bench start

# Start with specific workers
bench start --procfile Procfile.dev

# Start only web server
bench serve

# Start on specific port
bench serve --port 8001

Build Assets

# Build assets (JS/CSS)
bench build

# Build specific app
bench build --app my_app

# Build with verbose output
bench build --verbose

# Build production assets
bench build --production

# Build and minify
bench build --make-copy

# Watch for changes
bench watch

Migrate

# Run migrations
bench --site mysite.local migrate

# Migrate all sites
bench --site all migrate

# Migrate specific app
bench --site mysite.local migrate --app my_app

# Skip failing patches
bench --site mysite.local migrate --skip-failing

Clear Cache

# Clear cache
bench --site mysite.local clear-cache

# Clear all cache including redis
bench --site mysite.local clear-website-cache

# Clear redis cache
bench clear-redis-cache

Console

# Open Python console
bench --site mysite.local console

# In console:
# >>> doc = frappe.get_doc("Customer", "CUST-001")
# >>> doc.customer_name
# >>> frappe.db.sql("SELECT * FROM tabCustomer")

# Run Python script
bench --site mysite.local execute myapp.scripts.my_function

# Execute with arguments
bench --site mysite.local execute myapp.scripts.my_function --args='["arg1", "arg2"]'

MariaDB Console

# Open MariaDB console
bench --site mysite.local mariadb

# Run SQL query
bench --site mysite.local mariadb -e "SELECT * FROM tabCustomer LIMIT 5"

Run Tests

# Run all tests
bench --site mysite.local run-tests

# Run tests for specific app
bench --site mysite.local run-tests --app my_app

# Run specific test
bench --site mysite.local run-tests --module my_app.my_module.doctype.my_doctype.test_my_doctype

# Run with coverage
bench --site mysite.local run-tests --coverage

# Run specific test class
bench --site mysite.local run-tests --doctype "My DocType"

# Run parallel tests
bench --site mysite.local run-tests --parallel

# Skip test setup
bench --site mysite.local run-tests --skip-setup

Translation

# Update translation files
bench --site mysite.local update-translations

# Export translations
bench --site mysite.local export-translations

# Import translations
bench --site mysite.local import-translations /path/to/translations.csv

Production Setup

Setup Production

# Setup for production (systemd, nginx, supervisor)
sudo bench setup production frappe-user

# Setup supervisor
bench setup supervisor

# Setup systemd
bench setup systemd

# Setup nginx
bench setup nginx

# Setup Redis
bench setup redis

# Setup fail2ban
bench setup fail2ban

SSL/Let's Encrypt

# Setup Let's Encrypt SSL
sudo bench setup lets-encrypt mysite.local

# Renew certificates
sudo bench renew-lets-encrypt

Restart Services

# Restart supervisor
sudo supervisorctl restart all

# Restart specific
sudo supervisorctl restart frappe-bench-web:*
sudo supervisorctl restart frappe-bench-workers:*

# Restart systemd
sudo systemctl restart frappe-bench-web
sudo systemctl restart frappe-bench-schedule

# Check status
sudo supervisorctl status

Scheduler & Workers

Scheduler

# Enable scheduler
bench --site mysite.local enable-scheduler

# Disable scheduler
bench --site mysite.local disable-scheduler

# Check scheduler status
bench --site mysite.local show-scheduler-status

# Run specific scheduled job
bench --site mysite.local execute frappe.tasks.run_daily

Background Jobs

# Show queued jobs
bench --site mysite.local show-pending-jobs

# Clear failed jobs
bench --site mysite.local clear-website-cache

# Run specific queue
bench worker --queue default
bench worker --queue short
bench worker --queue long

# Purge jobs
bench --site mysite.local purge-jobs

Configuration

Site Config

# Show site config
bench --site mysite.local show-config

# Set config value
bench --site mysite.local set-config key value

# Set config with JSON value
bench --site mysite.local set-config limits '{"users": 10}'

# Set common config (all sites)
bench set-config key value

# Remove config
bench --site mysite.local remove-config key

Common Configurations

# site_config.json
{
    "db_name": "mysite_db",
    "db_password": "password",
    "db_type": "mariadb",
    "encryption_key": "xxxxx",
    "developer_mode": 0,
    "maintenance_mode": 0,
    "pause_scheduler": 0,
    "mail_server": "smtp.gmail.com",
    "mail_port": 587,
    "use_tls": 1,
    "mail_login": "[e-mail]",
    "mail_password": "password",
    "auto_email_id": "[e-mail]",
    "mute_emails": 0,
    "enable_scheduler": 1,
    "limits": {
        "users": 10,
        "emails": 500,
        "space": 5120
    }
}

Bench Config

# Show bench config
bench config list

# Set bench config
bench config set serve_port 8001
bench config set redis_cache_port 13000

# Common bench configs
bench config set developer_mode 1
bench config set webserver_port 8000
bench config set background_workers 1

Troubleshooting Commands

Logs

# View logs
tail -f logs/frappe.log
tail -f logs/web.error.log
tail -f logs/worker.error.log
tail -f logs/scheduler.error.log

# Site-specific logs
tail -f sites/mysite.local/logs/frappe.log

Debug

# Check site health
bench --site mysite.local doctor

# Show database stats
bench --site mysite.local show-db-size

# Show table sizes
bench --site mysite.local --db-type mariadb execute \
  "SELECT table_name, data_length FROM information_schema.tables WHERE table_schema = 'mysite_db'"

# Check scheduled jobs
bench --site mysite.local show-scheduler-status

# Reset password
bench --site mysite.local set-admin-password newpassword

# Add system manager
bench --site mysite.local add-system-manager [e-mail]

Fix Common Issues

# Rebuild search index
bench --site mysite.local build-search-index

# Reset desk customizations
bench --site mysite.local reset-perms

# Clear all locks
bench --site mysite.local clear-locks

# Reinstall
bench --site mysite.local reinstall --yes

# Partial restore
bench --site mysite.local partial-restore /path/to/backup.sql

Version Management

# Check versions
bench version

# Switch branch
bench switch-to-branch version-14 frappe erpnext

# Switch to develop
bench switch-to-branch develop --upgrade

# Set version
bench set-bench-version 5.x

Multi-Tenancy

# Setup multi-tenancy
bench config dns_multitenant on

# Add domain to site
bench --site mysite.local add-domain newdomain.com

# Remove domain
bench --site mysite.local remove-domain newdomain.com

# Setup wildcard SSL
sudo certbot certonly --webroot -w /var/www/letsencrypt -d *.mydomain.com

Common Workflows

Fresh Install

# Install bench
pip install frappe-bench

# Initialize bench
bench init frappe-bench
cd frappe-bench

# Get ERPNext
bench get-app erpnext

# Create site
bench new-site mysite.local

# Install ERPNext
bench --site mysite.local install-app erpnext

# Start development server
bench start

Daily Development

# Pull latest changes
bench update --no-backup

# Or step by step:
cd apps/frappe && git pull
cd apps/erpnext && git pull
bench update --no-pull

# Clear cache after code changes
bench --site mysite.local clear-cache

# Build assets
bench build --app my_app

Deploy Update

# On production server
cd /home/frappe/frappe-bench

# Set maintenance mode
bench --site mysite.local set-maintenance-mode on

# Backup
bench --site mysite.local backup --with-files

# Update
bench update

# Migrate
bench --site mysite.local migrate

# Build assets
bench build --production

# Clear cache
bench --site mysite.local clear-cache

# Restart
sudo supervisorctl restart all

# Disable maintenance mode
bench --site mysite.local set-maintenance-mode off