Technical Tutorials 2026-04-05 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 — just like git has commit, push, pull, and merge, bench has update, migrate, restore, and deploy. Unlike documentation that just lists commands, this guide explains WHAT each command actually does, WHEN you should use it, and WHAT can go wrong — so you understand the tool instead of just copying commands you do not understand.

Before Anything: How Bench Works (Read This Once)

Bench is a Python tool. When you run 'bench update', it is not magic — it runs git pull in each app folder, checks if Python requirements changed, runs database migration scripts, and rebuilds JavaScript assets. Understanding this means when something fails, you know which step failed and why. All bench commands must be run from inside the frappe-bench directory (~/frappe-bench) as the frappe user. If you run them as root or from the wrong directory, they will fail or cause 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 and configuration — one company. These commands manage the lifecycle of sites.

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 of 'apps' — Frappe (the framework), ERPNext (the main app), HRMS (HR module), and any custom apps. These commands manage which apps are installed.

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

Difference Between get-app, install-app, and remove-app

get-app downloads code to the server. install-app activates it for a specific site (creates database tables). uninstall-app deactivates it from a site (deletes its data from that site). remove-app removes the code entirely from the server. You can have an app downloaded (get-app done) but not 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 interact with the database. Use them carefully — mistakes can corrupt your data.

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

When you run 'bench mariadb', you get direct SQL access. A wrong UPDATE or DELETE command bypasses all ERPNext validations and can corrupt your accounting data permanently. Always test SQL on a copy of the database, never directly on production. Always start with SELECT before UPDATE or DELETE.

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

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

When to Use 'bench restart' vs 'sudo supervisorctl restart all'

bench restart (as frappe user) only restarts the Frappe/ERPNext workers and scheduler. sudo supervisorctl restart all (as root) restarts everything Supervisor controls. Use bench restart for most cases. Use supervisorctl when bench restart is not working.

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 user@company.com \
  --first-name Ahmed \
  --last-name Hassan

# Disable a user (prevents login, does not delete data)
bench --site mycompany.com disable-user user@company.com

# Enable a user
bench --site mycompany.com enable-user user@company.com

Scheduler and Background Job Commands

ERPNext runs background tasks for things like sending emails, auto-creating recurring invoices, and running scheduled backups. These are the 'scheduler' commands.

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 10 commands you will actually use 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

Comments

Want to run ERPNext without ever opening a terminal? Deploy on Managely Cloud — everything is managed from a web dashboard.

Start Free User Guide

Before Anything: How Bench Works (Read This Once)

Site Management Commands

App Management Commands

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

Database and Migration Commands

Update and Build Commands

Production and Service Management Commands

User Management Commands

Scheduler and Background Job Commands

Debugging and Logging Commands

Quick Reference Card (Print This)

Leave a comment

Comments