Bench Execute Command

The bench execute command allows you to run Python functions directly from the command line. It automatically initializes the Frappe framework and establishes a database connection for the specified site, making it useful for debugging, running custom scripts, performing maintenance tasks, and executing one-time operations.

Tip:

You don’t need to write any setup code for database access. The command automatically loads the Frappe environment before executing your function.

Basic Usage

Use the following syntax to execute a Python function on a specific site:

bench --site [site-name] execute [path.to.method]

Run Simple Functions

Execute any Python function available within your Frappe application.

Clear Cache

bench --site frappe.test execute frappe.clear_cache

This clears the cache for the specified site.

Get Site Information

bench --site frappe.test execute frappe.utils.get_site_info

The function executes and prints the returned site information.

Passing Positional Arguments

You can pass arguments immediately after the function name.

Get a Document

bench --site frappe.test execute frappe.get_doc User Administrator

Equivalent Python code:

frappe.get_doc("User", "Administrator")

Get a Field Value

bench --site frappe.test execute frappe.db.get_value DocType User name

Equivalent Python code:

frappe.db.get_value("DocType", "User", "name")

Automatic JSON Parsing

Arguments are automatically converted whenever possible. Numbers become integers, boolean values become Python booleans, while regular text remains a string.

bench --site frappe.test execute frappe.db.exists User Administrator

bench --site frappe.test execute some_function 123 true false

Example:

The value 123 becomes an integer, while true and false become Python True and False.

Using Named Arguments (kwargs)

Prefix an argument with -- to pass it as a keyword argument.

bench --site frappe.test execute frappe.db.get_value --doctype User --filters '{"name":"Administrator"}' --fieldname email

Equivalent Python code:

frappe.db.get_value(
    doctype="User",
    filters={"name":"Administrator"},
    fieldname="email"
)

Boolean Flags

Named arguments without values automatically become True.

bench --site frappe.test execute frappe.get_list User --ignore_permissions

Equivalent Python code:

frappe.get_list("User", ignore_permissions=True)

Mix Positional and Named Arguments

You can combine both argument styles in the same command.

bench --site frappe.test execute frappe.get_list User --limit 5

Equivalent Python code:

frappe.get_list("User", limit=5)

Execute Python Expressions

Instead of calling a function directly, you can execute complete Python expressions.

Count Records

bench --site frappe.test execute "frappe.db.count('User')"

Call Methods on Objects

bench --site frappe.test execute "frappe.get_doc('User','Administrator').reload()"

Common Examples

# Clear cache for a specific DocType
bench --site frappe.test execute frappe.clear_cache --doctype "Sales Order"

# Get a document
bench --site frappe.test execute frappe.get_doc User Administrator

# Count records
bench --site frappe.test execute frappe.db.count User

# Run a whitelisted method
bench --site frappe.test execute myapp.api.my_function --param1 value1 --param2 value2

# Check if a record exists
bench --site frappe.test execute frappe.db.exists User guest

# Read a configuration value
bench --site frappe.test execute frappe.conf.get developer_mode

# Execute a DocType method
bench --site frappe.test execute "frappe.get_doc('User','Administrator').get_fullname()"

# Chain multiple operations
bench --site frappe.test execute "frappe.get_doc('User','Administrator').add_roles('System Manager')"

Performance Profiling

Use the --profile flag to display execution time and performance statistics.

bench --site frappe.test execute frappe.db.get_list --profile --doctype "Sales Order" --limit 1000

Run on Multiple Sites

You can execute the same function across multiple sites.

All Sites

bench --site all execute frappe.clear_cache

Selected Sites

bench --site site1.local --site site2.local execute frappe.clear_cache

Command Behavior

Database Transactions: Changes are automatically committed when the command succeeds and rolled back if an error occurs.
Return Values: Function outputs are printed as JSON. If the function returns None, nothing is displayed.
Error Handling: Any exception stops execution, returns a non-zero exit code, and prints the complete traceback.
Security: The command can execute any accessible Python function, not only whitelisted methods. Use it carefully, especially on production systems.

Warning:

Since bench execute can run arbitrary Python code, avoid executing untrusted commands on production servers.

Legacy –args and –kwargs Options

Earlier versions of Bench supported passing arguments using --args and --kwargs. These options are still available but are no longer recommended. Use direct positional and named arguments whenever possible.

Note:

The values passed to --args and --kwargs use Python syntax and are evaluated using eval(), not JSON parsing.

Pass a List of Arguments

bench --site frappe.test execute frappe.db.get_value --args "['User', 'Administrator', 'email']"

Pass Keyword Arguments

bench --site frappe.test execute frappe.db.set_value --kwargs "{'doctype':'User','name':'Administrator','fieldname':'enabled','value':1}"

Combine –args and –kwargs

bench --site frappe.test execute frappe.db.get_value --args "['User','Administrator']" --kwargs "{'fieldname':'email'}"

Rating: 0 / 5 (0 votes)