Comprehensive Developer's Guide to Using the Bench CLI in Empress

Developers
1

Introduction

Welcome to this comprehensive guide on the Command Line Interface (CLI) tool in the Bench project, an integral part of the Empress software development environment. This guide is designed to delve into the technical depth of this feature, providing a clear, sophisticated explanation of its functionality, mirroring Apple’s style of presentation.

In Empress, the Bench CLI plays a critical role in managing and customizing business solutions. This guide underscores the importance of this feature and demonstrates how developers can effectively integrate and utilize it in software development and customization.

Bench CLI – An Overview

The Bench CLI is a command-line tool for managing the Empress framework – a full-stack web application framework written in Python & JavaScript with MariaDB as the database. It allows developers to manage Empress apps, sites, and the Empress environment itself, including setup, backup, and configuration tasks.

The commands for this tool are defined under the ‘frappe/bench’ directory. You can check all available flags and options for commands individually by executing them with the --help flag.

Here’s an example of how you can check the usage and options for the init command:

➜ bench init --help
Usage: bench init [OPTIONS] PATH

  Initialize a new bench instance in the specified path

Options:
  --python TEXT                   Path to Python Executable.
  --ignore-exist                  Ignore if Bench instance exists.
  --apps_path TEXT                path to json files with apps to install
                                  after init

Exploring the Bench CLI Commands

The Bench CLI commands are organized into four main groups:

  1. General Commands
  2. Setup Commands
  3. Config Commands
  4. Install Commands

Each of these command groups has its unique functionalities.

General Commands

The General Commands are a set of commands that don’t classify broadly in the other commands. Commands such as init, get-app, find come under this category. These commands can be invoked directly prefixing each with bench in your shell.

Here’s an example of how you can use these commands:

➜ bench COMMAND [ARGS]...

Frequently Used General Commands

Some frequently used commands in this category include:

  • init: Initialize a new bench instance in the specified path.
  • restart: Restart web, supervisor, systemd processes units.
  • update: Update the bench directory.
  • migrate-env: Migrate Virtual Environment to desired Python version.
  • retry-upgrade: Retry a failed upgrade.
  • backup: Backup single site data.
  • get-app: Download an app from the internet or filesystem and set it up in your bench.

Advanced Setup-based General Commands

Some advanced setup-based commands in this category include:

  • set-nginx-port: Set NGINX port for site.
  • set-ssl-certificate: Set SSL certificate path for site.
  • set-redis-cache-host: Set Redis cache host for bench.
  • use: Set default site for bench.
  • download-translations: Download latest translations.

Development General Commands

Some development-centric commands in this category include:

  • start: Start Empress development processes.
  • find: Finds benches recursively from location or specified path.
  • new-app: Create a new Empress application under apps folder.

Setup Commands

The Setup Commands consist of commands used to manipulate the requirements and the environment required by your Empress environment. These commands need to be executed using bench setup as the prefix.

Here’s an example of how you can use these commands:

➜ bench setup COMMAND [ARGS]...

Config Commands

The Config Commands deal with making changes in the current bench (not the CLI tool) configuration. These commands are used for manipulating configurations in the current bench context and need to be executed using bench config as the prefix.

Here’s an example of how you can use these commands:

➜ bench config COMMAND [ARGS]...

Install Commands

The Install Commands deal with commands used to install system dependencies for setting up a Empress environment. These commands need to be executed using bench install as the prefix.

Here’s an example of how you can use these commands:

➜ bench install COMMAND [ARGS]...

General Usage of the Bench CLI

The following examples demonstrate the general usage of the Bench CLI:

➜ bench init frappe-bench && cd frappe-bench
➜ bench new-site site1.local
➜ bench get-app erpnext https://github.com/frappe/erpnext
➜ bench --site site1.local install-app erpnext
➜ bench start
➜ bench update

Conclusion

The Bench CLI is an essential tool for developers working with the Empress system. It allows you to perform a wide range of tasks such as initializing new bench instances, managing apps and sites, and configuring your environment. By mastering the usage of this tool, you can significantly enhance your ability to create and manage custom business solutions.