Công cụ dòng lệnh

CLI Reference

Đúng 3 lệnh. cpt cài và đồng bộ template vào ~/.claude, và quản lý plan tracking cho workflow.

Mọi flag dưới đây lấy trực tiếp từ cpt-cli/src/index.ts. Đây là lệnh gõ trong terminal — khác với lệnh /cpt: gõ trong Claude Code.

init và uninstall chỉ đụng ~/.claude/; plan chỉ đụng file plan trong dự án. Không lệnh nào ghi đè code của bạn.

# chạy không cần cài toàn cục (khuyên dùng)
$ npx @tam-hopee/cpt-cli@latest <lệnh> [options]

# hoặc cài toàn cục rồi dùng lệnh `cpt`
$ npm install -g @tam-hopee/cpt-cli
$ cpt --help
$ cpt --version

Yêu cầu: Node.js ≥ 18, Git, đã cấu hình SSH cho Backlog (CLI clone template qua SSH).

Ví dụ trong trang này viết dạng cpt … cho gọn — thay bằng npx @tam-hopee/cpt-cli@latest … nếu bạn không cài toàn cục.

01 `cpt init`

Cài đặt hoặc cập nhật template vào ~/.claude/.

$ cpt init [options]

Flag	Mô tả
`-v, --verbose`	In log chi tiết
`-f, --force`	Bỏ qua các bước xác nhận
`--shallow`	Shallow clone `--depth 1` (mặc định bật)
`--no-shallow`	Full clone (đầy đủ lịch sử)
`--dev`	Cài template từ nhánh `dev` thay vì nhánh mặc định (`main`). Không cần cho việc thường ngày — `dev` đã merge vào `main` và hiện đang sau `main`, nên `--dev` cho bản cũ hơn. Chỉ dùng khi cần test pre-release.
`--dry-run`	Chỉ báo cáo những gì sẽ thay đổi (file cũ sẽ xoá, path sẽ được retire, file sẽ copy) rồi thoát — không ghi gì cả.
`--no-deletions`	Bỏ qua hoàn toàn danh sách retire của template. Việc dọn file cũ theo manifest vẫn chạy bình thường.
`--apply-deletions`	Retire path trong danh sách mà không hỏi, kể cả path manifest không xác nhận được nguồn gốc. Bắt buộc khi chạy không có terminal (CI, script) — riêng `--force` không bao giờ đủ để chạm vào path loại này.

Quy trình

Xác nhận nhánh cài (bỏ qua khi có --force hoặc --dev)
Clone template vào thư mục tạm
Transform path cho bản cài toàn cục (.claude/ → $HOME/.claude/)
Dọn file cũ: đọc manifest lần cài trước, xoá những file template không còn ship nữa (có xác nhận)
Merge file mới vào ~/.claude
Ghi lại manifest metadata.json
Retire path trong danh sách deletions của template — chuyển vào ~/.claude/.cpt-trash/ (có xác nhận). Chạy sau khi ghi manifest, nên bấm huỷ ở bước này không làm hỏng manifest.
Copy CLAUDE.md
Hỏi thiết lập API key (Gemini cho ai-multimodal; tuỳ chọn Discord webhook, Telegram token)
Hỏi cài dependency của skills (chạy install.sh)

# cài lần đầu / cập nhật
$ cpt init

# xem trước sẽ xoá/copy gì mà không ghi gì cả
$ cpt init --dry-run

# cài từ nhánh dev — chỉ khi cần test pre-release, hiện đang sau main
$ cpt init --dev

# không hỏi, full clone, log chi tiết
$ cpt init --force --no-shallow --verbose

Bảo vệ file: init không ghi đè file nhạy cảm hoặc cấu hình của bạn (.env*, key, CLAUDE.md…). File tuỳ biến được giữ lại; chỉ template được cập nhật.

Cập nhật có dọn file cũ

Khi chạy lại init để cập nhật, những file template đã bị gỡ hoặc đổi tên ở bản mới sẽ được xoá khỏi ~/.claude/. Quyết định dựa trên manifest metadata.json ghi lại lần cài trước — chỉ file do cpt cài mới bị đụng tới.

Loại file	Khi template không còn ship
File `cpt` đã cài, bạn chưa sửa	Xoá (có xác nhận, bỏ qua với `--force`)
File `cpt` đã cài, bạn đã sửa	Giữ lại + báo tên để bạn tự quyết định
File bạn tự thêm	Giữ nguyên — không nằm trong manifest nên không bao giờ bị xoá
File được bảo vệ (xem dưới)	Giữ nguyên — không bao giờ bị đụng, ở bất kỳ độ sâu nào

Tập file được bảo vệ đầy đủ: .env, CLAUDE.md, .gitignore, .mcp.json, .repomixignore, metadata.json (bản ở gốc ~/.claude), cộng với .env.*, *.key, *.pem, *.p12. Một định nghĩa duy nhất dùng chung cho cả dọn file cũ lẫn retire — không cơ chế nào chạm được vào chúng.

Bản cài cũ không có metadata.json: không có manifest thì không biết file nào do cpt cài, nên phần dọn file cũ theo manifest không xoá gì cả — chỉ cảnh báo rồi merge và ghi manifest mới. Nhưng danh sách retire của template vẫn chạy trên những bản cài này — đó chính là lý do nó tồn tại. Nó chỉ đụng đúng các path template ghi tên.

# xem trước danh sách file cũ sẽ bị xoá
$ cpt init --dry-run
# ⚠ 3 file(s) no longer in the template would be removed:
#   - skills/old-skill/SKILL.md
#   - commands/removed.md
# Merge would copy 1502 file(s), skip 9 protected

Danh sách retire của template

Việc dọn ở trên chỉ với tới file có trong manifest. Nhưng bản cài từ 0.1.5 trở về trước không hề có manifest, và file bị bỏ rơi từ những bản đó thì không manifest nào ghi nhận — chúng nằm lại ~/.claude mãi mãi.

Vì vậy template mang theo một danh sách retire do người bảo trì tự ghi tên từng path. Nó không cần manifest, nên nó với tới được cả những bản cài cũ nhất. Đổi lại nó có thể đụng vào file mà manifest không xác nhận được nguồn gốc — nên nó không xoá, mà chuyển.

	Dọn file cũ theo manifest	Danh sách retire
Căn cứ	manifest lần cài trước	template ghi tên path
Chạy trên bản cài không manifest	Không	Có
Cách gỡ	xoá hẳn	chuyển vào `.cpt-trash/`
Khôi phục được	Không	Có

Khôi phục path đã bị retire

Không có gì bị xoá thật. Mỗi lần chạy tạo một thư mục theo dấu thời gian trong ~/.claude/.cpt-trash/, giữ nguyên cấu trúc path. Muốn lấy lại thì chuyển ngược ra:

# xem các lần retire gần đây (giữ 3 lần gần nhất)
$ ls ~/.claude/.cpt-trash/
# 2026-08-21T09-14-02Z

# xem lần gần nhất đã lấy đi những gì
$ find ~/.claude/.cpt-trash/2026-08-21T09-14-02Z -type f

# chuyển ngược lại đúng chỗ cũ
$ mv ~/.claude/.cpt-trash/2026-08-21T09-14-02Z/skills/old-skill ~/.claude/skills/

Chỉ giữ 3 lần gần nhất, và việc dọn bớt diễn ra ở đầu mỗi lần chạy — nên nếu bạn bấm huỷ giữa chừng, lần retire bạn đang cần khôi phục vẫn còn nguyên.

Những gì danh sách này không làm được

Path nằm ngoài thư mục `cpt` thực sự từng cài	Bị từ chối. `~/.claude` là thư mục trạng thái của chính Claude Code — `settings.json`, lịch sử phiên, `projects/` đều không phải của `cpt`.
File được bảo vệ	Không bao giờ bị đụng, dù template có ghi tên.
File bạn đã tự sửa	Giữ lại và báo tên. Ngoại lệ: khi template retire nguyên một thư mục thì cả thư mục đi theo — lấy lại từ `.cpt-trash/`.
Quá 200 path trong một lần chạy	Không retire gì cả và báo pattern gây ra. `--force` không phá được giới hạn này.
Symlink trỏ ra ngoài `~/.claude`	Bị từ chối. Kiểm bằng đường dẫn thật, không phải so chuỗi.

# xem trước sẽ retire gì mà không đụng vào đĩa
$ cpt init --dry-run

# bỏ qua hoàn toàn phần retire
$ cpt init --no-deletions

# chạy trong CI / script (không có terminal để hỏi)
$ cpt init --force --apply-deletions

--force không phải là đồng ý. Nó chỉ bỏ qua câu hỏi. Nó không bao giờ cho phép retire path mà manifest không xác nhận được nguồn gốc, và không nới được giới hạn 200 path. Muốn vậy phải nói rõ bằng --apply-deletions. Chạy không có terminal mà không có flag này thì phần retire bị bỏ qua kèm thông báo.

02 `cpt uninstall`

Gỡ template khỏi ~/.claude/ theo manifest các file đã cài — file bạn tự thêm được giữ nguyên.

$ cpt uninstall [options]

Flag	Mô tả
`-v, --verbose`	In log chi tiết
`-f, --force`	Bỏ qua xác nhận
`--purge`	Xoá toàn bộ `~/.claude/` khi không có manifest. Xoá luôn cả file bạn tự thêm — chỉ dùng khi thực sự muốn làm sạch.

$ cpt uninstall          # gỡ, có xác nhận
$ cpt uninstall --force  # gỡ luôn không hỏi

Không có metadata.json: uninstall từ chối xoá thay vì đoán mò — không có manifest thì không phân biệt được file của cpt với file của bạn. Cách an toàn: chạy cpt init để tạo lại manifest, rồi cpt uninstall để gỡ chính xác. Muốn xoá sạch bất chấp thì dùng cpt uninstall --purge.

03 `cpt plan`

Theo dõi plan cho workflow: đọc và cập nhật plan.md + phase-*.md một cách xác định, thay vì sửa tay. Được dùng bởi /cpt:cook, /cpt:plan, /cpt:project-management.

$ cpt plan [action] [target] [options]

Action đọc — hỗ trợ `--json`

Lệnh	Mô tả
`cpt plan status [<plan.md\|dir>]`	Thanh tiến độ + tóm tắt `blockedBy`/`blocks`
`cpt plan parse [<target>]`	Liệt kê các phase đã parse
`cpt plan validate [<target>] [--strict]`	Báo cáo tuân thủ định dạng

Action ghi — thao tác trên `plan.md` ở cwd hoặc thư mục cha

Lệnh	Mô tả
`cpt plan create --title "X" --phases "A,B,C" --dir <dir>`	Tạo plan mới
`cpt plan check <id> [--start]`	Đánh dấu phase hoàn thành (hoặc đang làm)
`cpt plan uncheck <id>`	Đặt lại phase về `pending`
`cpt plan add-phase "Name" [--after <id>]`	Thêm phase / chèn sub-phase

Options

Flag	Áp dụng	Mô tả
`--json`	action đọc	Xuất JSON
`--strict`	`validate`	Coi warning là lỗi
`--global`	tất cả action	Giải quyết theo `~/.claude/plans`. Với `check`/`uncheck`/`add-phase` phải kèm `--dir` để chỉ ra plan nào — vì tham số vị trí của các action này là phase ID, không phải đường dẫn.
`--title <title>`	`create`	Tiêu đề plan
`--phases <names>`	`create`	Danh sách phase, phân tách bằng dấu phẩy
`--dir <dir>`	`create` + `check`/`uncheck`/`add-phase` khi dùng `--global`	Thư mục plan (phải nằm trong `~/.claude/plans` khi có `--global`)
`--priority <P1\|P2\|P3>`	`create`	Độ ưu tiên
`--issue <number>`	`create`	Số issue liên kết
`--after <id>`	`add-phase`	Chèn sub-phase sau phase này
`--start`	`check`	Đánh dấu đang làm thay vì hoàn thành

# tạo plan
$ cpt plan create --title "Thêm auth" --phases "Design,Build,Test" --dir plans/auth --priority P2

# xem tiến độ dạng JSON
$ cpt plan status plans/auth --json

# đánh dấu phase 1 đang làm, rồi hoàn thành
$ cpt plan check 1 --start
$ cpt plan check 1

# chèn sub-phase sau phase 2
$ cpt plan add-phase "Security review" --after 2

check/uncheck cập nhật cả bảng trong plan.md và frontmatter của file phase, rồi tính lại trạng thái plan (mọi phase completed → done; có phase đang làm → in-progress).

04 Xử lý sự cố

Triệu chứng	Xử lý
`git` không khả dụng	Cài Git, kiểm tra `git --version`
Clone thất bại	Kiểm SSH tới Backlog (`ssh -T hopee@hopee.git.backlog.com`) và quyền repo
Node quá cũ	Cần Node ≥ 18 (`node --version`, `nvm use 18`)
`cpt plan check` báo "not in canonical format"	Sửa bảng phase trong `plan.md` về đúng 3 cột canonical (xem trên)
File template cũ vẫn còn sau khi cập nhật	`cpt init --dry-run` để xem file cũ nào sẽ bị dọn, rồi `cpt init`
`init` vừa lấy mất file bạn còn cần	Nó nằm trong `~/.claude/.cpt-trash/` — chuyển ngược ra. Muốn tắt hẳn: `cpt init --no-deletions`
Muốn cài lại sạch	`cpt uninstall --force` rồi `cpt init`. Nếu `uninstall` báo thiếu manifest, chạy `cpt init` trước để tạo lại

05 Xem thêm

Quickstart — cài đặt và lệnh đầu tiên.
Lệnh /cpt: — lệnh gõ bên trong Claude Code.
Catalog · Lập trình · Catalog · Công cụ — 63 lệnh chuyên đề.