Công cụ CLI

CLI specdown mang lại workflow kiểu Git ngay trong terminal: đọc, chỉnh sửa, đồng bộ thư mục local với SpecDown, và upload ảnh để chèn vào tài liệu.

Cài đặt

npm (khuyên dùng)

npm install -g specdown-cli

npx (không cần cài)

npx specdown-cli --help

Xác thực

Đăng nhập

specdown login

Nhập email và mật khẩu. Session token được lưu tại ~/.specdown/config.json.

Đăng xuất

specdown logout

Kiểm tra user hiện tại

specdown whoami
# → user@example.com
# → ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# → Project: my-api-docs (my-api-docs)

Quản lý dự án

Liệt kê dự án

specdown projects
# * my-api-docs   (active)
#   team-handbook
#   mobile-spec

Chuyển dự án active

specdown use my-api-docs

Dự án active được dùng mặc định cho lệnh file đơn và upload ảnh.

Link một thư mục local với project

# Link thư mục hiện tại
specdown link my-api-docs

# Link thư mục khác
specdown link my-api-docs --dir ./docs

# Chỉ sync một subtree trên remote
specdown link my-api-docs --prefix /guides

Lệnh này tạo .specdown/project.json trong thư mục đã chọn. File đó lưu project, remote prefix, và các thiết lập sync cho workflow kiểu Git.

Gỡ link thư mục

specdown unlink
specdown unlink --dir ./docs

Đồng bộ thư mục đã link

Sau khi link, CLI coi thư mục local như working copy của project SpecDown. Nó lưu snapshot lần sync gần nhất tại .specdown/sync-state.json để phân biệt thay đổi local, thay đổi remote, và conflict.

Xem trạng thái sync

specdown status
specdown status --dir ./docs

Xem trước kế hoạch thay đổi

specdown diff
specdown diff --dir ./docs

diff cho biết file nào sẽ được push, pull, tạo mới, xóa, hoặc bị chặn vì conflict trước khi bạn ghi đè dữ liệu thật.

Chạy sync hai chiều

# Áp các thay đổi không conflict theo cả hai chiều
specdown sync

# Bật continuous sync cho thư mục đã link
specdown sync --watch --yes

# Vẫn sync phần không conflict khi đang có conflict
specdown sync --force --yes

sync là lệnh hai chiều, nằm giữa push và pull. Nó áp các thay đổi local và remote không conflict trong một lần chạy. Ở watch mode, CLI debounce nhiều file event và không bao giờ chạy chồng hai vòng sync cùng lúc.

Push thư mục đã link

# Push sau khi xác nhận
specdown push

# Bỏ qua prompt để chạy CI/automation
specdown push --yes

# Ghi đè remote khi có conflict
specdown push --force

# Dùng thư mục link khác
specdown push --dir ./docs

Pull thư mục đã link

# Kéo thay đổi từ SpecDown về local
specdown pull

# Bỏ qua prompt
specdown pull --yes

# Ghi đè local khi muốn remote thắng
specdown pull --force

Thao tác tài liệu đơn lẻ

Liệt kê tài liệu

specdown ls
# my-api-docs
# ├── 📁 guides
# │   ├── 📄 authentication   guides/authentication
# │   └── 📄 endpoints        guides/endpoints
# └── 📄 changelog            changelog

Đọc tài liệu

# Toàn bộ tài liệu
specdown read guides/authentication

# Chỉ dòng 10-25
specdown read guides/authentication --from 10 --to 25

# Kèm số dòng
specdown read guides/authentication -n

# Pipe sang công cụ khác
specdown read changelog | grep "v2"

read in raw Markdown ra terminal. Dùng --from và --to khi bạn chỉ muốn nhét một đoạn ngắn vào prompt AI hoặc shell pipeline.

Push một file cục bộ

# Upload file cục bộ lên đường dẫn doc
specdown push ./README.md changelog

# Nếu doc chưa tồn tại, sẽ được tạo
specdown push ./auth-spec.md guides/authentication

Pull một tài liệu

# Tải xuống file
specdown pull guides/authentication ./auth.md

# In ra stdout
specdown pull changelog

Tạo tài liệu hoặc thư mục mới

# Tài liệu mới
specdown new "OAuth Flow"

# Tài liệu trong thư mục
specdown new "OAuth Flow" --parent guides

# Thư mục mới
specdown new "API Reference" --folder

Xóa tài liệu

# Có xác nhận
specdown rm guides/old-api

# Bỏ qua xác nhận
specdown rm guides/old-api --force

Upload ảnh

# Upload ảnh và in ra markdown link
specdown image ./architecture.png

# Associate ảnh với một tài liệu cụ thể
specdown image ./diagram.png --doc /guides/authentication.md

Lệnh này upload ảnh local lên SpecDown và in ra Markdown image link để bạn paste vào tài liệu.

Tệp đính kèm của project

# Upload file project. HTML/HTM thành tài liệu editable; file khác in embed reference
specdown file upload ./assets/login-flow.png /assets/login-flow.png
specdown file upload ./pages/landing.html /pages/landing.html

# Liệt kê attachment trong project
specdown file list
specdown file list /assets

# Đọc file dạng text hoặc in metadata/download info cho file binary
specdown file read /assets/config.json
specdown file read /assets/login-flow.png ./login-flow.png

Dùng file upload cho PDF, ảnh, video, CSV, và các file dạng text cần xuất hiện trong file tree. File HTML/HTM sẽ thành tài liệu có thể chỉnh sửa; các file khác thành attachment chỉ preview và Markdown có thể nhúng bằng [@/path/to/file].

Comments

Đọc các thread comment của một tài liệu, bao gồm cả các comment được anchor trực tiếp từ share view. Comment ẩn danh sẽ hiển thị là Anonymous; comment của user đã đăng nhập hiển thị tên thật.

# Liệt kê toàn bộ thread + reply trên một tài liệu
specdown comments list guides/authentication

# Ẩn các thread đã resolved
specdown comments list guides/authentication --unresolved

# Output JSON cho scripting / AI
specdown comments list guides/authentication --json

Output gom các reply theo thread cha và in phần văn bản đã được bôi đen (selection text mà comment đang anchor vào) phía trên mỗi thread.

AI Skills

SpecDown đóng gói sẵn một bộ skill cho AI assistant (chuẩn Anthropic SKILL.md) để mọi agent — Claude Code, Cursor, Codex, OpenCode, Antigravity, hay tool .agents/chung — đều nhận được context và workflow riêng cho SpecDown mà bạn không phải viết prompt thủ công.

# Cài cho AI tool đang có trong thư mục hiện tại (hỏi tương tác)
specdown install skills

# Không tương tác: chọn target trực tiếp
specdown install skills --for claude
specdown install skills --for cursor
specdown install skills --for codex

# Xem skill nào đang có sẵn (bundled vs cache)
specdown skills status

Mỗi lần chạy, installer refresh ~/.specdown/skills/ từ phiên bản đi kèm CLI, rồi copy vào folder mà AI tool đó kỳ vọng (.claude/skills/, .cursor/rules/ dạng .mdc, .codex/skills/, …). Sau khi npm i -g specdown-cli@latest bạn chạy lại lệnh này là có skill mới.

Tìm kiếm

# Tìm trong tất cả tài liệu của dự án
specdown search "rate limiting"

# Chỉ tìm trong file cụ thể
specdown search "TODO" --files "guides/api,changelog"

# Thêm dòng ngữ cảnh quanh kết quả
specdown search "authentication" -C 5

Kết quả được highlight trong terminal với các dòng ngữ cảnh xung quanh.

Tham chiếu lệnh

Dùng trong CI/CD

Đặt credential qua biến môi trường để tránh nhắc nhập tương tác:

# Ví dụ GitHub Actions
- name: Sync docs to SpecDown
  env:
    SPECDOWN_EMAIL: ${{ secrets.SPECDOWN_EMAIL }}
    SPECDOWN_PASSWORD: ${{ secrets.SPECDOWN_PASSWORD }}
  run: |
    npx specdown-cli login
    npx specdown-cli use my-api-docs
    npx specdown-cli link my-api-docs --dir ./docs
    npx specdown-cli sync --dir ./docs --yes

Use Cases & Mẹo

Để AI vận hành spec Markdown của bạn

CLI được thiết kế AI-friendly. AI agent có thể gọi trực tiếp từ shell, giữ một working copy local, đọc spec, upload ảnh, rồi sync ngược lên SpecDown.

# Workflow của AI agent
specdown link my-api-docs --dir ./specs
specdown status --dir ./specs
specdown read api/authentication
specdown image ./screenshots/login.png --doc /api/authentication.md
specdown sync --dir ./specs --yes

Xem trước sync trước khi force

specdown status --dir ./docs
specdown diff --dir ./docs

# Chỉ áp dụng sau khi đã review kế hoạch
specdown sync --dir ./docs --yes
# hoặc
specdown pull --dir ./docs --force --yes

Đây là flow an toàn nhất khi local edit và remote edit có thể đã diverge.

Thêm screenshot và diagram từ terminal

specdown image ./artifacts/sequence-diagram.png --doc /guides/authentication.md
# -> ![sequence-diagram.png](/r/your-project/...png)

CLI sẽ trả Markdown link để bạn paste vào tài liệu, dùng trong PR comment, hoặc feed lại vào AI-generated update.

Chỉnh sửa local rồi publish lên SpecDown

# Chỉnh sửa trong editor local
code ./docs

# Xem thay đổi sẽ sync
specdown diff --dir ./docs

# Giữ local và remote cùng nhịp
specdown sync --dir ./docs

Giữ local mirror luôn nóng khi đang làm việc

# Chạy một watch loop cho mỗi linked folder
specdown sync --dir ./docs --watch --yes

Rất hợp khi AI agent hoặc editor local đang sửa Markdown, trong lúc teammate vẫn edit qua web app. Các thay đổi không conflict sẽ tự sync; conflict sẽ được giữ lại để review.

Kéo một tài liệu sang công cụ khác

# Tải doc về file local
specdown pull /api/overview.md ./README.md

# Chỉ pipe một đoạn ngắn sang lệnh khác
specdown read /api/overview.md --from 20 --to 60 | sed -n '1,12p'

Mẹo & Thủ thuật

• Dùng linked folder cho workflow dài ngày: link, status, diff, rồi push hoặc pull theo hướng bạn muốn.
• Dùng sync cho mirror hằng ngày: lệnh này áp các thay đổi không conflict từ cả local và remote trong một lần chạy.
• Dùng file mode cho script nhỏ: giữ push <file> <doc-path> và pull <doc-path> [out-file] cho các bước automation đơn giản.
• Review trước khi overwrite: luôn chạy diff trước. Chỉ dùng --force khi bạn thật sự muốn một phía thắng conflict.
• Watch mode thiên về automation: chạy specdown sync --watch --yes để watcher không bị dừng vì prompt lặp lại.
• Dùng khoảng dòng: --from và --to giúp prompt AI gọn hơn và chính xác hơn.
• Gắn ảnh với đúng doc: dùng specdown image --doc /path nếu bạn muốn asset gắn với một tài liệu cụ thể.