Start Free
عربي
Technical Tutorials 11 min read

ERPNext Bench CLI: Every Command Explained by a DevOps Engineer

Bench is the command-line tool that controls everything in an ERPNext installation. Think of it like git: git has commit, push, pull and merge, and bench has update, migrate, restore and deploy. Most references only list the commands. This one explains what each command actually does, when you should use it, and what can go wrong, so you understand the tool instead of copying lines you do not understand.

First, How Bench Works (Read This Once)

Bench is a Python tool. When you run 'bench update' it runs git pull in each app folder, checks whether the Python requirements changed, runs the database migration scripts, then rebuilds the JavaScript assets. Once you know that sequence, a failure tells you which step broke and why. Every bench command runs from inside the frappe-bench directory (~/frappe-bench), as the frappe user. Run them as root or from the wrong folder and they either fail or leave you with permission problems.

bash 
# Always start here before running bench commands
cd ~/frappe-bench

# Verify you are in the right place
pwd
# Should output: /home/frappe/frappe-bench

# Verify you are the frappe user
whoami
# Should output: frappe

Site Management Commands

A 'site' in ERPNext is one isolated database plus its own configuration: one company. These commands cover the whole life of a site, from creating it to deleting it.

bash 
# Create a new site
# What it does: Creates a new MariaDB database, runs all migrations, creates admin user
# When to use: When setting up a new company/tenant on the same server
bench new-site mycompany.com \
  --mariadb-root-password DB_ROOT_PASS \
  --admin-password ADMIN_PASS \
  --no-mariadb-socket

# List all sites on this bench
# What it does: Shows every site folder in the sites/ directory
bench --site all list-apps

# Set a default site (saves typing --site every command)
# What it does: Writes the site name to sites/currentsite.txt
bench use mycompany.com

# Enable maintenance mode (blocks user access, shows 'under maintenance')
# When to use: Before updates or migrations to prevent data changes
bench --site mycompany.com set-maintenance-mode on
bench --site mycompany.com set-maintenance-mode off

# Clear cached data
# When to use: After configuration changes that are not reflecting, or after updates
bench --site mycompany.com clear-cache
bench --site mycompany.com clear-website-cache  # Clears web page cache

# DANGER: Delete a site permanently (no recovery possible)
# What it does: Drops the entire database AND removes all files
# Use with extreme caution — there is no undo
bench drop-site mycompany.com --root-password DB_ROOT_PASS
drop-site is Permanent

bench drop-site deletes the database completely. There is no recycle bin. No undo. If you run this without a backup, your data is gone forever. Always take a backup and verify it before running drop-site.

App Management Commands

ERPNext is built from 'apps': Frappe (the framework), ERPNext (the main app), HRMS (the HR module), and any custom app you add. These commands decide which apps sit on the server and which sites actually use them.

bash 
# Download an app from GitHub onto this bench
# What it does: git clone of the app repository into apps/
bench get-app erpnext --branch version-15
bench get-app hrms --branch version-15

# Download a custom app from a private repository
bench get-app https://github.com/yourcompany/custom-app.git
# If private: Use SSH key authentication on the server first

# Install an app on a specific site (adds its tables to the database)
# What it does: Runs all migration scripts for that app on that site
bench --site mycompany.com install-app erpnext
bench --site mycompany.com install-app hrms

# List all apps installed on a site
bench --site mycompany.com list-apps

# Uninstall an app from a site (removes its data — irreversible)
bench --site mycompany.com uninstall-app hrms --yes

# Remove an app from bench entirely (removes the code folder)
bench remove-app hrms
The Difference Between get-app, install-app and remove-app

get-app downloads the code onto the server. install-app activates it for one site and creates that app's database tables. uninstall-app deactivates it on a site and deletes that site's data for it. remove-app deletes the code from the server entirely. An app can sit downloaded on the bench without being installed on any site.

Backup and Restore Commands — The Most Critical Commands You Will Use

These are the most important commands. If you ever need to restore data, these are what you use. Practice the restore process BEFORE you need it in an emergency.

bash 
# Take a complete backup (database + all uploaded files)
# What it does: mysqldump of the database + tar of files directory
# Backup files stored at: sites/mycompany.com/private/backups/
bench --site mycompany.com backup --with-files

# Database-only backup (faster, no file attachments)
bench --site mycompany.com backup

# List existing backups
ls -lh sites/mycompany.com/private/backups/

# Restore from a database backup
# What it does: Drops and recreates the database, then imports the backup
bench --site mycompany.com restore \
  sites/mycompany.com/private/backups/20260405_020000-mycompany_com-database.sql.gz

# Restore with files (both database AND uploaded files)
bench --site mycompany.com restore \
  sites/mycompany.com/private/backups/20260405_020000-mycompany_com-database.sql.gz \
  --with-private-files \
  sites/mycompany.com/private/backups/20260405_020000-mycompany_com-private-files.tar.gz \
  --with-public-files \
  sites/mycompany.com/private/backups/20260405_020000-mycompany_com-public-files.tar.gz
Automate Backups with Cron

As the frappe user, add this to crontab (crontab -e): 30 2 * * * cd /home/frappe/frappe-bench && bench --site mycompany.com backup --with-files >> /home/frappe/backup.log 2>&1

Database and Migration Commands

These commands talk to the database directly. Read each one before you run it: a mistake here reaches live records, not a test copy.

bash 
# Run pending database migrations
# What it does: Applies any new patch files that have not run yet
# When to use: After updates, after installing new apps
bench --site mycompany.com migrate

# Open the MariaDB console for direct SQL
# What it does: Opens mysql client connected to the site's database
# When to use: For debugging data issues — use VERY carefully
bench --site mycompany.com mariadb

# Open Python console with Frappe context
# What it does: Python REPL with frappe.db, frappe.get_doc, etc. available
# When to use: For debugging Python-level issues or running maintenance scripts
bench --site mycompany.com console

# Check site for errors and inconsistencies
# What it does: Checks scheduler, database connection, installed apps
bench --site mycompany.com doctor

# Rebuild the search index (global search)
# When to use: After migrating data or when search results are missing records
bench --site mycompany.com rebuild-global-search
'bench mariadb' Can Delete Everything

'bench mariadb' gives you raw SQL access to the live database. One wrong UPDATE or DELETE skips every ERPNext validation and can corrupt your accounting data for good. Run SELECT first, always test on a copy, and never experiment on production. This is the risk a managed platform takes off the table. Managely is a platform as well as a product: background workers, multiple servers and Git-to-live deploys, but no root shell and no command that can reach live data by accident. Each company still gets an isolated database and its own domain, and you can export your data whenever you want.

Update and Build Commands

bash 
# Full update: pull code + run migrations + rebuild assets
# What it does: All three steps in sequence
bench update

# Pull code only (no migration, no asset rebuild)
# When to use: To see what changed before running migrations
bench update --pull

# Apply migrations only (no code pull)
# When to use: After manually changing branches
bench update --patch

# Rebuild JavaScript/CSS assets
# What it does: Runs yarn/webpack build for all apps
# When to use: After code changes or when UI appears broken after update
bench build

# Build for production (minified, slower to build but faster to serve)
bench build --production

# Switch all apps to a different branch
# What it does: git checkout on each app
# WARNING: This changes code but does not run migrations — do that separately
bench switch-to-branch version-15 frappe erpnext hrms

# Check current versions of all installed apps
bench version

Prefer managed updates over 'bench update' at 2am? Managely handles the upgrade and the deploy for you. Start free, no credit card.

Start Free

Production and Service Management Commands

bash 
# Initial production setup (run as root/sudo after installation)
# What it does: Creates Supervisor config, Nginx config, sets up systemd services
sudo bench setup production frappe

# Regenerate Nginx configuration (run as root after adding new sites)
sudo bench setup nginx
sudo nginx -t        # Test config before reloading
sudo systemctl reload nginx

# Regenerate Supervisor configuration
sudo bench setup supervisor
sudo supervisorctl reload

# Restart all bench services (workers, scheduler)
bench restart

# Alternative: restart via Supervisor directly (as root)
sudo supervisorctl restart all
sudo supervisorctl status    # Check status of all services

# Stop/start individual services
sudo supervisorctl stop frappe-schedule:frappe-schedule
sudo supervisorctl start frappe-schedule:frappe-schedule
'bench restart' or 'sudo supervisorctl restart all'?

bench restart, run as the frappe user, restarts the Frappe and ERPNext workers and the scheduler. sudo supervisorctl restart all, run as root, restarts everything Supervisor controls. Use bench restart first. Fall back to supervisorctl when bench restart has no effect.

User Management Commands

bash 
# Reset the Administrator password
# When to use: When you are locked out of the system
bench --site mycompany.com set-admin-password NEW_PASSWORD

# Add a new System Manager user from command line
bench --site mycompany.com add-system-manager [email protected] \
  --first-name Ahmed \
  --last-name Hassan

# Disable a user (prevents login, does not delete data)
bench --site mycompany.com disable-user [email protected]

# Enable a user
bench --site mycompany.com enable-user [email protected]

Scheduler and Background Job Commands

ERPNext runs background jobs: sending email, creating recurring invoices, running scheduled backups. If the scheduler is off, all of that silently stops. These commands tell you whether it is running.

bash 
# Check scheduler status
bench --site mycompany.com scheduler status

# Enable the scheduler (needed after install or if manually disabled)
bench --site mycompany.com enable-scheduler

# Disable the scheduler (useful during maintenance to stop background jobs)
bench --site mycompany.com disable-scheduler

# Run a specific scheduled job manually (for testing)
bench --site mycompany.com run-patch erpnext.patches.v15_0.some_patch_name

# View pending jobs
bench --site mycompany.com show-pending-jobs

Debugging and Logging Commands

bash 
# Watch error log in real time
tail -f ~/frappe-bench/logs/frappe.log

# Watch background worker errors
tail -f ~/frappe-bench/logs/worker.error.log

# Watch web server log
tail -f ~/frappe-bench/logs/web.error.log

# Start development server (with auto-reload on code changes)
# WARNING: Do NOT use this in production
bench start

# Run tests for a specific module
bench --site mycompany.com run-tests --module erpnext.accounts

Quick Reference Card (Print This)

The commands you will actually reach for every week:

bash 
# 1. Take a backup
bench --site mycompany.com backup --with-files

# 2. Apply updates (minor patches)
bench update --pull

# 3. Restart all services after update
bench restart

# 4. Check if everything is working
bench --site mycompany.com doctor

# 5. Clear cache when something is not reflecting
bench --site mycompany.com clear-cache

# 6. Reset admin password
bench --site mycompany.com set-admin-password NEWPASS

# 7. Enable maintenance mode for updates
bench --site mycompany.com set-maintenance-mode on

# 8. Check service status
sudo supervisorctl status

# 9. Check current version
bench version

# 10. Watch errors in real time
tail -f ~/frappe-bench/logs/frappe.log

Bench is a skill. It should not be your full-time job.

Marketplace apps, one dataset, your plan.

Start free Deploy your app from Git

Leave a comment

Comments