CLI

CLI là bộ công cụ dòng lệnh hỗ trợ nhà phát triển khởi tạo, phát triển và đóng gói AI App trên hệ sinh thái V-App một cách nhanh chóng và tiêu chuẩn.

Cài đặt

Yêu cầu hệ thống: Node.js LTS v22+

npm

# Cài đặt global
npm install -g @v-miniapp/cli

# Hoặc cài đặt trong repo
npm install -D @v-miniapp/cli

yarn

# Cài đặt global
yarn global add @v-miniapp/cli

# Hoặc cài đặt trong repo
yarn add --dev @v-miniapp/cli

pnpm

# Cài đặt global
pnpm add -g @v-miniapp/cli

# Hoặc cài đặt trong repo
pnpm add -D @v-miniapp/cli

Sau khi cài đặt global, bạn có thể sử dụng lệnh v-miniapp-cli trực tiếp từ terminal. Nếu cài đặt trong repo, sử dụng thông qua định nghĩa scripts trong package.json.

---

Các lệnh cơ bản

Xác thực (Identity)

Để thực hiện các lệnh cần giao tiếp với VSF API (như create, dev, deploy), bạn cần đăng nhập thông qua hệ thống VID.

Đăng nhập

v-miniapp-cli login

Đăng xuất

v-miniapp-cli logout

Khởi tạo dự án

Khởi tạo dự án AI App mới. Tự động cấu hình và cài đặt các dependencies cần thiết.

v-miniapp-cli create

Phát triển (Development)

Start MCP Server và mở Inspector giúp xem trước UI cũng như kiểm thử input/output của tools

Tại folder của project AI App vừa được tạo, chạy lệnh

npm run dev

Sau khi chạy lệnh này, inspector sẽ được tự động mở, mặc định sẽ là http://127.0.0.1:6274/

MCP Server sẽ được chạy ở port 4000 - 4999

Build cho Production

Đóng gói widget và server code cho môi trường production:

npm

npm run build

pnpm

pnpm build

yarn

yarn build

Lệnh build thực hiện:

• Compile widget — Vite build các widget trong web/src/widgets/ thành file tĩnh tối ưu
• Compile server — Biên dịch TypeScript server code
• Output — Tất cả được đóng gói vào thư mục dist/

Chạy Production Server

Sau khi build, khởi động server ở chế độ production:

npm

npm run start

pnpm

pnpm start

yarn

yarn start

cảnh báo

Bạn cần chạy lệnh build trước khi chạy start. Server production đọc từ thư mục dist/ — nếu chưa build sẽ không có gì để chạy.

Đặc điểm của Production Server

Đặc điểm	Mô tả
Thư mục chạy	dist/ — code đã được biên dịch và tối ưu
Biến môi trường	NODE_ENV=production
Static assets	Widget và stylesheet được phục vụ từ /assets
MCP endpoint	Server expose MCP interface tại /mcp
Cổng mặc định	3000 (có thể thay đổi qua biến PORT)

So sánh Development vs Production

	Development (npm run dev)	Production (npm run start)
Cổng mặc định	4000 - 4999	3000
Hot reload	✅ Có (Vite dev server)	❌ Không
Inspector	✅ Tự động mở	❌ Không có
Tối ưu hoá	❌ Không	✅ Minify, tree-shaking
Phù hợp cho	Phát triển & debug	Deploy lên server thật

Deploy

Khi deploy lên server thật, MCP client bên ngoài sẽ kết nối tới endpoint của bạn:

https://your-domain.com/mcp

Checklist trước khi deploy

1. ✅ Chạy npm run build thành công, không có lỗi
2. ✅ Test local với npm run start trước khi deploy
3. ✅ Cấu hình biến môi trường production (server/.env)
4. ✅ Cấu hình MCP endpoint PROD trên V-Console
5. ✅ Verify domain trên V-Console

Kiểm tra hệ thống

Kiểm tra kết nối

v-miniapp-cli healthcheck

Kiểm tra trạng thái kết nối tới các dịch vụ của V-App (Auth, API, Web) để đảm bảo môi trường phát triển sẵn sàng.

Kiểm tra phiên bản CLI

v-miniapp-cli version-check

So sánh phiên bản hiện tại với phiên bản mới nhất trên NPM và phiên bản tối thiểu bắt buộc từ hệ thống để đảm bảo tính tương thích.

---

Debug mode

Flag --debug dùng để bật chế độ ghi log chi tiết, hỗ trợ debug trong quá trình phát triển và xử lý lỗi.

v-miniapp-cli [command] --debug

Khi bật --debug, CLI sẽ:

• Log chi tiết quá trình khởi tạo command
• In đầy đủ stack trace khi xảy ra lỗi

Debug mode áp dụng cho tất cả các lệnh của CLI.