Bench CLI Commands Reference

Bench CLI命令参考手册

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

这是用于管理Frappe/ERPNext安装的Frappe Bench命令行界面完整参考手册。

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命令
管理Frappe站点
安装和更新应用
执行迁移和构建
搭建生产环境
排查常见问题

Bench Directory Structure

Bench目录结构

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

frappe-bench/
├── apps/                   # Frappe应用
│   ├── frappe/            # 核心框架
│   ├── erpnext/           # ERPNext（若已安装）
│   └── my_app/            # 自定义应用
├── sites/                  # 站点目录
│   ├── common_site_config.json
│   ├── apps.txt           # 已安装应用列表
│   └── my_site.local/     # 独立站点
│       ├── site_config.json
│       ├── private/
│       └── public/
├── config/                 # 配置文件
├── logs/                   # 日志文件
├── env/                    # Python虚拟环境
└── node_modules/          # Node.js依赖

Site Management

站点管理

Create Site

创建站点

bash

undefined

bash

undefined

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

undefined

bench new-site mysite.local --no-mariadb-socket

undefined

Use Site

使用站点

bash

undefined

bash

undefined

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

undefined

bench --site all migrate

undefined

Site Operations

站点操作

bash

undefined

bash

undefined

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

undefined

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

undefined

Backup & Restore

备份与恢复

bash

undefined

bash

undefined

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

undefined

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

undefined

App Management

应用管理

Get Apps

获取应用

bash

undefined

bash

undefined

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

undefined

bench get-app erpnext --install-all

undefined

Install/Uninstall Apps

安装/卸载应用

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local uninstall-app my_app --yes --force

undefined

Create New App

创建新应用

bash

undefined

bash

undefined

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

undefined

undefined

Update Apps

更新应用

bash

undefined

bash

undefined

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

undefined

bench update --reset

undefined

Remove App

移除应用

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local uninstall-app my_app bench remove-app my_app

undefined

Development Commands

开发命令

Start Development Server

启动开发服务器

bash

undefined

bash

undefined

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

undefined

bench serve --port 8001

undefined

Build Assets

构建资源

bash

undefined

bash

undefined

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

undefined

bench watch

undefined

Migrate

迁移

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local migrate --skip-failing

undefined

Clear Cache

清除缓存

bash

undefined

bash

undefined

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

undefined

bench clear-redis-cache

undefined

Console

控制台

bash

undefined

bash

undefined

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"]'

undefined

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

undefined

MariaDB Console

MariaDB控制台

bash

undefined

bash

undefined

Open MariaDB console

bench --site mysite.local mariadb

Run SQL query

bench --site mysite.local mariadb -e "SELECT * FROM tabCustomer LIMIT 5"

undefined

bench --site mysite.local mariadb -e "SELECT * FROM tabCustomer LIMIT 5"

undefined

Run Tests

运行测试

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local run-tests --skip-setup

undefined

Translation

翻译

bash

undefined

bash

undefined

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

undefined

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

undefined

Production Setup

生产环境搭建

Setup Production

配置生产环境

bash

undefined

bash

undefined

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

undefined

bench setup fail2ban

undefined

SSL/Let's Encrypt

bash

undefined

bash

undefined

Setup Let's Encrypt SSL

sudo bench setup lets-encrypt mysite.local

Renew certificates

sudo bench renew-lets-encrypt

undefined

sudo bench renew-lets-encrypt

undefined

Restart Services

重启服务

bash

undefined

bash

undefined

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

undefined

sudo supervisorctl status

undefined

Scheduler & Workers

调度器与工作进程

Scheduler

调度器

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local execute frappe.tasks.run_daily

undefined

Background Jobs

后台任务

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local purge-jobs

undefined

Configuration

配置

Site Config

站点配置

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local remove-config key

undefined

Common Configurations

常见配置

python

undefined

python

undefined

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 } }

undefined

{ "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 } }

undefined

Bench Config

Bench配置

bash

undefined

bash

undefined

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

undefined

bench config set developer_mode 1 bench config set webserver_port 8000 bench config set background_workers 1

undefined

Troubleshooting Commands

故障排查命令

Logs

日志

bash

undefined

bash

undefined

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

undefined

tail -f sites/mysite.local/logs/frappe.log

undefined

Debug

调试

bash

undefined

bash

undefined

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

undefined

bench --site mysite.local add-system-manager user@example.com

undefined

Fix Common Issues

修复常见问题

bash

undefined

bash

undefined

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

undefined

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

undefined

Version Management

版本管理

bash

undefined

bash

undefined

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

undefined

bench set-bench-version 5.x

undefined

Multi-Tenancy

多租户

bash

undefined

bash

undefined

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

undefined

sudo certbot certonly --webroot -w /var/www/letsencrypt -d *.mydomain.com

undefined

Common Workflows

常见工作流

Fresh Install

全新安装

bash

undefined

bash

undefined

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

undefined

bench start

undefined

Daily Development

日常开发

bash

undefined

bash

undefined

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

undefined

bench build --app my_app

undefined

Deploy Update

部署更新

bash

undefined

bash

undefined

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

undefined

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

undefined

bench-commands

Original

Translation

Bench CLI Commands Reference

Bench CLI命令参考手册

When to Use This Skill

何时使用本工具

Bench Directory Structure

Bench目录结构

Site Management

站点管理

Create Site

创建站点

Create new site

Create new site

With specific database

With specific database

With MariaDB root password

With MariaDB root password

With admin password

With admin password

From SQL file

From SQL file

Skip creating default user

Skip creating default user

Use Site

使用站点

Set default site

Set default site

Run command on specific site

Run command on specific site

Run on all sites

Run on all sites

Site Operations

站点操作

List all sites

List all sites

Drop site (delete)

Drop site (delete)

Drop with force

Drop with force

Set site maintenance mode

Set site maintenance mode

Disable scheduler

Disable scheduler

Backup & Restore

备份与恢复

Backup site

Backup site

Backup with files

Backup with files

Backup all sites

Backup all sites

Restore from backup

Restore from backup

Restore with files

Restore with files

App Management

应用管理

Get Apps

获取应用

Get app from GitHub

Get app from GitHub

Get specific branch

Get specific branch

Get specific tag

Get specific tag

Get from local path

Get from local path

Get and install on all sites

Get and install on all sites

Install/Uninstall Apps

安装/卸载应用

Install app on site

Install app on site

Install app on all sites

Install app on all sites

Uninstall app

Uninstall app

Uninstall with force (removes data)