Frappe Commands
The Bench CLI utilizes the module
frappe.utils.bench_manager
to get the framework's as well as any other Application's commands present on the current bench directory.
This page is concerned only with the commands that exist in the Frappe project, that are a direct part of the CLI tool. These commands are defined under the frappe/frappe .
For references of any Bench commands, checkout Bench Commands .
There are four major command types in Frappe inherited by Bench during command executions. They can be broadly grouped into
Site Commands
Set of commands used for site-specific operations. These are the most frequented commands to alter the state of your sites. These commands are accessed by using the
--site
option along with the site name (or "all") if you wish to run the operation
(if possible)
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. By default, all sites created on your bench will have only the Frappe Framework installed on them.
bench new-site {site}
For more information and examples, see the bench new-site reference.
Site Backups
You can use the Bench CLI to take backups on the sites of your bench. You can manage the site's database and files backups and have more control over the operation.
bench --site {site} backup
The Bench CLI also deletes the older backup files from your bench directory. By default, it deletes backups older than 24 hours from the backups directory.
For more information and examples, see the bench backup reference.
Site Restores
Bench CLI can be used to restore an existing site to a previous state. Using the
bench restore
command, a site may be restored with the specific database and file restores.
bench --site {site} restore {path/to/database/file}
The least requirement for performing a restore operation is having the database file on your local filesystem. The specified backup file may have the
sql.gz
of
sql
extension.
For more information and examples, see the bench restore reference.
Partial Site Restores and Backups
Since Version 13, Frappe has support for taking partial backups and restoring them. Partial backups can be taken using the
bench backup
command directly. As for partial restores, the
bench partial-restore
command may be used to restore the partial backups to an existing site.
For more information and examples, see the bench partial-restore and bench backup reference.
Site App Management
You can install or uninstall Frappe Applications available on your Bench. To add Apps to your bench using
bench get-app
checkout
the docs
.
App Installation
The easiest way to install a Frappe Application on your site is through the Bench CLI. However, the application must be installed on your bench prior to that.
bench --site {site} install-app {app}
In this operation, Application
meta
,
modules
and
doctypes
of the specified site are installed on the specified site.
App Uninstallation
Uninstall an app installed on site. This is a destructive action and consists of removing all app-related data from the site. Hence, a backup is taken before uninstalling said app.
bench --site {site} uninstall-app {app}
Note: From Version 13, even apps not installed on the Bench can be uninstalled from the site.
For more information and examples, see the bench uninstall-app reference.
Site Migrations
Run patches, sync schema and rebuild files, translations and indexes on a particular site. Find out how site migrations work in the docs .
bench --site {site} migrate
For more information and examples, see the bench migrate reference.
Site Deletion
Drops the database and moves the site directory from
./sites
to the
./archived_sites
(unless specified otherwise)
folder on your Bench.
bench drop-site {site}
For more information and examples, see the bench drop-site reference.
Reset Site Data
Re-install all installed Applications from your specified site. This completely resets the site.
bench reinstall {site}
For more information and examples, see the bench reinstall reference.
List Installed Apps
List all the Frappe Applications installed on the specified site. The information shown by the command is fetched from the
Installed Applications
DocType which tracks the latest version of the apps, the site was migrated to. The global default
installed_apps
is used as fallback.
bench --site {site} list-apps
Multi-site support has been added in Version 13. To see the summary for all sites, run the command with site's value as
all
.
For more information and examples, see the bench list-apps reference.
Setting the default site
Sometimes typing
--site [sitename]
for every site command can be tedious. You can set the default site for the terminal session by setting the
FRAPPE_SITE
environment variable.
~/frappe-bench
❯ export FRAPPE_SITE=mysite.localhost
~/frappe-bench
❯ echo $FRAPPE_SITE
mysite.localhost
~/frappe-bench
❯ bench console
Apps in this namespace:
frappe
In [1]: frappe.local.site
Out[1]: 'mysite.localhost'
Access site in the browser
To access a site in the browser, you have to remember the webserver port on which bench is running and then type out the full URL. There is a bench command that does this for you.
Running the following command will open the site url directly in your default browser.
# open site.local in the browser
$ bench --site site.local browse
# this also works
$ bench browse site.local
You can also login as a user by passing
--user
option.
$ bench --site site.local browse --user test@example.com
$ bench --site site.local browse --user Administrator
Login URL: http://site.local:8000/app?sid=<generated-sid>
Note that this command:
Allows login as any user only when developer_mode is set to 1
Allows login as Administrator regardless of developer_mode
Prints the login URL only when user is Administrator
Site Operations, Debugging and Development
Here are some operations you can perform on your site via the Bench CLI to update your site state. You may never have to use some of these, but they exist just in case.
-
add-system-manager : Add a new system manager to a site.
-
add-user : Add a new User with specific roles to a site.
-
add-to-hosts : Add the specified site to the hosts file on your system.
-
build-search-index : Builds search index for Websites. Refer to Full Text Search API Docs for more information.
-
disable-user : Disable user on site.
-
publish-realtime : Publish realtime event from bench.
-
reload-doc : Reload schema for a particular Doctype and refresh the specified Document
-
reload-doctype : Reload schema for a particular DocType
-
remove-from-installed-apps : Removes the mentioned app from the site gloabl value of
installed_applications
. -
run-patch : Run a particular patch via the Frappe Patch Handler.
-
migrate-to : Command to migrate your local site to a Frappe Hosting Provider's service.
-
ngrok : Create a temporary URL and share it with anyone, and they can access your local site in their browser. Primarily built for aiding with the development of third party services.
-
set-password : Set the password for any user.
-
set-admin-password : Set the password for the Administrator user.
-
set-last-active-for-user : Set users last active date to current datetime.
-
start-recording : Starts the Frappe Recorder for the specified sites.
-
stop-recording : Terminates the Frappe Recorder for the specified sites.
-
use : Sets the default site on the bench.
Database Maintenance Commands
Set of commands that are related to database management and maintenance. These commands offer more control to your site's database. You may want to fine-tune your deployment to fit your site's needs over time.
Table Transformations
The
transform-database
command allows you to manage the settings of your site's tables. At this point, you can switch
engine
and
row_format
settings for select tables on your site database.
bench --site {site} transform-database --tables {tables}
For more information and examples, see the bench transform-database reference.
Table Trimming
Docfields removed from a particular DocType may not be deleted from their Database tables. This is by design to prevent premature data loss in Frappe. This won't be problematic for the most part, however, at some point you may face issues due to this lingering data.
Some benefits of regular table trimming are:
-
Smaller backup sizes
-
Reduced time taken to backup sites
-
Reduced Site Database Usages
-
Optimized queries in case of
SELECT *
-
Database is clean and doesn't have anything hidden or redundant data
bench trim-tables [OPTIONS]
For more information and examples, see the bench trim-tables reference.
Database Trimming
Deleting DocTypes from the list view may not delete their corresponding tables from the database. Migrations may leave ghost tables in your Site Database at times. This may be done for the sake of redundancy, for recovery in case your data is corrupted or lost, or simply, in cases of human error.
bench trim-database [OPTIONS]
For more information and examples, see the bench trim-database reference.
Scheduler Commands
Commands to manage and review the scheduler and background jobs' statuses for the sites on your bench. Defined under module
frappe.commands.schedule
.
-
disable-scheduler : Disable scheduler for specified sites.
-
doctor : Get diagnostic info about the status of the scheduler for all sites (if unspecified) and active workers on bench.
-
enable-scheduler : Enables scheduler for specified sites.
-
purge-jobs : Purge any pending periodic tasks, if the event option is not given, it will purge everything for the site.
-
ready-for-migration : Checks if a particular site is ready for migration by checking the existence of any pending background jobs.
-
scheduler : Change the state of the scheduler for any site from pause , resume , disable or enable state.
-
set-maintenance-mode : Set the value for maintenance mode in the config for specified sites.
-
show-pending-jobs : Get diagnostic info about background jobs.
-
schedule : Start the scheduler process for your bench. This process manages scheduler events defined in the
hooks.py
file. You can find this command mentioned in the bench config for your process manager too. -
worker : Start worker process on your bench. The process this starts will manage all background jobs started on this bench.
-
trigger-scheduler-event : Trigger a specific scheduler event for the specified sites.
Frappe Utility Commands
Frappe Utility commands that can be both, site or bench specific. These commands are defined under the module
frappe.commands.utils
.
Displaying Site Config
The applied configuration for your sites gets applied as a combination of the bench directory's
common_site_config.json
and the site's own
site_config.json
. You can read more about this,
here
. Bench provides an interface to view the applied
frappe.conf
values for your sites. You may choose to access this information in tabular or JSON formats.
bench --site {site} show-config
For more information and examples, see the bench show-config reference.
Updating Site Config
Bench provides a wrapper command to insert or update values in the site config files. You can update values in your site's
site_config.json
, along with the bench directory's
common_site_config.json
through the same command.
bench --site {site} set-config KEY VALUE
For more information and examples, see the bench set-config reference.
Display Version Of Installed Apps
The
version
command displays all installed apps and their versions.
bench version [OPTIONS]
With version 13, the
-f
/
--format
option was introduced. This option allows you to display additional information about the branch and last commit. For more information and examples, see the
bench version
reference.
More Commands
-
add-to-email-queue : Add an email to the Email Queue.
-
build : Builds assets for the Frappe Applications installed on bench.
-
bulk-rename : Rename multiple records via a CSV file. Example File Format (Without Header) :
Old Name
New Name
Merge
HR-EMP-00001
EMP0001
FALSE
HR-EMP-00002
EMP0002
FALSE
HR-EMP-00003
EMP0003
FALSE
HR-EMP-00004
EMP0004
FALSE
HR-EMP-00005
EMP0005
FALSE
HR-EMP-00006
EMP0006
FALSE
-
clear-cache : Clear cache, doctype cache and defaults.
-
clear-website-cache : Clear Website cache.
-
console : Starts an IPython console for the site. Use with the
--autoreload
flag to reload changes to code automatically. -
data-import : Import documents in bulk from CSV or XLSX using data import.
-
destroy-all-sessions : Clear sessions of all users (logs them out).
-
execute : Execute a particular function or method with a given set of
args
andkwargs
. -
export-csv : Export data import template with data for DocType.
-
export-doc : Export a single document to CSV.
-
export-fixtures : Export records from a site to your Frappe Application, as JSON files. Fixtures are defined in your app's
hooks.py
file. -
export-json : Export doclist as json to the given path, use '-' as name for Singles.
-
import-csv : Import from your CSV file using data import.
-
import-doc : Import (insert/update) doclist. If the argument is a directory, all files ending with
.json
are imported -
jupyter : Starting a Jupyter Notebook server.
-
make-app : Creates a boilerplate Frappe Application.
-
db-console : Start the interactive DB console for your site. This command is an alias over commands: mariadb, postgres
-
mariadb : Start the MySQL interactive console for the mysql site.
-
postgres : Start the PostgreSQL interactive console for the postgres site.
-
rebuild-global-search : Setup help table in the current site (called after migrate).
-
request : Make a request as Administrator with Arguements to a Path.
-
reset-perms : Reset permissions for all DocTypes to their default settings.
-
run-tests : Run Python tests on the specified site.
-
run-parallel-tests : Run Python tests parallelly on CI.
-
run-ui-tests : Run Cypress UI tests.
-
serve : Start the webserver for the bench.
-
watch : Watch and concatenate JS and CSS files as and when they change.
Translation Commands
There are two ways to manage translations. Until v15, translations are commonly based on CSV files. Starting from v16, frappe manages translations using the .po file format from GNU Gettext. Custom apps can either continue to provide CSV based translations or switch to the new format.
CSV Files
Set of commands to manage CSV based translation files. These commands are defined under the module
frappe.commands.translate
.
-
build-message-files : Build message files for translation.
-
get-untranslated : Get untranslated strings for language.
-
migrate-translations : Migrate target-app-specific translations from source-app to target-app
-
new-language : Create a `[lang].csv` file for the given application.
-
update-translations : Update translations for set language between files.
Gettext / PO files
Set of commands to manage Gettext based translation files. These commands are defined under the module
frappe.commands.gettext
.
-
generate-pot-file : Generate a POT file. This is creates the base file that contains all the translatable strings of your app and serves a a template for translation files for specific languages.
-
compile-po-to-mo : Compile PO files to MO files. PO files are human-readable. In production, translations are read from MO files, where the translations are complied to an optimized binary format. This command creates MO files from your PO files (this command also triggered by bench build , for convenience).
-
migrate-csv-to-po : Migrate your app's translations from CSV files (old) to PO files (new). Please run generate-pot-file first.
-
update-po-files : Sync the language's PO files with POT file. This way, new translatable strings are added to your PO file, where they can be translated, while outdated ones can removed. You might want to run generate-pot-file first.
-
create-po-file : Create a new (untranslated) PO file for a new language.