frappe-cli

  ███████╗██████╗  █████╗ ██████╗ ██████╗ ███████╗     ██████╗██╗     ██╗
  ██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔════╝    ██╔════╝██║     ██║
  █████╗  ██████╔╝███████║██████╔╝██████╔╝█████╗      ██║     ██║     ██║
  ██╔══╝  ██╔══██╗██╔══██║██╔═══╝ ██╔═══╝ ██╔══╝      ██║     ██║     ██║
  ██║     ██║  ██║██║  ██║██║     ██║     ███████╗    ╚██████╗███████╗██║
  ╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝     ╚══════╝     ╚═════╝╚══════╝╚═╝

                     Frappe CLI  ·  fp  ·  v1.0.4
           Install · Operate · Develop — all in one command

A production-ready CLI that installs and operates Frappe / ERPNext — from a bare VPS to a working HTTPS site in one command. Also your daily bench shortcut.

Built with Python + Click + Rich. Every step is independently runnable, self-healing, and idempotent — safe to re-run on partially-installed servers.

Two tools in one

┌─────────────────────────────────────────────────────────────────────┐
│                          fp  (frappe-cli)                           │
├──────────────────────────────┬──────────────────────────────────────┤
│   🏗  INSTALLER / OPS        │   ⚡  DAILY DEV WORKFLOW             │
│                              │                                      │
│  fp install wizard           │  fp use <site>     ← set context     │
│  fp step <name>              │  fp migrate        ← auto --site     │
│  fp ssl setup/list           │  fp console                          │
│  fp service status           │  fp restart                          │
│  fp backup setup             │  fp build / watch                    │
│  fp firewall setup           │  fp get-app <url>                    │
│                              │  fp sites / fp context               │
└──────────────────────────────┴──────────────────────────────────────┘

Highlights

• One-command bootstrap: fp install wizard provisions a fresh Ubuntu VPS end-to-end (MariaDB → Redis → Node → bench → site → ERPNext → nginx → supervisor → SSL).
• 17 individually runnable steps: fp step <name> lets you re-run, debug, or compose any wizard step on its own (same code path as the wizard).
• Context-aware dev workflow: fp use mysite.local remembers your active bench + site — then every bench command becomes one word.
• Multi-bench friendly: works on fresh and non-fresh VPS — auto-detects existing bench installs and directories.
• Self-healing: automatically repairs the supervisor symlink that vanilla bench setup production sometimes misses on multi-bench hosts.
• Hard verification: polls supervisorctl status for RUNNING and pings bench Redis for PONG before declaring success.
• Resumable: the wizard saves progress; if a step fails you can fix and fp install wizard --resume.
• Operator-friendly utilities: fp ssl list/setup, fp service status, fp backup setup, fp firewall setup, and more.

Installation

frappe-cli is published on PyPI: https://pypi.org/project/frappe-cli/.

After install, use fp as your command everywhere (short for Frappe Platform; the per-bench context file is .fp.yaml).

With uv (recommended)

# Install uv (if you don't have it yet)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install frappe-cli globally
uv tool install frappe-cli

# Verify
fp --version
fp --help

To upgrade later:

uv tool upgrade frappe-cli

With pip

pip install --user frappe-cli
export PATH="$HOME/.local/bin:$PATH"
fp --help

With pipx

pipx install frappe-cli
fp --help

Requirements

Note: frappe-cli will install Node.js, MariaDB, Redis, nginx, supervisor, wkhtmltopdf, certbot, and uv for you. You do not need to pre-install them.

Quick start: bootstrap a fresh VPS

The fastest path from a clean Ubuntu server to a working HTTPS Frappe site:

Fresh Ubuntu VPS
      │
      ▼
  apt install python3-pip curl
      │
      ▼
  uv tool install frappe-cli
      │
      ▼
  fp install wizard          ← interactive prompts, ~30-60 min
      │
      ├─ system-update
      ├─ system-deps
      ├─ nodejs
      ├─ mariadb-install + mariadb-secure
      ├─ redis
      ├─ wkhtmltopdf
      ├─ bench-install + bench-init
      ├─ site-create
      ├─ get-app + install-app
      ├─ production (nginx + supervisor)
      └─ ssl (Let's Encrypt)
            │
            ▼
  ✓ https://erp.example.com  ← live in one command

sudo apt update && sudo apt install -y python3-pip curl

# 1. Install frappe-cli
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install frappe-cli

# 2. Run the interactive wizard (≈30–60 min depending on the host)
fp install wizard

You'll be prompted for:

App branch auto-detection

The wizard detects the right branch automatically:

For private repos, use the SSH URL format before running the wizard:

# Make sure your SSH key is added to GitHub first
git@github.com:myorg/vsd_fleet_ms.git   ← use this style in the URL prompt

MariaDB root password

The wizard asks for this password twice. Unlike the site admin password (which can be reset with bench set-admin-password), the MariaDB root password is harder to recover if entered incorrectly. Confirm carefully.

If a step fails, fix the issue and resume from where it stopped:

fp install wizard --resume

When it's done:

curl -I https://erp.example.com   # HTTP/2 200, served by nginx, valid Let's Encrypt cert

⚡ Daily dev workflow

This is where fp really shines. Instead of typing bench --site <long.site.name> migrate every time, you set your context once and then use short commands.

  ~/my-bench/                    ← bench root
  ├── apps/
  │   ├── frappe/
  │   └── my_custom_app/         ← you are here, deep in code
  ├── sites/
  │   ├── dev.local/
  │   └── staging.example.com/
  └── .fp.yaml                   ← fp writes: site: dev.local

Step 1 — set your active site (once per session)

Works from any directory inside the bench — bench root, apps/, apps/my_app/, etc.

cd ~/my-bench
fp use dev.local
# ✓ Active site set to dev.local  (bench: my-bench)

Step 2 — run bench commands without the boilerplate

# Before fp:
bench --site dev.local migrate
bench --site dev.local console
bench --site dev.local clear-cache

# With fp:
fp migrate
fp console
fp clear-cache

Switching between sites

You never "lose" a site — just use a different one. The old site is still there.

fp sites
  ● dev.local          ← active (green dot)
    staging.example.com

fp use staging.example.com
# ✓ Active site set to staging.example.com

fp migrate            → bench --site staging.example.com migrate

One-command deploy

The most common prod/demo workflow — pull, migrate, then restart:

cd ~/my-bench/apps/my_custom_app
fp deploy
# → git pull
# → bench --site dev.local migrate
# → bench restart
# ✓ Deploy complete

Migrate runs before restart so schema and code changes apply cleanly. Skip git pull when you only need migrate + restart:

fp deploy --no-pull

Make fp restart passwordless

On production benches bench restart (and therefore fp restart / fp deploy) uses sudo supervisorctl — which prompts for a password.

Enable passwordless restart in two ways:

Option A — during fp install wizard (recommended for new servers):

The wizard asks you at setup time:

Allow passwordless 'fp restart' for this user? [Y/n]

Answer Y and the wizard writes a safe sudoers drop-in automatically.

Option B — at any time with fp sudo:

fp sudo status              # check current state
fp sudo enable-restart      # grant passwordless supervisorctl (asks sudo once)
fp sudo disable-restart     # revoke the rule

After enabling, fp deploy runs completely without password prompts:

→ git pull
→ migrate dev.local
→ restart bench
✓ Deploy complete

The sudoers rule is scoped to one user + one binary (/usr/bin/supervisorctl) — minimal privilege. The file is tagged so fp sudo disable-restart never removes a hand-crafted rule.

All dev commands

  fp use <site>         Write active site to .fp.yaml
  fp context            Show current bench + active site
  fp sites              List all sites (active site marked with ●)
  fp deploy             git pull → migrate → restart

  ── site-scoped (auto-injects --site) ─────────────────────────────
  fp migrate            Sync schema, run patches, rebuild assets
  fp console            IPython console for the active site
  fp install-app <app>  Install app on active site
  fp uninstall-app <a>  Remove app from active site
  fp list-apps          Apps installed on active site
  fp clear-cache        Clear framework cache
  fp mariadb            MariaDB shell for active site

  ── bench-scoped (no --site needed) ───────────────────────────────
  fp restart            Restart supervisor / systemd processes
  fp build              Build JS + CSS assets
  fp start              Start dev server (Procfile)
  fp watch              Watch + recompile JS/CSS on change
  fp get-app <url>      Download app from git URL

  ── sudoers management ────────────────────────────────────────────
  fp sudo status                Show passwordless restart state
  fp sudo enable-restart        Grant passwordless supervisorctl
  fp sudo disable-restart       Revoke the rule

How it works: fp detects the bench root by walking up from your current directory looking for both a sites/ and apps/ folder. The active site is stored in <bench_root>/.fp.yaml — a plain YAML file you can inspect or edit directly. The wizard's state (~/.frappe-cli-state.json) is completely separate and untouched.

Command structure

fp <group> <command> [options]

Every command supports --help and many support --dry-run and --debug.

Everyday recipes

Add SSL to an existing site

# See all sites and which are still on HTTP
fp ssl list

# Issue an HTTPS cert for one site (auto-detects the owning bench)
fp ssl setup --site-name erp.example.com

# First time ever using Let's Encrypt on this host? Provide an email
fp ssl setup --site-name new.example.com --email you@example.com

Re-run a single wizard step

Every step the wizard runs is also exposed as a standalone command. Same code, same self-healing, same verification.

# Show all steps in execution order
fp step list

# Run just SSL for one site
fp step ssl --bench-name my-bench --site-name erp.example.com

# Re-do the production setup (nginx + supervisor) for a bench
fp step production --bench-name my-bench

# Try a step without executing anything
fp step production --bench-name my-bench --dry-run

# Force a step even when check() says "already done"
fp step ssl --bench-name my-bench --site-name erp.example.com --force

The full step catalogue:

Add another site to an existing bench

fp step site-create     --bench-name my-bench --site-name shop.example.com
fp step dns-multitenant --bench-name my-bench
fp step app-install     --bench-name my-bench --site-name shop.example.com --app-url erpnext
fp step bench-restart   --bench-name my-bench
fp step ssl             --bench-name my-bench --site-name shop.example.com

Set up an automated backup

fp backup setup \
  --bench-name my-bench \
  --site-name erp.example.com \
  --admin-email you@example.com

Service health check

fp service status --bench-name my-bench --site-name erp.example.com
fp service restart

Firewall (UFW)

fp firewall setup        # opens 22, 80, 443 by default

Tips for non-fresh VPS

frappe-cli is designed to work on hosts that already have bench installed or already have other Frappe benches:

• fp step bench-install — checks if bench is on PATH (any of ~/.local/bin, /usr/local/bin, /usr/bin) and skips if found.
• fp step bench-init — skips if the target bench directory already has apps/frappe/.
• fp step production — explicitly creates the missing supervisor.conf symlink that vanilla bench setup production sometimes forgets on multi-bench hosts.
• fp step ssl — uses sudo test -f so it can correctly detect existing certs in the root-owned /etc/letsencrypt/live/ directory.

Why frappe-cli over raw bench?

Configuration file (optional)

For reproducible installs, pass a YAML config with --config:

# production.yaml
system:
  timezone: "Africa/Nairobi"
  locale: "en_US.UTF-8"
  user: "frappe"
frappe:
  branch: "version-15"
  bench_name: "my-bench"
  site_name: "erp.example.com"
  admin_password: "changeme"
  mariadb_root_password: "changeme"
services:
  enable_ssl: true
  enable_ufw: true
backup:
  admin_email: "you@example.com"
  retention_days: 7

See src/frappe_cli/data/example_config.yaml.

Logs and troubleshooting

• All commands log to /var/log/frappe-installer.log (with local fallback if not writable).
• Use --debug on any command for verbose subprocess output.
• Use --dry-run on step / install commands to preview what would run.
• For a known-working manual flow you can compare against, see docs/superpowers/test3-bench-setup.md — a step-by-step runbook used to verify every wizard step.

Development

git clone https://github.com/okama12/frappe-cli.git
cd frappe-cli

# Install dependencies
poetry install

# Run all tests (163 passing)
PYTHONPATH=src poetry run pytest tests/

# Lint (ruff + black --check + isort --check + mypy)
poetry run bash scripts/lint.sh

# Install locally and try it
poetry run fp --help

Project layout

src/frappe_cli/
├── cli.py                  # root Click group — registers all commands
├── dev/
│   ├── context.py          # bench detection + .fp.yaml read/write
│   └── commands.py         # use, context, sites + passthrough commands
├── install/
│   ├── wizard.py           # fp install wizard
│   ├── context.py          # InstallContext dataclass
│   ├── state.py            # ~/.frappe-cli-state.json (resume support)
│   └── steps/              # one InstallStep class per wizard step
├── step/                   # fp step <name> — thin wrappers around steps/
├── ssl/                    # fp ssl setup, fp ssl list
├── site/, app/, service/, backup/, firewall/, ...
└── utils/                  # shell, errors, logging, validators

Tests live under tests/ (one file per command group, plus test_install_steps.py for the wizard step classes and test_dev_commands.py for dev workflow).

Contributing

1. Fork → feature branch.
2. Add or improve a command group / step.
3. Add tests in tests/ (use click.testing.CliRunner).
4. Run poetry run bash scripts/lint.sh and PYTHONPATH=src poetry run pytest.
5. Open a PR with a clear description.

About

Built by Rashidi Okama in Tanzania to make day-to-day Frappe work easier.

• Website: https://rashidiokama.com
• GitHub: https://github.com/okama12

Run fp about for the in-CLI credits panel. If this project saves you time, please star the repo — it really helps.

License

MIT © Rashidi Okama