bench-commands

What this skill does

# Bench CLI Commands Reference

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

## 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 Directory Structure

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

## Site Management

### Create Site
```bash
# 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
```

### Use Site
```bash
# 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
```

### Site Operations
```bash
# 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
```

### Backup & Restore
```bash
# 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
```

## App Management

### Get Apps
```bash
# 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
```

### Install/Uninstall Apps
```bash
# 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
```

### Create New App
```bash
# 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
```

### Update Apps
```bash
# 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
```

### Remove App
```bash
# 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
```

## Development Commands

### Start Development Server
```bash
# 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
```

### Build Assets
```bash
# 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
```

### Migrate
```bash
# 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
```

### Clear Cache
```bash
# 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
```

### Console
```bash
# 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"]'
```

### MariaDB Console
```bash
# Open MariaDB console
bench --site mysite.local mariadb

# Run SQL query
bench --site mysite.local mariadb -e "SELECT * FROM tabCustomer LIMIT 5"
```

### Run Tests
```bash
# 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
```

### Translation
```bash
# 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
```

## Production Setup

### Setup Production
```bash
# 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
```

### SSL/Let's Encrypt
```bash
# Setup Let's Encrypt SSL
sudo bench setup lets-encrypt mysite.local

# Renew certificates
sudo bench renew-lets-encrypt
```

### Restart Services
```bash
# 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
```

## Scheduler & Workers

### Scheduler
```bash
# 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
```

### Background Jobs
```bash
# 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
```

##