Skip to main content
Version: 1.4.1

Hướng Dẫn Sử Dụng sPhoton ERP CLI (erp)

Công cụ dòng lệnh sPhoton ERP CLI (erp) giúp tự động hóa hoàn toàn việc khởi tạo, cấu hình, quản lý và vận hành các môi trường phát triển (development) cũng như kiểm thử/vận hành (staging/production) cho hệ thống ERPNext/Frappe sử dụng Docker Compose.

1. Các lệnh CLI và Cờ (Flags)​

Dưới đây là tổng hợp đầy đủ các lệnh, cờ tương ứng, cách dùng và ngữ cảnh sử dụng thực tế.

1.1. Xem thông tin phiên bản (version)​

  • Cú pháp: 
    erp version
    erp -v
    erp --version
  • Khi nào dùng: Cần kiểm tra thông tin liên hệ của maintainer, slogan thương hiệu, website chính thức hoặc kiểm tra phiên bản CLI hiện tại.

1.2. Khởi tạo dự án mới (new)​

  • Cú pháp: 
    erp new <project_dir> [flags]
  • Các cờ (Flags):
    • --run: Tự động khởi chạy provisioning dựng môi trường ngay sau khi tạo cấu hình thành công.
    • --local: Chỉ định môi trường phát triển cục bộ (local).
    • --staging: Chỉ định môi trường kiểm thử (staging).
    • --production: Chỉ định môi trường vận hành thực tế (production).
    • --name <company_name>: Thiết lập tên công ty / dự án (Mặc định: ERPNext).
    • --port <host_port>: Thiết lập cổng dịch vụ trên máy host (Mặc định: 8123).
    • --host-name <hostname>: Thiết lập tên miền site kèm scheme (ví dụ: http://localhost:8123, https://erp.example.com).
    • --admin-password <password>: Thiết lập mật khẩu cho tài khoản Administrator.
    • --apps <apps>: Danh sách các ứng dụng cài đặt kèm, phân cách bằng dấu phẩy (ví dụ: hrms,payments hoặc appname:https://repo).
    • --image <image>: Tên Docker image (Mặc định: ghcr.io/workdone-vn/erp).
    • --version <tag>: Tag phiên bản Docker image (Mặc định: 1.0.0).
    • --github-token <token>: GitHub PAT — chỉ lưu khi kèm --run, dùng để clone private repo.
    • --ssh-key <path>: Đường dẫn SSH key/file — chỉ lưu khi kèm --run, mount vào container.
    • --auto-check-version: Bật tự động kiểm tra phiên bản mới của ERPNext/Frappe (Mặc định: tắt).
  • Chế độ tự động hoàn toàn (Non-interactive / Agent-friendly): Nếu bạn truyền đủ 3 thông số bắt buộc: Môi trường (một trong các cờ --local/--staging/--production), Tên công ty (--name), và Cổng (--port), CLI sẽ bỏ qua giao diện tương tác TUI hoàn toàn và trực tiếp tạo cấu hình. Ví dụ lệnh chạy nhanh: 
    erp new dev_project --run --local --name ERPNext --port 2345 --host-name http://localhost:2345 --admin-password admin --auto-check-version
  • Giao diện Wizard tương tác (TUI): Nếu thiếu bất kỳ tham số bắt buộc nào, CLI sẽ tự động kích hoạt TUI Wizard tương ứng để hỏi thông tin còn thiếu. Bạn có thể dùng phím Tab/Enter để chuyển bước, Shift+Tab để quay lại và Space để chọn app.
    • Bước 11 (Cấu hình Auto-check update): Wizard sẽ hỏi bạn có muốn bật chế độ tự động check phiên bản mới và thông báo hay không (mặc định nhập n để tắt). Nếu tắt, CLI sẽ tự động tắt popup cảnh báo update "New updates are available" trên Web UI Desk của Frappe để tránh phiền toái cho người dùng.

1.3. Khởi dựng và chạy môi trường (run)​

  • Cú pháp: 
    erp run [flags]
  • Các cờ (Flags):
    • --dry-run: Chỉ in ra màn hình các lệnh docker và bench sẽ được chạy mà không thực sự thực thi chúng.
    • --force: Buộc tải lại (re-download) và cài đặt lại các app bổ sung kể cả khi thư mục apps/<app> đã tồn tại trên host.
  • Cách thức hoạt động:
    1. Tự động viết tệp compose.yml và ghi các tài nguyên Docker (Dockerfile, scripts entrypoint) vào thư mục dự án.
    2. Khởi động các Docker container ở chế độ chạy ngầm (docker compose up -d).
    3. Tự động vá lỗi setup_wizard.js của Frappe core trên host để Setup Wizard nhận diện tiếng Việt mặc định.
    4. Chờ MariaDB container sẵn sàng, sau đó chạy bench new-site để tạo site mới.
    5. Cài đặt erpnext và các ứng dụng bổ sung được định nghĩa trong cấu hình.
      • Nếu thư mục apps/<app> đã tồn tại (ví dụ lần chạy trước bị gián đoạn), CLI tự động bỏ qua bước bench get-app cho app đó để tránh prompt xác nhận A directory for the application '<app>' already exists... khiến lệnh bị lỗi exit status 1 — nhưng vẫn chạy bench install-app để cài app lên site.
      • Khi dùng --force, CLI xóa thư mục apps/<app> cũ trước rồi tải và cài đặt lại từ đầu.
    6. Đặt các thông số hệ thống tiếng Việt mặc định (vi, Vietnam, Asia/Ho_Chi_Minh, VND, định dạng ngày dd-mm-yyyy, ngày đầu tuần thứ Hai Monday).
    7. Khởi động lại các container ứng dụng để tải mã nguồn mới nhất.
  • Khi nào dùng: Chạy lệnh này ngay tại thư mục dự án khi bắt đầu khởi động hoặc dựng mới môi trường dự án.

1.4. Dừng dự án (stop)​

  • Cú pháp: 
    erp stop
  • Mô tả: Tắt tất cả các containers đang chạy ngầm của dự án hiện tại bằng lệnh docker compose down.
  • Khi nào dùng: Khi kết thúc ngày làm việc hoặc muốn tạm dừng dự án để giải phóng tài nguyên CPU/RAM trên máy tính.

1.5. Kiểm tra đồng bộ (verify)​

  • Cú pháp: 
    erp verify [project_dir]
  • Mô tả: Quét cấu hình erp-config.yaml và đối chiếu với file chạy thực tế compose.yml để kiểm tra sự trùng khớp về cổng ánh xạ Nginx, các biến môi trường cài đặt app của backend.
  • Khi nào dùng: Sử dụng trước khi deploy hoặc khi cần kiểm tra xem tệp compose chạy thực tế có đồng bộ với file cấu hình dự án hay không.

1.6. Trình quản lý HUD Dashboard (dashboard)​

  • Cú pháp: 
    erp dashboard
  • Mô tả: Giao diện HUD quản trị tập trung (TUI Bubbletea) hiển thị danh sách các dự án đang tồn tại trên hệ thống.
  • Các phím điều khiển nhanh:
    • s: Bật dự án được chọn (docker compose up -d ngầm).
    • x: Tắt dự án được chọn (docker compose down).
    • r: Khởi động lại dự án (docker compose restart).
    • d: Gỡ bỏ đăng ký (Unregister) dự án khỏi Dashboard (không xóa file trên đĩa cứng).
    • q hoặc Ctrl+C: Thoát dashboard.
  • Khi nào dùng: Khi có nhiều dự án chạy song song và muốn có một giao diện chung để bật, tắt và giám sát nhanh trạng thái của chúng.

1.7. Quản lý ứng dụng (app)​

Quản lý các ứng dụng Frappe động cho site của dự án hiện tại:

  • Cài đặt ứng dụng: 
    erp app install <app_name_or_url> [repo_url] [flags]
    • --force: Buộc cài lại app từ đầu một cách không tương tác — CLI tự động archive thư mục app cũ vào archived/apps/<app>-<ngày> (bản sao an toàn, không xoá mất mã nguồn) rồi truyền --overwrite cho bench get-app để clone lại. Việc archive chủ động này tránh lỗi [Errno 39] Directory not empty của bench khi tên app (erp_admin) khác tên thư mục repo (erp_asian_admin) — vốn khiến --overwrite của bench bị kẹt.
    • --branch <branch_or_tag>: Chỉ định branch hoặc tag cụ thể để cài đặt (ví dụ: --branch develop, --branch v2.0.0). Ghi đè cơ chế tự động dò branch.
    • Bảo mật token: khi dùng GitHub token để truy cập repo private, CLI truyền cho bench get-app URL sạch (không nhúng token) và để git tự rewrite URL sang token qua biến môi trường GIT_CONFIG_* — token không bao giờ xuất hiện trên dòng lệnh (bench hay echo lệnh git clone) hay trong log.
    • Branch được lưu vào erp-config.yaml (apps[].branch) để erp app update khôi phục git theo đúng branch đã cài.
    • Nếu không dùng --force và thư mục apps/<app> đã tồn tại, CLI tự động bỏ qua bước bench get-app (tái sử dụng mã nguồn hiện có) và chỉ chạy bench install-app để cài app lên site. Ví dụ:
    erp app install hrms                                       # App chuẩn, branch tự động
    erp app install wiki https://github.com/frappe/wiki.git    # Custom app, branch tự động
    erp app install my_app --branch develop                    # Chỉ định branch develop
    erp app install my_app https://github.com/org/repo.git#v2.0  # Chỉ định tag v2.0 qua URL
    erp app install erp_admin https://github.com/org/erp_asian_admin --force   # Cài lại từ đầu, app name khác repo folder

Cơ chế chọn Branch/Tag cho App​

CLI áp dụng quy tắc ưu tiên sau để xác định branch/tag khi cài app:

Ưu tiênCơ chếMô tả
1 (cao nhất)# trong URLNếu repo URL chứa dấu # (vd: https://github.com/org/repo.git#develop), CLI truyền nguyên URL cho bench get-app — git/bench sẽ tự giải mã fragment # thành branch/tag.
2Flag --branchNếu không có # trong URL nhưng flag --branch được chỉ định, CLI dùng giá trị này.
3 (thấp nhất)Tự động dòCLI tự xác định branch theo bảng bên dưới:

Branch mặc định cho app chuẩn:

AppBranch
hrmsversion-16
paymentsversion-16
crmmain
slidesdevelop

Custom app (không trong danh sách trên): CLI dò phiên bản Frappe đang chạy trong container (frappe.__version__) và ánh xạ thành version-<major> (vd: version-16, version-15).

Cú pháp # trong URL — hữu ích khi bạn muốn dùng một branch/tag cụ thể mà bench get-app và git hiểu được:

erp app install my_app https://github.com/org/repo.git#develop     # Branch develop
erp app install my_app https://github.com/org/repo.git#v2.0.0      # Tag v2.0.0  
erp app install my_app https://github.com/org/repo.git#abc123def   # Commit hash
  • Gỡ cài đặt ứng dụng: 
    erp app uninstall <app_name> [--force]
    • Tương tác (mặc định): CLI forward terminal xuống prompt xác nhận của bench (All doctypes ... Are you sure?) — bạn gõ y/n bình thường.
    • --force: Bỏ qua prompt để chạy không tương tác (CI/script). CLI truyền --yes (cờ chuẩn của bench để bypass confirmation, không phải --force) kèm auto-confirm — chữa lỗi cũ "hỏi xong abort ngay vì stdin không được forward".
    • Không tương tác + không --force: CLI báo lỗi rõ ràng yêu cầu thêm --force, không để bench abort mơ hồ.
  • Cập nhật ứng dụng: 
    erp app update <app_name>
    • Tự khôi phục git trước khi update: bench update sẽ crash exit status 128 (git symbolic-ref) nếu app thiếu .git (app baked trên staging sau lần cài đầu) hoặc đang ở detached HEAD. CLI tự chữa trước khi chạy bench update:
      • App thiếu .git → git init + thêm remote upstream (lấy URL từ erp-config.yaml) + fetch + checkout đúng branch (lấy từ apps[].branch trong config).
      • App detached HEAD → re-attach HEAD về branch đã cấu hình.
    • Sau khi restore, bench update --apps <app> chạy bình thường.

1.8. Sao lưu và Khôi phục (backup & restore)​

  • Sao lưu cơ sở dữ liệu và files: 
    erp backup
    Mô tả: Tạo bản sao lưu nén .sql.gz lưu bên trong thư mục sites/ của dự án.
  • Khôi phục cơ sở dữ liệu: 
    erp restore <backup_file_path>
    Mô tả: Khôi phục cơ sở dữ liệu của site từ tệp sao lưu. CLI tự động xử lý việc sao chép tệp tạm vào volume container nếu tệp nằm ngoài vùng mount của docker.

1.9. Quản lý dịch thuật đa ngôn ngữ (export:lang & import:lang)​

  • Xuất dịch thuật ra file CSV: 
    erp export:lang <language_code> -f <csv_path>
    Ví dụ: erp export:lang vi -f translation_vi.csv
  • Nhập dịch thuật từ file CSV: 
    erp import:lang <language_code> -f <csv_path>
    Mô tả: Cập nhật bản dịch từ tệp CSV vào các tệp .po của các ứng dụng, tự động chạy biên dịch .mo và xoá cache Desk để cập nhật ngay từ dịch mới lên giao diện.

1.10. Đổi mật khẩu Administrator (reset-password)​

  • Cú pháp: 
    erp reset-password [new_password]
  • Mô tả: Thay đổi mật khẩu tài khoản Administrator của site và ghi nhận lại mật khẩu mới này vào tệp cấu hình dự án. Nếu không truyền mật khẩu mới, CLI sẽ tự động sinh mật khẩu ngẫu nhiên an toàn dài 16 ký tự.

1.11. Cấu hình GitHub Token (github login)​

  • Cú pháp: 
    erp github login --token <token>
  • Các cờ (Flags):
    • --token: Mã Personal Access Token (PAT) của GitHub có quyền đọc/pull các repository private của tổ chức.
  • Khi nào dùng: Khi cấu hình các ứng dụng tùy chỉnh (custom apps) trong tệp erp-config.yaml sử dụng địa chỉ SSH (git@github.com:workdone-vn/...) hoặc HTTPS (https://github.com/workdone-vn/...), CLI sẽ tự động chèn Token đã cấu hình này để chuyển URL thành định dạng truy cập qua HTTPS OAuth2 (https://oauth2:<token>@github.com/...) lúc clone app.
  • Cơ chế hoạt động:
    1. Xác thực token: CLI sẽ tự động dùng lệnh git ls-remote để kiểm tra trực tiếp xem token được cung cấp có hợp lệ và có quyền truy cập (đọc/pull) repository của tổ chức (workdone-vn/erpmanager.git) hay không. Nếu không, CLI sẽ trả về lỗi và không lưu token.
    2. Mã hóa bảo mật: Token sau khi xác thực thành công sẽ được mã hóa đối xứng (sử dụng khóa được tạo từ định danh thiết bị và người dùng hệ điều hành để đảm bảo token không bị lưu dưới dạng văn bản thuần - clear text) và lưu tại tệp cấu hình an toàn trên máy người dùng (~/.erp_github_token).

1.12. Cấu hình SSH Key (ssh-key import)​

  • Cú pháp:

    erp ssh-key import [flags]

  • Các cờ (Flags):

    • --path <path>: Đường dẫn tới tệp SSH Key đơn (ví dụ: ~/.ssh/id_ed25519) hoặc thư mục chứa các SSH key (ví dụ: ~/.ssh). Mặc định là thư mục .ssh của người dùng (~/.ssh).

  • Khi nào dùng: Khi bạn muốn sử dụng khóa SSH có sẵn trên máy host để clone/triển khai các custom app qua giao thức SSH (ví dụ: git@github.com:...) thay vì cấu hình GitHub Personal Access Token (PAT).

  • Hai chế độ mount:

    Chế độ A — Mount toàn bộ thư mục ~/.ssh:

    erp ssh-key import --path ~/.ssh

    Toàn bộ .ssh (mọi key + known_hosts) được mount chỉ-đọc vào /home/frappe/.ssh. Git/ssh trong container tự dò key theo chuẩn.

    Chế độ B — Chỉ mount 1 key file đơn (khuyến nghị — an toàn hơn):

    erp ssh-key import --path ~/.ssh/id_ed25519
    # hoặc bất kỳ file private key nào, tên không quan trọng:
    erp ssh-key import --path ~/keys/github_deploy_key

    Dù file gốc tên gì, CLI luôn mount key đó vào /home/frappe/.ssh/id_ed25519 (tên chuẩn cố định trong container). CLI tự động:

    • Mount đúng file key (bất kể tên gốc) vào /home/frappe/.ssh/id_ed25519.
    • Móc kèm known_hosts (nếu tồn tại cạnh key) để xác thực host GitHub.
    • Set GIT_SSH_COMMAND để git/ssh chỉ dùng đúng key đó: 
      GIT_SSH_COMMAND=ssh -i /home/frappe/.ssh/id_ed25519 -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new

  • Cơ chế hoạt động:

    1. Lưu cấu hình: CLI kiểm tra sự tồn tại của tệp/thư mục SSH Key trên máy host và lưu đường dẫn tuyệt đối vào tệp cấu hình toàn cục ~/.erp_ssh_key_path.
    2. Mount vào container: Khi sinh ra tệp compose.yml (chạy erp run hoặc erp new --run), CLI đọc đường dẫn đã lưu và thêm bind mount vào service backend:
      • Nếu là thư mục (ví dụ ~/.ssh): <đường_dẫn>:/home/frappe/.ssh:ro.
      • Nếu là một tệp key đơn (bất kỳ tên gì, ví dụ ~/keys/deploy_key): <đường_dẫn>:/home/frappe/.ssh/id_ed25519:ro (+ known_hosts nếu có).
    3. Tái tạo cấu hình: erp run luôn tạo lại compose.yml mỗi lần chạy, nên mount SSH key được cập nhật tự động; docker compose up -d sẽ tạo lại container backend với mount mới. Sau đó erp app install chỉ cần chạy bench get-app bên trong container vốn đã được mount key.
    4. Tác dụng: Container backend sử dụng trực tiếp SSH Credentials và danh sách known_hosts từ máy host để clone code qua Git SSH mà không cần can thiệp thủ công. (Không có bước docker compose cp hay chown/chmod — đây là bind mount trực tiếp, quyền đọc key được xác định bởi quyền trên máy host.)

1.13. Nâng cấp CLI tự động (upgrade)​

  • Cú pháp: 
    erp upgrade [version]
  • Khi nào dùng: Khi bạn muốn tự động nâng cấp chính công cụ dòng lệnh erp lên phiên bản mới nhất (mặc định) hoặc một phiên bản cụ thể từ máy chủ phân phối https://erp-cli.workdone.vn/.
  • Cơ chế hoạt động:
    1. Kiểm tra phiên bản: CLI gửi yêu cầu tới API máy chủ (/versions.json) để lấy danh sách phiên bản hiện có. Nếu phiên bản được chỉ định không tồn tại, CLI sẽ xuất thông báo Không tìm thấy phiên bản. Nếu phiên bản hiện tại đã là phiên bản mới nhất hoặc mới hơn phiên bản chỉ định, CLI sẽ báo đã là bản mới nhất.
    2. Hiển thị thông tin phiên bản: Trước khi tải, CLI hiển thị phiên bản mục tiêu, hệ điều hành/nền tảng, tên tệp tải về, nguồn tải và kích thước tệp.
    3. Tải file binary: Khi nâng cấp lên phiên bản mới nhất, CLI ưu tiên tải từ đường dẫn ổn định https://erp-cli.workdone.vn/dist/latest/<file> (không cần chỉ định số phiên bản). Nếu endpoint latest chưa được cấu hình trên máy chủ, CLI tự động fallback về đường dẫn theo phiên bản cụ thể /dist/<version>/<file>. Trong lúc tải, CLI hiển thị thanh tiến trình (Downloading [■■····] 42%) cùng số liệu hoàn thành.
    4. Thay thế tệp thực thi: CLI đổi tên tệp gốc thành *.old, ghi tệp mới vào đúng vị trí cũ rồi xóa tệp cũ; nếu ghi lỗi, CLI khôi phục lại tệp gốc. Trên Windows, erp.exe đang chạy bị hệ điều hành khóa, CLI ghi tệp mới thành erp.exe.new và khởi động script cập nhật nền (erp-update.cmd) để tự hoán đổi khi tiến trình thoát — sau khi hoàn tất bạn chỉ cần chạy lại erp version để xác nhận.
  • Đường dẫn tải ổn định (stable): Ngoài lệnh upgrade, bạn có thể tải trực tiếp phiên bản mới nhất từ đường dẫn không đổi (không cần chỉ định số phiên bản):
    • Linux amd64: https://erp-cli.workdone.vn/dist/latest/erp-linux-amd64
    • Windows x86: https://erp-cli.workdone.vn/dist/latest/erp-windows-386.exe
    • macOS Apple Silicon (arm64): https://erp-cli.workdone.vn/dist/latest/erp-darwin-arm64
    • macOS Intel (amd64): https://erp-cli.workdone.vn/dist/latest/erp-darwin-amd64

1.14. Bật/Tắt Developer Mode (devmode)​

  • Cú pháp: 
    erp devmode [on|off]
  • Mô tả: Bật hoặc tắt chế độ nhà phát triển (developer_mode) trong cấu hình Frappe bench. Ở chế độ on, Frappe hiển thị đầy đủ menu Debug, Developer Tools, và cho phép chỉnh sửa trực tiếp DocType, Server Script, Report, Page, Web Page,... trên Web UI mà không cần qua mã nguồn.
  • Mặc định: on. Chạy erp devmode không tham số sẽ bật developer mode.
  • Cách hoạt động: Lệnh thực thi bench set-config -gp developer_mode 1 (bật) hoặc bench set-config -gp developer_mode 0 (tắt) bên trong container backend.
  • Khi nào dùng:
    • Bật (on): Khi đang phát triển custom app, cần truy cập tính năng Developer của Frappe.
    • Tắt (off): Khi chạy production hoặc không cần các công cụ phát triển để tăng hiệu năng và bảo mật.

1.15. Chạy lệnh trong container (exec)​

  • Cú pháp: 
    erp exec <command>
  • Mô tả: Chạy một lệnh bất kỳ bên trong container backend của dự án hiện tại (tương đương docker compose exec backend bash -c "<command>").
  • Ví dụ: 
    erp exec "python -c 'import frappe; print(frappe.__version__)'"
    erp exec "bench --site frontend console"
    erp exec "cat /etc/os-release"
  • Khi nào dùng: Gỡ rối nhanh, kiểm tra môi trường, hoặc chạy lệnh bench/python trực tiếp trong container mà không cần docker compose exec thủ công.

1.16. Đổi tên miền site (set:hostname)​

  • Cú pháp: 
    erp set:hostname <hostname>
  • Mô tả: Cập nhật tên miền (hostname) của site hiện tại, đồng thời đồng bộ vào erp-config.yaml, compose.yml, project registry và cấu hình trong container.
  • Yêu cầu: Hostname phải có scheme (http:// hoặc https://). Ví dụ: http://localhost:8123, https://erp.example.com.
  • Cơ chế hoạt động:
    1. Cập nhật cfg.HostName và lưu erp-config.yaml (tự động sinh lại compose.yml).
    2. Cập nhật registry (projects.json) cho dashboard.
    3. Chạy bench --site frontend set-config host_name <hostname> trong container.
    4. Restart container frontend để Nginx nạp cấu hình mới.

1.17. Nâng cấp môi trường từ phiên bản cũ (migrate-from)​

  • Cú pháp: 
    erp migrate-from <version>
  • Mô tả: Di trú (migrate) cấu hình và dữ liệu dự án từ phiên bản CLI cũ lên phiên bản hiện tại.
  • Hỗ trợ: Hiện chỉ hỗ trợ erp migrate-from 1.1 (nâng cấp lên chuẩn môi trường v1.2+).
  • Cơ chế hoạt động:
    1. Nếu chưa có HostName, CLI hỏi và lưu.
    2. Nếu site frontend đã tồn tại: chạy bench migrate + cập nhật Docker resources + restart.
    3. Nếu site cũ khác tên: backup database → cập nhật resources → đổi tên site sang frontend → migrate → tạo symlink alias → clear cache.
    4. Nếu migration lỗi: tự động rollback (restore database, khôi phục tên site cũ).

1.18. Cài đặt Agent Skills cho AI IDE (skills)​

  • Cú pháp: 
    erp skills [--list] [--skill <repo>] [--skills <names>] [--ide <ide>]
  • Mô tả: Cài đặt các Agent Skills về Frappe/ERPNext vào project cho AI IDE của bạn (hỗ trợ opencode và antigravity — JetBrains). Skills được nạp từ máy chủ phân phối https://github.com/frappe/skills (chính chủ) hoặc https://github.com/lubusIN/frappe-skills (LUBUS), và được cài vào project (thư mục .agents/skills/).
  • Các cờ (Flags):
    • --list: Chỉ hiển thị danh sách bộ skills và IDE được hỗ trợ.
    • --skill <repo>: Bộ skills để cài (frappe/skills | lubusIN/frappe-skills).
    • --skills <names>: Các skill cụ thể muốn cài, cách nhau bằng dấu phẩy (ví dụ frappe-app-dev,code-style).
    • --ide <ide>: IDE đích (opencode | antigravity), cách nhau bằng dấu phẩy.
  • Cách dùng:
    • Xem danh sách: erp skills --list
    • Chọn tương tác (bộ skills → các skill → IDE): erp skills
    • Cài không tương tác: erp skills --skill frappe/skills --skills frappe-app-dev,code-style --ide opencode
  • Khi nào dùng: Khi muốn AI coding assistant nắm được kiến thức chuẩn Frappe/ERPNext (DocTypes, APIs, testing, code review...) khi làm việc trong project.

2. Hướng dẫn phát triển Custom App (Local Development)​

Khi làm việc ở môi trường phát triển cục bộ (local), thư mục ./apps trên máy host sẽ được mount trực tiếp vào container. Bạn có thể áp dụng quy trình phát triển và kiểm thử sau:

2.1. Khởi tạo Custom App mới​

Chạy lệnh tại thư mục dự án:

erp dev create-app <app_name>

2.2. Cơ chế tự động nạp lại (Auto-reload)​

  • Frontend (JS/CSS/Assets): Chạy watcher để tự động phát hiện và biên dịch lại assets frontend khi bạn lưu file thay đổi ở host: 
    erp dev watch
  • Backend (Python API & Controllers): Ở chế độ ENVIRONMENT=development, Gunicorn chạy trong container backend được bật cờ --reload. Mỗi khi bạn chỉnh sửa và lưu file .py ở host, Gunicorn tự động tải lại code Python mới ngay lập tức, bạn không cần chạy lệnh restart thủ công.

2.3. Khi nào cần chạy lệnh Reload thủ công (erp dev reload)?​

Các tiến trình chạy nền như Background Workers (bench worker) và Scheduler (bench schedule) không sử dụng Gunicorn nên không có tính năng tự động reload. Bạn cần chạy lệnh reload thủ công khi:

  1. Thay đổi logic của các tác vụ chạy nền (background tasks / jobs).
  2. Thay đổi cấu hình hệ thống trong file hooks.py (chỉ được load lại khi khởi động hoặc clear cache cụ thể). Lệnh chạy:
erp dev reload

Lệnh này sẽ xoá cache và khởi động lại nhanh các container backend và workers để load code mới.

2.4. Mở Interactive Console​

Truy cập nhanh Python interactive console của Frappe trực tiếp trong container để test code, chạy thử lệnh ORM hoặc kiểm tra database:

erp dev console