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": "user@gmail.com", "mail_password": "password", "auto_email_id": "noreply@mysite.com", "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 user@example.com
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