Developer's Guide to Utilizing the Bench CLI in Empress Framework

Developers
1

Introduction

The Bench CLI is a central feature in the Empress Framework that helps developers manage and control their applications efficiently. This guide will guide you through the utilization of the Bench CLI, focusing on the frappe.utils.bench_manager module that the CLI employs to access the framework’s commands and those of any other applications present in the current bench directory.

Major Command Types

In Empress, the Bench CLI inherits four major command types during executions, which are:

  1. Site Commands
  2. Database Maintenance Commands
  3. Scheduler Commands
  4. Empress Utility Commands
  5. Translation Commands

Site Commands

These are commands used for site-specific operations. They are accessed using the --site option with the site name, or “all” if you wish to run the operation for all sites on the bench. These commands are defined under the module frappe.commands.site.

Site Creation

Create a new Site on your bench with the command:

bench new-site {site}

Site Backups

Back up your sites using the Bench CLI:

bench --site {site} backup

Site Restores

Restore a site to a previous state:

bench --site {site} restore {path/to/database/file}

Partial Site Restores and Backups

From Version 13, Empress supports taking partial backups and restoring them:

bench backup --with-files
bench --site {site} partial-restore {path/to/database/file}

Site App Management

Install or uninstall Empress Applications available on your Bench:

bench --site {site} install-app {app}
bench --site {site} uninstall-app {app}

Site Migrations

Run patches, sync schema, and rebuild files, translations, and indexes on a particular site:

bench --site {site} migrate

Site Deletion

Drop a site from your bench:

bench drop-site {site}

Reset Site Data

Re-install all installed Applications from your specified site:

bench reinstall {site}

List Installed Apps

List all the Empress Applications installed on the specified site:

bench --site {site} list-apps

Database Maintenance Commands

These commands relate to database management and maintenance:

Table Transformations

Switch engine and row_format settings for select tables on your site database:

bench --site {site} transform-database --tables {tables}

Table Trimming

Trim unused data from the database:

bench trim-tables [OPTIONS]

Database Trimming

Clear ghost tables from your Site Database:

bench trim-database [OPTIONS]

Scheduler Commands

Manage and review the scheduler and background jobs’ statuses for the sites on your bench:

Change Scheduler State

Change the state of the scheduler for any site:

bench --site {site} scheduler enable
bench --site {site} scheduler disable

Empress Utility Commands

These commands can be both site or bench specific:

Displaying Site Config

View the applied frappe.conf values for your sites:

bench --site {site} show-config

Updating Site Config

Update values in your site’s site_config.json:

bench --site {site} set-config KEY VALUE

Display Version Of Installed Apps

Display all installed apps and their versions:

bench version [OPTIONS]

Translation Commands

Manage translations for your multi-lingual deployments:

Build Message Files

Build message files for translation:

bench build-message-files

Update Translations

Update translations for set language between files:

bench update-translations

This guide has provided a comprehensive guide on the Bench CLI in the Empress Framework, elaborating on its functionality from a developer’s perspective. The commands provided above are critical for managing and controlling applications in the Empress Framework, contributing significantly to the development and customization of business solutions. The Bench CLI is an essential tool in the Empress Framework that enables developers to manage their applications effectively and efficiently.