The fast way to develop Frappe apps.
Weg means "way" in German and "speed" in Marathi/Sanskrit — a modern replacement for Frappe's bench CLI with declarative configuration and faster tooling.
Weg supports three distinct workflows for Frappe development:
Your app is the project root. The bench infrastructure is hidden in .weg/. Ideal for developing a single Frappe app with modern tooling.
weg new myapp
cd myapp
weg startConfiguration lives in pyproject.toml [tool.weg].
Traditional bench directory structure. Use this when working with multiple apps or migrating from existing bench setups.
cd /path/to/frappe-bench
weg init
weg startConfiguration lives in weg.toml.
Work with remote Frappe sites (like Frappe Cloud) without direct bench access. Clone customizations locally, edit with any tools, and sync changes back.
weg remote clone https://mysite.frappe.cloud mysite
cd mysite
# Edit Client Scripts, Server Scripts, Custom Fields locally
weg remote push -m "Add priority field to Todo"This creates a git-backed directory mirroring the site's customizations, enabling version control, team collaboration, and AI-assisted editing.
- Declarative configuration via
weg.tomlorpyproject.toml - Modern tooling - devbox (Nix), uv (fast Python), process-compose
- Direct API access -
weg apiwithout HTTP overhead - Container support - Docker Compose generation and production image builds
- MCP server - AI assistant integration via Model Context Protocol
- 70+ commands covering all common Frappe development workflows
- Works from anywhere - run commands from any subdirectory within your project
# Download the latest binary
curl -fsSL https://github.com/gavindsouza/weg/releases/latest/download/weg-$(uname -s)-$(uname -m) -o weg
chmod +x weg
mkdir -p ~/.local/bin
mv weg ~/.local/bin/
# Add to PATH if not already (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"
# Or build from source
git clone https://github.com/gavindsouza/weg
cd weg
go build -o weg .
mv weg ~/.local/bin/weg new myapp
cd myapp
weg start
weg site browse # Open in browser (auto-login as Administrator)cd /path/to/frappe-bench
weg init
weg startweg remote clone https://mysite.frappe.cloud mysite
cd mysite
# Edit customizations locally...
weg remote status # See what changed
weg remote push # Push changes to remoteweg site list # List all sites
weg site new mysite.localhost # Create new site
weg site drop mysite.localhost # Delete site
weg site use mysite.localhost # Set default site
weg site backup # Backup current site
weg site restore backup.sql.gz # Restore from backup
weg site password # Reset admin password
weg site browse # Open site in browserweg app list # List installed apps
weg app get erpnext # Install ERPNext
weg app get https://github.com/user/custom-app
weg app remove custom-app # Remove an app
weg site install custom-app # Install app on siteweg start # Start all services
weg stop # Stop all services
weg build # Build frontend assets
weg build --app myapp # Build specific app
weg test # Run tests
weg test --module myapp.tests # Run specific tests
weg console # Open Python console
weg db console # Open database consoleweg cache clear # Clear Redis + pycache
weg scheduler status # Check scheduler status
weg scheduler enable # Enable background jobs
weg scheduler disable # Disable background jobs
weg scheduler jobs # List pending jobs# Direct API calls without HTTP overhead
weg api call frappe.client.get_count doctype=User
weg doc get User Administrator # Get a document
weg doc list User --limit 10 # List documents
weg doctype list # List all doctypesweg remote clone <url> <dir> # Clone site customizations
weg remote pull # Pull changes from remote
weg remote push # Push local changes to remote
weg remote push -m "message" # Push with commit message
weg remote status # Show local vs remote diff
weg remote sync # Bidirectional sync
weg remote login <url> # Save credentials for a siteweg cloud login # Authenticate with Frappe Cloud
weg cloud sites # List your sites
weg cloud deploy mysite # Deploy to cloud
weg cloud logs mysite # View site logs# Docker Compose for local development
weg docker init # Generate docker-compose.yml
weg docker init --mode prod # Generate for production
weg docker up # Start containers
weg docker down # Stop containers
weg docker logs # View container logs
weg docker ps # List running containers
# Build production images
weg image build # Build container image
weg image build --tag myapp:v1 # Custom tag
weg image build --push # Build and push to registry
weg image list # List local imagesWeg uses weg.toml for bench-centric projects or pyproject.toml [tool.weg] for app-centric projects.
[frappe]
version = "15"
database = "mariadb"
[apps.erpnext]
url = "https://github.com/frappe/erpnext"
branch = "version-15"
[[sites]]
name = "mysite.localhost"
default = true
apps = ["frappe", "erpnext"]
[services.workers]
short = 1
default = 2
long = 1[tool.weg]
frappe_version = "15"
[tool.weg.dependencies]
erpnext = { url = "https://github.com/frappe/erpnext", branch = "version-15" }
[tool.weg.sites]
default = "dev.localhost"Weg generates process-compose.yaml for running development services. You can customize it by creating process-compose.override.yaml:
# process-compose.override.yaml
processes:
web:
environment:
- GUNICORN_WORKERS=4
# Disable a process
watch:
disabled: true
# Add a custom process
mailhog:
command: mailhog
readiness_probe:
http_get:
port: 8025The override file is automatically included when present (uses process-compose's native include feature).
For containerized development or production, use weg docker init to generate a docker-compose.yml with all required services (web, workers, scheduler, socketio, database, Redis).
Options include --mode prod for production settings, --no-db for external databases, and --web-port to customize ports. Edit the generated file directly or use Docker Compose overrides for further customization.
Use weg image build to create OCI-compliant production images. The multi-stage Dockerfile generates specialized targets (web, worker, scheduler, socketio) optimized for deployment to Docker, Podman, or Kubernetes.
The easiest way to enable completions:
# Bash - add to ~/.bashrc
eval "$(weg completion bash)"
# Zsh - add to ~/.zshrc
eval "$(weg completion zsh)"
# Fish - run once
weg completion fish | source
# Or persist: weg completion fish > ~/.config/fish/completions/weg.fishFor faster shell startup (optional), you can cache the completions:
# Bash
weg completion bash > ~/.local/share/bash-completion/completions/weg
# Zsh (if using Oh My Zsh)
weg completion zsh > ~/.oh-my-zsh/completions/_weg| Feature | weg | bench |
|---|---|---|
| Configuration | Declarative (TOML) | Imperative (commands) |
| Development modes | App-centric, bench-centric, remote-site | Bench-centric only |
| Python management | uv (fast) | pip |
| System dependencies | devbox/Nix (reproducible) | Manual |
| Process management | process-compose | honcho/supervisord |
| Container support | Built-in (Docker Compose + image builds) | frappe_docker (separate) |
| API access | Direct (no HTTP) | Via HTTP |
| Remote site editing | Built-in (git-backed) | Not available |
| Cloud integration | Built-in | Separate tool |
Weg includes an MCP (Model Context Protocol) server that lets AI assistants manage your Frappe environment:
weg mcp install # Configure for Claude Code / other MCP clientsThe MCP server exposes 12 tools for running Python, calling APIs, managing sites, and more — replacing common anti-patterns like manual bench activation or direct frappe imports.
See CONTRIBUTING.md for setup, testing, and code style guidelines.
- Go 1.24+ (for building from source)
- devbox (installed automatically on first use)
- Git