CLI

Các lệnh terminal openspec.

Các lệnh

Thiết lập

Lệnh	Chức năng
openspec init	Khởi tạo OpenSpec trong một dự án.
openspec update	Cập nhật các tệp hướng dẫn đã cài đặt của OpenSpec.
openspec config	Xem và thay đổi cấu hình toàn cục.

Thay đổi và đặc tả

Lệnh	Chức năng
openspec list	Liệt kê các thay đổi, hoặc đặc tả với --specs.
openspec show	In một thay đổi hoặc đặc tả, dưới dạng markdown hoặc JSON.
openspec view	Bảng điều khiển một màn hình về đặc tả và thay đổi.
openspec validate	Kiểm tra các thay đổi và đặc tả để phát hiện vấn đề cấu trúc.
openspec archive	Di chuyển một thay đổi đã hoàn tất vào kho lưu trữ và cập nhật các đặc tả chính.

Quy trình làm việc và schema

Agent của bạn chạy hầu hết các lệnh này trong quy trình làm việc.

Lệnh	Chức năng
openspec new	Tạo một thư mục thay đổi mới.
openspec status	Trạng thái hoàn thành artifact cho một hoặc mọi thay đổi đang hoạt động.
openspec instructions	Hướng dẫn tạo artifact, áp dụng hoặc lưu trữ.
openspec templates	Đường dẫn template đã được xác định cho artifact của một schema.
openspec schemas	Liệt kê các schema quy trình làm việc có sẵn.
openspec schema	Kiểm tra, fork hoặc tạo schema (thử nghiệm).

Đa repo (beta)

Lệnh	Chức năng
openspec store	Tạo và quản lý store: các repo OpenSpec độc lập được đăng ký trên máy của bạn.
openspec doctor	Báo cáo tình trạng mối quan hệ của gốc OpenSpec đã được xác định.
openspec context	In ngữ cảnh làm việc cho gốc OpenSpec đã được xác định.
openspec workset	Tổ hợp, duy trì và mở các chế độ xem làm việc cá nhân.

Tiện ích

Lệnh	Chức năng
openspec version	Báo cáo phiên bản đã cài đặt và tùy chọn kiểm tra bản cập nhật.
openspec install	Cài đặt openspec độc lập, chạy mà không cần Node.js.
openspec feedback	Gửi phản hồi về OpenSpec.
openspec completion	Cài đặt hoặc tạo tính năng tự hoàn thành lệnh của shell.

Không còn được khuyến nghị

Lệnh	Chức năng
openspec change	Dạng danh từ của show, list và validate cho các thay đổi. CLI sẽ cảnh báo và chỉ đến các lệnh có động từ đứng đầu.
openspec spec	Dạng danh từ của show, list và validate cho đặc tả, với cùng cảnh báo đó.

Mọi lệnh đều nhận -h, --help. Lệnh openspec đứng riêng cũng nhận:

• -V, --version: in phiên bản CLI.
• --no-color: tắt đầu ra có màu.## openspec init

Khởi tạo OpenSpec trong một dự án.

openspec init                        # thư mục hiện tại, trình chọn công cụ tương tác
openspec init --tools claude,cursor  # thiết lập các công cụ cụ thể, không nhắc
openspec init --tools none           # chỉ cấu trúc openspec/, không có tệp công cụ

Nếu không có --tools, init sẽ nhắc bạn chọn công cụ trong terminal tương tác. Khi không ở trong terminal tương tác, nó sẽ thiết lập các công cụ mà nó phát hiện được trong dự án. Nếu không phát hiện được công cụ nào, nó thoát với mã 1 và liệt kê các id hợp lệ.

Kho lưu trữ chỉ có store

Khi openspec/config.yaml chứa một dòng store: và kho lưu trữ không có spec hoặc thay đổi cục bộ, hãy chạy init từ thư mục gốc của kho lưu trữ:

# cài đặt các tệp tích hợp Claude Code trong kho lưu trữ mã
openspec init --tools claude

• Tệp tích hợp: được ghi vào kho lưu trữ mã.
• openspec/config.yaml: được giữ nguyên từng byte.
• openspec/specs/ và openspec/changes/: không được tạo trong kho lưu trữ mã.

Chạy init từ một thư mục con sẽ thoát với mã 1 và yêu cầu bạn chạy từ thư mục gốc của kho lưu trữ. --language cũng thoát với mã 1 vì ngôn ngữ thuộc về cấu hình của store bên ngoài. Hãy chạy init ở thư mục gốc của store hoặc chỉnh sửa trực tiếp cấu hình đó.

Đối số

Đối số	Mô tả
path	Thư mục dự án cần khởi tạo. Mặc định: thư mục hiện tại. Được tạo nếu chưa có.

Tùy chọn

Cờ	Tác dụng
--tools <tools>	Các id công cụ phân tách bằng dấu phẩy, all, hoặc none. Bỏ qua trình chọn. Các id được liệt kê trong Công cụ được hỗ trợ.
--language <language>	Thêm một chỉ dẫn ngôn ngữ vào cấu hình dự án mới. Bị từ chối khi dòng store: của kho lưu trữ trỏ đến một store bên ngoài.
--force	Xóa các tệp từ bố cục OpenSpec cũ mà không hỏi. Các lần chạy tương tác sẽ xác nhận việc dọn dẹp trước.
--profile <profile>	Ghi đè profile cấu hình toàn cục cho lần chạy này: core (bộ luồng công việc chuẩn) hoặc custom (các luồng công việc được lưu trong cấu hình toàn cục).
--no-animation	Hiển thị màn hình chào tĩnh thay vì màn hình có hiệu ứng động.

Đầu ra

Mỗi công cụ được chọn sẽ nhận các skill và lệnh của OpenSpec trong thư mục riêng của nó:

▌ OpenSpec structure created
✔ Setup complete for Claude Code

OpenSpec Setup Complete

Created: Claude Code
6 skills and 6 commands in .claude/
Config: openspec/config.yaml (schema: spec-driven)

Getting started:
  Start your first change: /opsx:propose "your idea"

Restart your IDE for the new commands to take effect.

--tools none chỉ tạo openspec/config.yaml. Trên một dự án đã được khởi tạo, init sẽ ghi lại các tệp đã cài đặt tại chỗ và bản tóm tắt hiển thị Refreshed: Claude Code cùng Config: openspec/config.yaml (exists).

Mã thoát

• 0: thiết lập hoàn tất.
• 1: giá trị --tools hoặc --profile không hợp lệ, một lần chạy không tương tác mà không phát hiện công cụ nào và không có --tools, hoặc một lời gọi store-only không hợp lệ.

openspec update

Cập nhật các tệp chỉ dẫn đã cài đặt của OpenSpec.

openspec update             # làm mới các công cụ có tệp cũ hơn CLI
openspec update --force     # ghi lại các tệp ngay cả khi chúng đã mới
openspec update --dry-run   # liệt kê những gì bản cập nhật sẽ thay đổi, và không thay đổi gì

update tìm các công cụ mà init đã cấu hình và so sánh các tệp được tạo của chúng với phiên bản của CLI. Khi có bản phát hành OpenSpec mới hơn, trước tiên nó sẽ đề xuất nâng cấp CLI, sau đó chạy lại với phiên bản đã nâng cấp. Đặt OPENSPEC_NO_UPDATE_CHECK=1 để bỏ qua kiểm tra.

Đối số

Đối số	Mô tả
path	Thư mục dự án cần cập nhật. Mặc định: thư mục hiện tại.

Tùy chọn

Cờ	Tác dụng
--force	Ghi lại các tệp của mọi công cụ đã cấu hình ngay cả khi chúng đã mới.
--dry-run	Báo cáo mọi tệp mà bản cập nhật sẽ thêm, thay đổi hoặc xóa, và không ghi gì. Không kiểm tra nâng cấp CLI, không nhắc. Kết hợp với --force để xem trước bản cập nhật bắt buộc.
--json	Với --dry-run, in kế hoạch dưới dạng JSON. Nếu không có --dry-run, lệnh thoát với mã 1.

Xem trước bản cập nhật

--dry-run lập kế hoạch cho bản cập nhật mà một lần chạy không tương tác sẽ thực hiện: cùng luồng mã, với mọi thao tác ghi và xóa được ghi nhận thay vì được thực hiện. Mọi tệp mà bản cập nhật thực sẽ chạm tới đều được liệt kê, bao gồm:

• di chuyển các tệp OpenSpec ra khỏi thư mục cũ của một công cụ (.kimi/ sang .kimi-code/, .windsurf/ sang .devin/, .codex/ và .agent/ sang .agents/);
• lưu cấu hình toàn cục khi một bản cài đặt từ trước khi có profile nhận được cấu hình đó;
• đồng bộ hóa các tệp agent đám mây của GitHub Copilot;
• với --force, thiết lập các công cụ chỉ được tìm thấy trong các artifact cũ và dọn dẹp các artifact đó, bao gồm cả các prompt Codex toàn cục đã ngừng dùng.

openspec update --dry-run

2 file(s) would change:
  update  .claude/skills/openspec-propose/SKILL.md  (claude)
  add     ~/.config/openspec/config.json  (openspec)

--dry-run --json in cùng kế hoạch đó dưới dạng một tài liệu JSON:

{
  "changes": [
    { "path": ".claude/skills/openspec-propose/SKILL.md", "action": "update", "tool": "claude" },
    { "path": "~/.config/openspec/config.json", "action": "add", "tool": "openspec" }
  ],
  "notes": [],
  "failures": []
}

Trường	Nội dung
changes[].path	Đường dẫn tương đối so với dự án. Một tệp nằm ngoài dự án, chẳng hạn skill toàn cục hoặc cấu hình toàn cục, được hiển thị từ thư mục home của bạn dưới dạng ~/..., hoặc dưới dạng đường dẫn tuyệt đối khi nó cũng nằm ngoài thư mục home.
changes[].action	add, update, hoặc delete. Một tệp có nội dung byte mới trùng với nội dung cũ sẽ không được liệt kê.
changes[].tool	Công cụ đã cấu hình mà tệp thuộc về, chẳng hạn claude. Các tệp thuộc về chính OpenSpec thay vì một công cụ, gồm cấu hình toàn cục và dọn dẹp artifact cũ, là openspec.
notes[]	{ code, message } cho một bước mà người dùng terminal sẽ được hỏi. legacy-tool-directories: một thao tác di chuyển mà lần chạy tương tác sẽ hỏi trước; changes liệt kê thao tác đó như đã thực hiện. legacy-artifacts: đã tìm thấy các tệp từ bố cục cũ của OpenSpec, chẳng hạn lệnh slash openspec-proposal.md hoặc các khối đánh dấu OpenSpec trong AGENTS.md. Nếu không có --force, bản cập nhật không tương tác sẽ giữ nguyên chúng, nên changes cũng vậy; --dry-run --force liệt kê việc dọn dẹp chúng. Trống đối với một lần làm mới thông thường.
failures[]	{ tool, error } cho mỗi công cụ mà bản cập nhật thực sẽ thất bại, bao gồm cả thao tác ghi không thể thực hiện: một thư mục ở vị trí đáng lẽ là tệp, một tệp ở vị trí đáng lẽ là thư mục, hoặc một tệp hay thư mục không có quyền ghi. Đối với công cụ đó, changes dừng tại nơi bản cập nhật thực sẽ dừng; các công cụ khác vẫn được lập kế hoạch. Những lỗi mà ổ đĩa chỉ báo khi đang ghi, chẳng hạn hết dung lượng, không thể dự đoán trước.

Một lỗi trước khi lập kế hoạch, chẳng hạn không có thư mục OpenSpec, vẫn in ra đúng một tài liệu JSON: kế hoạch trống cộng với mảng status có severity, code (update_error) và message. Mã thoát là 1.

Đầu ra

Khi các tệp của mọi công cụ khớp với phiên bản CLI:

✓ All 1 tool(s) up to date (v1.7.0)
  Tools: claude

Use --force to refresh files anyway.

Khi các tệp của một công cụ đến từ CLI cũ hơn (hoặc với --force, trường hợp sẽ in Force updating 1 tool(s): claude thay thế):

Updating 1 tool(s): claude (1.6.0 → 1.7.0)

✔ Updated Claude Code

✓ Updated: Claude Code (v1.7.0)
Tools: Claude Code

Restart your IDE for changes to take effect.

Trong một thư mục không có OpenSpec, update từ chối:

✖ Error: No OpenSpec directory found. Run 'openspec init' first.

Mã thoát

• 0: các tệp đã được cập nhật, hoặc mọi thứ đã mới.
• 1: không có thư mục OpenSpec tại đường dẫn, hoặc bản cập nhật thất bại.

openspec config

Xem và thay đổi cấu hình toàn cục.

openspec config list                  # xem cài đặt hiện tại
openspec config set delivery skills   # thay đổi một giá trị
openspec config profile               # trình chọn luồng công việc tương tác

Lệnh con	Tác dụng
path	In vị trí tệp cấu hình.
list	Hiển thị tất cả cài đặt hiện tại.
get <key>	In một giá trị, dạng thô và có thể dùng trong script.
set <key> <value>	Đặt một giá trị, có ép kiểu.
unset <key>	Xóa một khóa để áp dụng giá trị mặc định.
reset	Đặt lại toàn bộ cấu hình về mặc định.
edit	Mở tệp cấu hình trong $EDITOR.
profile [preset]	Cấu hình chế độ delivery và các luồng công việc.

Cấu hình có phạm vi toàn cục trên máy của bạn, được lưu dưới dạng JSON tại nơi mà config path trỏ đến: $XDG_CONFIG_HOME/openspec/config.json nếu được đặt, nếu không thì ~/.config/openspec/config.json (macOS, Linux) hoặc %APPDATA%\openspec\config.json (Windows). Mọi lệnh con đều chấp nhận --scope <scope>, nhưng hiện tại chỉ có global hoạt động. Mọi scope khác đều thoát với mã 1 kèm Error: Project-local config is not yet implemented.

openspec config path

openspec config path

/Users/you/.config/openspec/config.json

openspec config list

openspec config list          # cài đặt dễ đọc kèm tóm tắt profile
openspec config list --json   # cấu hình thô dưới dạng JSON

Tùy chọn

Cờ	Tác dụng
--json	In đối tượng cấu hình dưới dạng JSON.

Đầu ra

Mỗi cài đặt, sau đó là tóm tắt profile đánh dấu các giá trị là được đặt rõ ràng hoặc mặc định:

featureFlags: {}
profile: core
delivery: both

Profile settings:
  profile: core (default)
  delivery: both (default)
  workflows: propose, explore, apply, update, sync, archive (from core profile)

openspec config get

openspec config get delivery

Đối số

Đối số	Mô tả
key	Khóa cần đọc. Dấu chấm truy cập các giá trị lồng nhau (featureFlags.workspaces).

Đầu ra

Giá trị nguyên, sẵn sàng cho script. Các đối tượng được in dưới dạng JSON compact:

both

Mã thoát

• 0: giá trị đã được in.
• 1: khóa không có giá trị, và không in gì.

openspec config set

openspec config set delivery skills
openspec config set featureFlags.workspaces true

Đối số

Đối số	Mô tả
key	Khóa cần ghi, dùng dấu chấm cho các giá trị lồng nhau.
value	Giá trị mới. true/false trở thành boolean, chuỗi số trở thành số.

Tùy chọn

Cờ	Tác dụng
--string	Lưu giá trị dưới dạng chuỗi, bỏ qua ép kiểu.
--allow-unknown	Cho phép các khóa mà schema không biết.

Đầu ra

Set featureFlags.workspaces = true

Các khóa không xác định và giá trị không hợp lệ sẽ thất bại với mã thoát 1 trước khi bất kỳ nội dung nào được lưu:

Error: Invalid configuration key "bogus.key". Unknown top-level key "bogus".
Use "openspec config list" to see available keys.
Pass --allow-unknown to bypass this check.

Error: Invalid configuration - delivery: Invalid option: expected one of "both"|"skills"|"commands"

Nếu tệp cấu hình tồn tại nhưng không chứa một đối tượng JSON, cho dù vì nó hoàn toàn không phải là JSON hợp lệ hay vì gốc của nó là một thứ khác như null hoặc mảng, thì config set, config unset và config profile sẽ thoát với mã 1 và giữ nguyên tệp. Hãy sửa bằng openspec config edit, hoặc thay thế bằng openspec config reset --all:

Error: /home/you/.config/openspec/config.json could not be parsed, so it was left unchanged.
Fix it with "openspec config edit", or reset it with "openspec config reset --all".

Cho đến khi được sửa, telemetry và kiểm tra cập nhật vẫn tắt.

openspec config unset

openspec config unset delivery

Xóa khóa để giá trị mặc định được áp dụng lại. Các khóa có giá trị mặc định tích hợp luôn được xem là đã đặt, nên lệnh này báo thành công ngay cả khi bạn chưa từng đặt chúng:

Unset delivery (reverted to default)

Một khóa hoàn toàn không có giá trị sẽ in Key "featureFlags.nothere" was not set. Cả hai trường hợp đều thoát với mã 0. Nếu tệp cấu hình không thể phân tích, lệnh thoát với mã 1, tương tự như config set.

openspec config reset

openspec config reset --all      # yêu cầu xác nhận
openspec config reset --all -y   # không nhắc

Tùy chọn

Cờ	Tác dụng
--all	Bắt buộc. Đặt lại mọi thứ.
-y, --yes	Bỏ qua nhắc xác nhận.

Đầu ra

Configuration reset to defaults

Nếu không có --all, lệnh thoát với mã 1 và in dòng hướng dẫn sử dụng.

Mã thoát

• 0: đã đặt lại xong, hoặc bạn trả lời không tại nhắc.
• 1: thiếu --all.
• 130: nhắc bị hủy bằng Ctrl-C.

openspec config edit

openspec config edit

Mở tệp cấu hình trong $EDITOR (dự phòng $VISUAL), tạo nó với các giá trị mặc định trước nếu chưa có. Khi trình soạn thảo đóng, tệp được xác thực. JSON không hợp lệ hoặc cấu hình không hợp lệ sẽ thoát với mã 1.

Giá trị editor có thể kèm đối số và đường dẫn được trích dẫn, ví dụ code --wait hoặc "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Nó được tách thành các từ mà không qua shell, nên $VAR, ~ và ; được truyền nguyên văn. Một trình soạn thảo không thể khởi động hoặc thoát khác 0 sẽ in lỗi một dòng và thoát với mã 1.

Khi chưa cấu hình editor, lệnh thoát với mã 1:

Error: No editor configured
Set the EDITOR or VISUAL environment variable to your preferred editor
Example: export EDITOR=vim

openspec config profile

openspec config profile        # trình chọn tương tác (cần terminal)
openspec config profile core   # áp dụng preset core trực tiếp

Đối số

Đối số	Mô tả
preset	Tên preset tùy chọn. Hiện chỉ có core. Nó chọn các luồng công việc core và giữ cài đặt delivery của bạn.

Khi không có preset, một trình chọn tương tác hiển thị delivery và các luồng công việc hiện tại của bạn, cho phép bạn thay đổi một hoặc cả hai (delivery: both, skills only, hoặc commands only; workflows: danh sách checkbox), in ra sự khác biệt, và bên trong một dự án OpenSpec sẽ đề xuất chạy openspec update giúp bạn. Nếu không ở trong terminal, lệnh thoát với mã 1:

Interactive mode required. Use `openspec config profile core` or set config via environment/flags.

Đầu ra

Cấu hình đã thay đổi sẽ không áp dụng cho các dự án cho đến khi chúng được cập nhật:

Config updated. Run `openspec update` in your projects to apply.

Mã thoát

• 0: profile đã được lưu, hoặc bạn giữ nguyên cài đặt hiện tại.
• 1: preset không xác định, không có terminal, hoặc lệnh openspec update được đề xuất thất bại.
• 130: trình chọn bị hủy bằng Ctrl-C.

openspec list

Liệt kê các thay đổi hoặc spec với --specs.

openspec list                    # các thay đổi đang hoạt động, được sửa đổi gần đây nhất xếp trước
openspec list --archived         # các thay đổi đã lưu trữ
openspec list --all              # các thay đổi đang hoạt động và đã lưu trữ
openspec list --specs            # các spec kèm số lượng yêu cầu
openspec list --json             # dạng máy đọc được, bao gồm root đã phân giải

Các dòng được lấy từ openspec/changes/ và openspec/specs/ dưới root đã phân giải. Danh sách thay đổi mặc định bỏ qua openspec/changes/archive/.

Tùy chọn

Cờ	Tác dụng
--specs	Liệt kê spec thay vì thay đổi.
--changes	Liệt kê thay đổi. Đây là mặc định.
--archived	Chỉ liệt kê các thay đổi đã lưu trữ. Không thể kết hợp với --specs.
--all	Liệt kê các thay đổi đang hoạt động và đã lưu trữ. Không thể kết hợp với --specs. Ưu tiên hơn --archived.
--sort <order>	recent (sửa đổi gần đây nhất trước tiên) hoặc name. Mặc định: recent. Spec luôn được sắp xếp theo tên.
--json	In JSON thay vì bảng.
--store <id>	Dùng một store đã đăng ký làm root của OpenSpec thay vì dự án hiện tại.

Đầu ra

Mỗi thay đổi một dòng: tên, trạng thái tác vụ, lần sửa đổi gần đây nhất. Cột trạng thái hiển thị No tasks, 2/5 tasks hoặc ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all nhóm các thay đổi đang hoạt động và đã lưu trữ dưới các tiêu đề riêng. Mỗi nhóm sử dụng thứ tự sắp xếp đã chọn:

Changes:
  add-rate-limit     No tasks      just now

Archived Changes:
  2026-08-10-add-login     ✓ Complete    2d ago

Specs:
  api     requirements 1

--json thêm số lượng tác vụ và status với giá trị no-tasks, in-progress hoặc complete:

{
  "changes": [
    {
      "name": "add-rate-limit",
      "completedTasks": 0,
      "totalTasks": 0,
      "lastModified": "2026-08-11T13:44:40.171Z",
      "status": "no-tasks"
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Với --archived hoặc --all, mọi đối tượng thay đổi đều bao gồm một giá trị boolean archived. Mảng kết hợp sử dụng thứ tự sắp xếp đã chọn. Một thay đổi đã lưu trữ vẫn có thể có trạng thái in-progress khi tệp tác vụ được theo dõi của nó còn các tác vụ chưa được đánh dấu hoàn thành. Nếu không có một trong hai cờ này, cấu trúc JSON vẫn giữ nguyên.

Danh sách trống sẽ in No active changes found., No archived changes found., No changes found. hoặc No specs found. và vẫn thoát với mã 0.

Một thay đổi là một thư mục nằm trực tiếp dưới openspec/changes/. Khác với spec, thay đổi không thể được lồng trong một thư mục namespace. Một thư mục như changes/mobile/ chỉ bọc một thay đổi (changes/mobile/refresh-token/) sẽ được liệt kê với trạng thái not a change, theo sau là cảnh báo nêu tên các thư mục lồng nhau. --json đánh dấu mục đó bằng một mảng nested và thêm một mảng warnings ở cấp cao nhất. show, status, validate và archive từ chối thư mục đó với cùng thông báo. Để khắc phục, hãy di chuyển thay đổi lên và gộp namespace vào tên của nó:

mv openspec/changes/mobile/refresh-token openspec/changes/mobile-refresh-token
rmdir openspec/changes/mobile

Mã thoát

• 0: đã in danh sách, kể cả khi trống.
• 1: không tìm thấy root OpenSpec (ngoài dự án, không có --store).

openspec show

In một thay đổi hoặc spec, dưới dạng markdown hoặc JSON.

openspec show add-rate-limit              # thay đổi: in proposal.md
openspec show add-rate-limit --diff       # thay đổi: nối thêm các diff yêu cầu
openspec show api                         # spec: in spec.md
openspec show api --json --no-scenarios   # spec JSON không có nội dung kịch bản

Khi không có tên, show sẽ hỏi chọn thay đổi hay spec, sau đó liệt kê các mục để chọn. Ngoài terminal tương tác, lệnh thoát với mã 1 và thay vào đó in các dạng trực tiếp.

Đối số

Đối số	Ý nghĩa
item-name	Thay đổi hoặc spec cần hiển thị, theo tên thư mục (add-rate-limit, api).

Tùy chọn

Cờ	Tác dụng
--json	In JSON có cấu trúc thay vì markdown thô.
--type <change|spec>	Chọn loại khi một thay đổi và một spec trùng tên.
--no-interactive	Không bao giờ nhắc nhập: tên bị thiếu sẽ trở thành lỗi.
--deltas-only	JSON, thay đổi: giới hạn đầu ra chỉ còn các delta. JSON của thay đổi vốn đã chỉ chứa delta, nên đầu ra khớp với --json thông thường.
--requirements-only	Bí danh đã ngừng dùng của --deltas-only. Cảnh báo trên stderr.
--diff	Thay đổi: nối thêm các diff delta theo từng yêu cầu. Bị bỏ qua kèm cảnh báo đối với spec.
--requirements	JSON, spec: giữ văn bản yêu cầu, làm trống các mảng scenarios.
--no-scenarios	JSON, spec: đầu ra giống như --requirements.
-r, --requirement <id>	JSON, spec: xuất một yêu cầu theo vị trí bắt đầu từ 1. Không thể kết hợp với --requirements.
--store <id>	Dùng một store đã đăng ký làm root của OpenSpec thay vì dự án hiện tại.

Các cờ không áp dụng cho loại đã phân giải sẽ bị bỏ qua kèm cảnh báo trên stderr.

Đầu ra

Chế độ văn bản là truyền thẳng nội dung thô: một thay đổi in proposal.md của nó, một spec in spec.md của nó.

# Add rate limiting
```## Why
Các client chưa xác thực có thể làm cạn kiệt API.

## What Changes
- Thêm giới hạn tốc độ cho từng client vào API công khai.

Đối với một thay đổi, --diff in ra đề xuất trước, sau đó là phần Specifications Changed (diffs). Các yêu cầu ADDED bao gồm toàn bộ nội dung. Các yêu cầu REMOVED giữ lý do và di trú đã viết. Các yêu cầu RENAMED hiển thị FROM và TO. Các yêu cầu MODIFIED hiển thị diff hợp nhất so với yêu cầu chính tương ứng.

Nếu tiêu đề MODIFIED chỉ khớp sau khi gộp chữ hoa/thường hoặc khoảng trắng, đầu ra bao gồm cả diff và cảnh báo rằng việc khớp archive là chính xác. Nếu spec chính hoặc yêu cầu bị thiếu, đầu ra cảnh báo và in toàn bộ khối delta. Khối MODIFIED không có sự khác biệt về văn bản in (no textual changes).

Một thay đổi với --json có dạng delta:

{
  "id": "add-rate-limit",
  "title": "Add rate limiting",
  "deltaCount": 1,
  "deltas": [
    {
      "spec": "api",
      "operation": "ADDED",
      "description": "Add requirement: The API SHALL limit each client to 100 requests per minute.",
      "requirement": {
        "name": "Rate limit",
        "text": "The API SHALL limit each client to 100 requests per minute.",
        "scenarios": [
          {
            "name": "Client exceeds the limit",
            "rawText": "- **WHEN** a client sends its 101st request within a minute\n- **THEN** the API responds 429"
          }
        ]
      },
      ...
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Mỗi yêu cầu mang name của mình, văn bản tiêu đề sau Requirement:. Đây là tên mà archive khớp các mục MODIFIED, REMOVED và RENAMED. Mỗi kịch bản mang name của mình, văn bản tiêu đề sau Scenario:. Một chuỗi # đóng ở bất kỳ tiêu đề nào không thuộc tên.

--json --diff giữ nguyên hình dạng cấp cao này. Một delta MODIFIED nhận thêm chuỗi diff, chuỗi warning, hoặc cả hai. Các thao tác khác không đổi. Chuỗi diff rỗng có nghĩa là các khối chính và delta giống nhau về văn bản.

Một spec với --json liệt kê các yêu cầu với các kịch bản. Yêu cầu và kịch bản mang các trường name giống như JSON thay đổi:

{
  "id": "api",
  "title": "api",
  "overview": "Public HTTP API behavior.",
  "requirementCount": 1,
  "requirements": [
    {
      "name": "Health endpoint",
      "text": "The API SHALL expose a health endpoint.",
      "scenarios": [
        {
          "name": "Health check succeeds",
          "rawText": "- **WHEN** a client requests GET /health\n- **THEN** the API responds 200"
        }
      ]
    }
  ],
  "metadata": {
    "version": "1.0.0",
    "format": "openspec"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Tên không xác định gợi ý các kết quả gần đúng: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Tên khớp cả một thay đổi và một spec sẽ báo lỗi và yêu cầu --type.

Mã thoát

• 0: đã in mục.
• 1: tên không xác định hoặc mơ hồ, không có tên ngoài terminal, chỉ mục -r ngoài phạm vi, --requirements kết hợp với -r, hoặc không thể đọc delta hoặc spec chính cho --diff.

openspec view

In bảng điều khiển một màn hình của spec và thay đổi.

openspec view   # project summary in one screen

view in bảng điều khiển một lần rồi thoát. Nó không đọc phím nhấn. Thay đổi được nhóm theo tiến độ nhiệm vụ: Draft (chưa có nhiệm vụ), Active (đang thực hiện nhiệm vụ, với thanh tiến độ và phần trăm), Completed (mọi nhiệm vụ đã được đánh dấu). Spec liệt kê với số lượng yêu cầu, lớn nhất trước.

Tùy chọn

Cờ	Tác dụng
--store <id>	Sử dụng store đã đăng ký làm gốc OpenSpec thay vì dự án hiện tại.

Đầu ra

OpenSpec Dashboard

════════════════════════════════════════════════════════════
Summary:
  ● Specifications: 1 specs, 1 requirements
  ● Draft Changes: 1
  ● Active Changes: 0 in progress
  ● Completed Changes: 0

Draft Changes
────────────────────────────────────────────────────────────
  ○ add-rate-limit

Specifications
────────────────────────────────────────────────────────────
  ▪ api                            1 requirement

════════════════════════════════════════════════════════════

Use openspec list --changes or openspec list --specs for detailed views

Một dòng tóm tắt Task Progress xuất hiện khi bất kỳ thay đổi nào có nhiệm vụ đang thực hiện.

Mỗi thay đổi đang hoạt động cũng hiển thị trạng thái schema và artifact bên dưới thanh tiến độ nhiệm vụ:

    └─ [spec-driven] proposal✓ specs→ design→ tasks✓

Marker	Trạng thái artifact
✓	Đầu ra tồn tại. Artifact tasks hiện có được coi là hoàn thành ngay cả khi danh sách kiểm tra chưa hoàn thành.
→	Sẵn sàng để tạo.
Không có marker	Bị chặn bởi phụ thuộc còn thiếu.
(skipped)	Thay đổi bỏ qua nó.

Nếu không thể tải workflow, view in cảnh báo và giữ tiến độ nhiệm vụ của thay đổi đó hiển thị. Chạy openspec status --change <name> để kiểm tra workflow riêng biệt. Sau openspec view --store <id>, truyền cùng --store <id> cho status.

Mã thoát

• 0: đã in bảng điều khiển.
• 1: không tìm thấy gốc OpenSpec (ngoài dự án, không có --store).

openspec validate

Kiểm tra thay đổi và spec để tìm vấn đề cấu trúc.

openspec validate add-rate-limit   # one change or spec, by name
openspec validate --all            # every change and spec

Không có tên và không có cờ bulk, validate nhắc bạn chọn mục. Ngoài terminal tương tác, nó thoát 1 và in các cờ bulk thay thế.

Đối số

Đối số	Nó là gì
item-name	Thay đổi hoặc spec để xác thực, theo tên thư mục (add-rate-limit, api).

Tùy chọn

Cờ	Tác dụng
--all	Xác thực mọi thay đổi và spec.
--changes	Xác thực mọi thay đổi.
--specs	Xác thực mọi spec.
--archived	Kiểm tra hoàn thành nhiệm vụ trong các thay đổi đã lưu trữ, mà không xác thực các delta spec đã áp dụng.
--strict	Coi cảnh báo là lỗi.
--type <change|spec>	Chọn loại khi một thay đổi và một spec dùng chung tên.
--json	In báo cáo có cấu trúc thay vì văn bản.
--report <mode>	Đầu ra bulk: full (mặc định) hoặc findings. Yêu cầu phạm vi bulk rõ ràng.
--concurrency <n>	Số xác thực song song tối đa trong các lần chạy bulk. Mặc định: OPENSPEC_CONCURRENCY, nếu không thì 6.
--no-interactive	Không bao giờ nhắc: tên thiếu hoặc mơ hồ trở thành lỗi.
--store <id>	Sử dụng store đã đăng ký làm gốc OpenSpec thay vì dự án hiện tại.

Đầu ra

Các lần chạy bulk in một dòng trạng thái cho mỗi mục, sau đó là các phát hiện, và kết thúc bằng tổng:

✓ change/add-rate-limit
✓ spec/api
Totals: 2 passed, 0 failed (2 items)

Phát hiện về checkbox nhiệm vụ

Tiến độ đếm checkbox và không có gì khác, vì vậy tệp nhiệm vụ được viết dưới dạng gạch đầu dòng thường sẽ được đọc là không có nhiệm vụ: openspec list và openspec status báo cáo không có công việc, và openspec archive không có gì để đánh dấu là chưa hoàn thành. Validate báo cáo WARNING trên mỗi tệp nhiệm vụ được theo dõi liệt kê công việc mà không có checkbox:

⚠ [WARNING] tasks.md: This change counts as 0 tasks: no line in its tracked task files is a checkbox, so "openspec list" and "openspec status" report no work and "openspec archive" has nothing to flag as incomplete. Write each task as "- [ ] 1.1 Description".

Cảnh báo chỉ kích hoạt khi toàn bộ tập theo dõi của thay đổi không có checkbox nào. Một tệp văn bản bên cạnh danh sách kiểm tra thực sự không được báo cáo, và thay đổi đang viết giữ tiến độ ngay khi có một checkbox. --strict biến cảnh báo thành lỗi. Số dòng nằm trong báo cáo --json.

Các khối fenced, nhận xét HTML, YAML front matter và mã thụt lề không được quét, vì vậy mẫu terminal được dán không bao giờ bị nhầm là danh sách nhiệm vụ.

Phát hiện hợp nhất archive

Đối với các thay đổi, validate chạy merge builder của archive đối với các spec chính hiện tại mà không ghi tệp. Nó báo cáo xung đột hợp nhất, chẳng hạn như mục tiêu MODIFIED bị thiếu hoặc yêu cầu ADDED xung đột, dưới dạng INFO:

ℹ [INFO] api/spec.md: Archive would refuse this delta: api MODIFIED failed for header "### Requirement: Rate limiting" - not found

Các phát hiện này xuất hiện ngay cả khi xác thực thành công, trong cả đầu ra văn bản và JSON. INFO không bao giờ thay đổi mã thoát, kể cả dưới --strict: mục tiêu bị thiếu có thể thuộc về thay đổi anh em chưa được lưu trữ. Các delta đã đồng bộ vào spec chính tuân theo các quy tắc hợp nhất hiện có của archive.

Kiểm tra này không chạy xác thực merged-spec sau đó của archive hoặc các kiểm tra nghỉ hưu. Báo cáo sạch không đảm bảo rằng archive sẽ thành công.

Nếu không thể bắt đầu merge preflight, một phát hiện INFO giải thích lý do. Các phát hiện xác thực hiện có và mã thoát vẫn giữ nguyên.

Một mục thất bại liệt kê từng vấn đề và cách sửa:

Change 'add-rate-limit' has issues
✗ [ERROR] api/spec.md: ADDED "Rate limiting" must include at least one scenario
Next steps:
  - Ensure change has deltas in specs/: use headers ## ADDED/MODIFIED/REMOVED/RENAMED Requirements
  - Each requirement MUST include at least one #### Scenario: block
  - Debug parsed deltas: openspec show add-rate-limit --json --deltas-only

--json in một báo cáo cho lần chạy:

{
  "items": [
    {
      "id": "add-rate-limit",
      "type": "change",
      "valid": true,
      "issues": [],
      "durationMs": 2
    }
  ],
  "summary": {
    "totals": {
      "items": 1,
      "passed": 1,
      "failed": 0
    },
    "byType": {
      "change": {
        "items": 1,
        "passed": 1,
        "failed": 0
      }
    }
  },
  "version": "1.0",
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Các mục issues mang level là ERROR, WARNING, hoặc INFO.

Mã thoát

• 0: mọi mục được xác thực đều thành công, bao gồm phạm vi bulk rỗng.
• 1: một mục thất bại, yêu cầu báo cáo không hợp lệ, openspec/config.yaml không thể đọc được hoặc không phải YAML hợp lệ, hoặc lần chạy thất bại (ví dụ tên không xác định hoặc không có gốc OpenSpec). Cấu hình không thể đọc hoặc phân tích dừng lần chạy trước khi bất kỳ mục nào được kiểm tra; với --json nó được báo cáo dưới dạng một mục status duy nhất với mã unreadable_config hoặc unparseable_config.

--report full|findings

Chọn đầu ra cho phạm vi xác thực bulk rõ ràng:

• full: mọi mục. Đây là mặc định. --report full rõ ràng giữ nguyên hình dạng đầu ra hiện có mà không thêm siêu dữ liệu báo cáo.
• findings: chỉ các mục có vấn đề, bao gồm các mục thành công với cảnh báo hoặc thông tin. Mọi mục vẫn được xác thực. Tổng số, hành vi chế độ strict và mã thoát không thay đổi.

openspec validate --all --report findings
openspec validate --archived --report findings --json

Phạm vi

Cờ	Findings report.scope
--all	all
--changes	changes
--specs	specs
--changes --specs, hoặc --all với một trong hai cờ	all
--archived	archived

Cả hai chế độ báo cáo rõ ràng đều từ chối tên mục vị trí, phạm vi bulk bị thiếu, hoặc phạm vi archive và active kết hợp.

Đầu ra văn bản Findings

Đầu ra con người: stdout in Scope: <scope> (<count> items), sau đó là tổng. Không có mục nào có vấn đề:

Scope: all (2 items)
No item findings.
Totals: 2 passed, 0 failed (2 items)

Nhãn mục có vấn đề, nhãn mức độ nghiêm trọng, đường dẫn và thông báo in ra stderr. Các lỗi phạm vi active giữ gợi ý chạy lại Details: sau tổng. Biểu ngữ gốc và đầu ra tiến độ hiện có có thể đứng trước báo cáo.

Đầu ra JSON Findings

--report findings --json in một tài liệu. Ví dụ này có hai mục sạch:

{
  "report": {
    "kind": "validation-findings",
    "version": "1.0",
    "scope": "all",
    "returnedItems": 0,
    "totalItems": 2
  },
  "itemFindings": [],
  "summary": {
    "totals": { "items": 2, "passed": 2, "failed": 0 },
    "byType": {
      "change": { "items": 1, "passed": 1, "failed": 0 },
      "spec": { "items": 1, "passed": 1, "failed": 0 }
    }
  },
  "root": { "path": "/Users/you/projects/my-app", "source": "nearest" }
}

• report.kind and report.version: xác định hình dạng validation-findings, phiên bản 1.0. Không có version hoặc items cấp cao.
• report.returnedItems and report.totalItems: đếm các bản ghi trả về và tất cả các mục được xác thực, tương ứng.
• itemFindings: bản ghi mục đầy đủ có mảng issues không rỗng. Bao gồm các vấn đề ERROR, WARNING, và INFO. Mỗi bản ghi giữ id, type, valid, issues, và durationMs. Các mục đã lưu trữ dùng type: "change".
• summary: tổng số của toàn bộ lần chạy và số lượng theo loại, không phải số lượng của tập con trả về. Phạm vi rỗng có tổng bằng không và thoát 0.
• root: cùng siêu dữ liệu gốc đã chọn như báo cáo đầy đủ.

Bảo toàn bản ghi: các mục trả về giữ thứ tự báo cáo đầy đủ và bất kỳ trường bổ sung nào trên mục hoặc vấn đề. Lọc không viết lại thông báo hoặc vị trí, bao gồm các trường line và column tùy chọn.

Lỗi lệnh: lỗi chọn gốc hoặc lỗi phát hiện mục giữ chẩn đoán status hiện có và thoát 1. Chúng không trả về báo cáo findings hoàn thành hoặc báo cáo rỗng thành công.

Yêu cầu báo cáo không hợp lệ

Cả hai chế độ báo cáo rõ ràng đều từ chối các yêu cầu này trước khi chọn gốc hoặc phát hiện mục:

• Giá trị báo cáo không được hỗ trợ, bao gồm chuỗi rỗng.
• Tên mục vị trí, ngay cả với cờ bulk.
• Không có phạm vi bulk rõ ràng.
• --archived kết hợp với --all, --changes, hoặc --specs.

Trong chế độ JSON, yêu cầu bị từ chối thoát 1 với chỉ một mảng status một phần tử. Nó không có root hoặc tải báo cáo:

openspec validate --all --report bogus --json

{
  "status": [
    {
      "severity": "error",
      "code": "invalid_validation_report_request",
      "message": "Unknown validation report 'bogus'.",
      "fix": "Use --report full|findings with --all, --changes, --specs, or --archived, without an item name. Do not combine archived and active scopes."
    }
  ]
}

Chế độ con người in lỗi ra stderr. --report trần không có giá trị là lỗi cú pháp Commander trên stderr, kể cả với --json; nó không sử dụng bao chẩn đoán này.

Lọc báo cáo đầy đủ bên ngoài

Để xem JSON tùy chỉnh, lọc báo cáo đầy đủ bằng jq hoặc PowerShell. Các ví dụ script này giữ nguyên mã thoát xác thực và để nguyên tài liệu lỗi lệnh.

Trong Bash với jq:

if validation_json=$(openspec validate --all --json); then
  validation_exit=0
else
  validation_exit=$?
fi
printf '%s\n' "$validation_json" |
  jq 'if has("items") then .items |= map(select(.issues | length > 0)) else . end'
exit "$validation_exit"

Trong PowerShell:

$validationJson = openspec validate --all --json
$validationExit = $LASTEXITCODE
$validationReport = $validationJson | ConvertFrom-Json
if ($validationReport.PSObject.Properties.Name -contains 'items') {
  $validationReport.items = @($validationReport.items | Where-Object { $_.issues.Count -gt 0 })
}
$validationReport | ConvertTo-Json -Depth 100
exit $validationExit

Các chế độ xem tùy chỉnh này giữ các khóa của báo cáo đầy đủ nhưng bỏ qua các mục sạch. Chúng không phải báo cáo full-v1 đầy đủ cũng không phải hình dạng --report findings có phiên bản.

openspec archive

Di chuyển một change đã hoàn thành vào kho lưu trữ và cập nhật các spec chính.

openspec archive add-rate-limit -y                # lưu trữ một change, hợp nhất các delta của nó
openspec archive add-rate-limit -y --skip-specs   # lưu trữ mà không chạm vào các spec

Nếu không có tên, archive sẽ nhắc bạn chọn một change. Khi chạy ngoài terminal tương tác, nó sẽ thoát với mã 1 và in ra lệnh để chạy lại.

Đối số

Đối số	Mô tả
change-name	Change cần lưu trữ, xác định theo tên thư mục (add-rate-limit).

Tùy chọn

Flag	Tác dụng
-y, --yes	Trả lời có cho mọi xác nhận: cập nhật spec, task chưa hoàn thành, bỏ qua kiểm tra hợp lệ.
--skip-specs	Lưu trữ mà không chạm vào các spec chính (dành cho change về hạ tầng, công cụ hoặc chỉ tài liệu).
--no-validate	Bỏ qua kiểm tra hợp lệ. Archive sẽ hỏi bạn xác nhận trước, và -y trả lời giúp.
--json	In kết quả có cấu trúc thay vì văn bản. Cần --yes để xác nhận các cập nhật spec.
--store <id>	Dùng một store đã đăng ký làm thư mục gốc OpenSpec thay vì dự án hiện tại.

Đầu ra

Một lần chạy thành công sẽ báo trạng thái task, xem trước các cập nhật spec, áp dụng chúng và nêu tên thư mục lưu trữ:

Task status: ✓ Complete

Specs to update:
  api: update
Applying changes to openspec/specs/api/spec.md:
  + 1 added
Totals: + 1, ~ 0, - 0, → 0
Specs updated successfully.
Change 'add-rate-limit' archived as '2026-08-11-add-rate-limit'.

Thư mục change được di chuyển nguyên vẹn vào openspec/changes/archive/2026-08-11-add-rate-limit/, với ngày hiện tại làm tiền tố cho tên của nó. Mỗi delta được hợp nhất vào spec chính của nó: requirement ADDED ở trên đã được bổ sung vào openspec/specs/api/spec.md. Nếu không dùng -y, archive sẽ hiển thị bản xem trước và hỏi trước khi cập nhật. Nếu từ chối, change vẫn được lưu trữ còn các spec được giữ nguyên.

Với --json --yes:

{
  "archive": {
    "change": "add-rate-limit",
    "archivedAs": "2026-08-11-add-rate-limit",
    "path": "/Users/you/projects/my-app/openspec/changes/archive/2026-08-11-add-rate-limit",
    "specsUpdated": true,
    "totals": {
      "added": 1,
      "modified": 0,
      "removed": 0,
      "renamed": 0
    }
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Archive kiểm tra hợp lệ change trước và từ chối những change không đạt:

Validation errors in change delta specs:
  ✗ ADDED "Rate limiting" must include at least one scenario

Validation failed. Please fix the errors before archiving.
To skip validation (not recommended), use --no-validate flag.

Task chưa hoàn thành chỉ cảnh báo chứ không chặn. Trong chế độ tương tác, archive sẽ hỏi có tiếp tục hay không, còn -y sẽ tự tiếp tục:

Task status: 1/2 tasks
Warning: 1 incomplete task(s) found. Continuing due to --yes flag.

Mã thoát

• 0: change đã được lưu trữ, dù có hay không có cập nhật spec.
• 1: kiểm tra hợp lệ thất bại, tên change không tồn tại, hoặc cần xác nhận nhưng không thể đọc được câu trả lời.

openspec new

Tạo một thư mục change mới.

openspec new change add-caching                                # chỉ metadata
openspec new change add-search --goal "Users can search docs"  # ghi lại một goal

new có duy nhất một subcommand là new change <name>. Nó tạo thư mục openspec/changes/<name>/ chứa duy nhất một tệp metadata .openspec.yaml:

schema: spec-driven
created: 2026-08-11

Các artifact (proposal, specs, design, tasks) không được tạo sẵn ở đây. Bạn sẽ tự viết chúng sau, và openspec status sẽ cho biết mục tiếp theo cần làm.

Đối số

Đối số	Mô tả
name	Tên thư mục cho change (add-caching).

Tùy chọn

Flag	Tác dụng
--description <text>	Đồng thời tạo một README.md trong thư mục change với nội dung này.
--goal <text>	Lưu một dòng goal: vào .openspec.yaml.
--schema <name>	Schema workflow cho change. Mặc định: spec-driven, schema duy nhất đi kèm.
--json	In change vừa tạo dưới dạng JSON thay vì văn bản.
--store <id>	Dùng một store đã đăng ký làm thư mục gốc OpenSpec thay vì dự án hiện tại.

Đầu ra

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Khi không tìm thấy thư mục openspec/ nào, new change sẽ tạo một thư mục ngay tại vị trí bạn đang đứng và thông báo điều đó:

Created change 'add-caching' at openspec/changes/add-caching/
Schema: spec-driven
Next: openspec status --change add-caching

Note: no OpenSpec root was found here, so one was created at openspec/.
Run `openspec init` to finish setting this project up, or delete that directory if you meant a different project.

Thông báo này được ghi ra stdout cùng với phần còn lại của đầu ra dành cho người dùng, và không bao giờ xuất hiện khi dùng --json.

Với --json, trong một dự án đã có sẵn openspec/:

{
  "change": {
    "id": "add-caching",
    "path": "/Users/you/projects/my-app/openspec/changes/add-caching",
    "metadataPath": "/Users/you/projects/my-app/openspec/changes/add-caching/.openspec.yaml",
    "schema": "spec-driven"
  },
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Khi không tìm thấy thư mục openspec/ nào và new change đã tạo một thư mục, JSON sẽ có cấu trúc tương tự. root.path là thư mục nơi bạn chạy lệnh, và root.source sẽ có giá trị implicit:

"root": {
  "path": "/Users/you/projects/my-app",
  "source": "implicit"
}

Mã thoát

• 0: change đã được tạo.
• 1: change đã tồn tại, hoặc schema không xác định.## openspec status

Báo cáo trạng thái hoàn thành artifact cho một thay đổi hoặc mọi thay đổi đang hoạt động.

openspec status --change add-rate-limit          # chế độ xem danh sách kiểm tra
openspec status --change add-rate-limit --json   # báo cáo có cấu trúc
openspec status --all                            # mọi thay đổi đang hoạt động
openspec status --all --json                     # một báo cáo hàng loạt

Khi có các thay đổi đang hoạt động, chỉ dùng chính xác một trong --change hoặc --all. Nếu không có cờ nào, lệnh status thoát với mã 1 và liệt kê các thay đổi khả dụng, ngay cả khi chỉ có một thay đổi:

✖ Error: Missing required option --change (or --all for every active change). Available changes:
  add-rate-limit

Khi dự án không có thay đổi đang hoạt động, lệnh status in No active changes. Create one with: openspec new change <name> và thoát với mã 0 ngay cả khi không có cờ nào. Với --all --json, trạng thái trống tương tự là { "changes": [], "message": "No active changes.", "root": ... }.

Tùy chọn

Cờ	Tác dụng
--change <id>	Thay đổi cần báo cáo, xác định theo tên thư mục.
--all	Báo cáo mọi thay đổi đang hoạt động, được sắp xếp theo tên. Không thể kết hợp với --change.
--schema <name>	Ghi đè schema được tự động phát hiện từ openspec/config.yaml. Tên không xác định sẽ gây lỗi.
--json	In báo cáo có cấu trúc thay vì văn bản.
--store <id>	Dùng một store đã đăng ký làm root của OpenSpec thay vì dự án hiện tại.

Đầu ra

Một danh sách kiểm tra các artifact của schema: [x] hoàn thành, [ ] sẵn sàng để viết, [-] bị chặn cho đến khi các artifact mà nó phụ thuộc tồn tại.

Change: add-rate-limit
Schema: spec-driven
Change root: /Users/you/projects/my-app/openspec/changes/add-rate-limit
Progress: 2/4 artifacts complete

[x] proposal
[x] specs
[ ] design
[-] tasks (blocked by: design)

Next: openspec instructions design --change "add-rate-limit" --json

Dòng Next: cho biết lệnh duy nhất giúp đẩy thay đổi tiến lên, vì vậy openspec status là đủ để tiếp tục một thay đổi trong một phiên mới. Dòng này cho biết artifact sẵn sàng tiếp theo khi quá trình lập kế hoạch chưa hoàn tất, và cho biết openspec instructions apply khi mọi artifact lập kế hoạch đã tồn tại:

[x] proposal
[x] specs
[x] design
[x] tasks

All planning artifacts complete!
Next: openspec instructions apply --change "add-rate-limit" --json

Dòng này kèm theo --store <id> bất cứ khi nào root được phân giải là một store, và cho biết cùng một lệnh với câu trong nextSteps của JSON.

--json bổ sung các phụ thuộc theo từng artifact, đường dẫn tệp đã phân giải và bước tiếp theo được đề xuất. Đã rút gọn:

{
  "changeName": "add-rate-limit",
  "schemaName": "spec-driven",
  "isComplete": false,
  "nextSteps": [
    "Run openspec instructions design --change \"add-rate-limit\" --json before writing that artifact."
  ],
  "artifacts": [
    {
      "id": "proposal",
      "outputPath": "proposal.md",
      "status": "done",
      "requires": []
    },
    {
      "id": "design",
      "outputPath": "design.md",
      "status": "ready",
      "requires": [
        "proposal"
      ]
    },
    {
      "id": "tasks",
      "outputPath": "tasks.md",
      "status": "blocked",
      "requires": [
        "specs",
        "design"
      ],
      "missingDeps": [
        "design"
      ]
    }
  ]
}

Với --all --json, changes chứa cùng một đối tượng trạng thái cho từng thay đổi, không có root cho từng thay đổi. Root được chọn xuất hiện một lần ở đối tượng bao ngoài. Ví dụ này rút gọn các trường trạng thái theo từng thay đổi được hiển thị ở trên:

{
  "changes": [
    {
      "changeName": "add-rate-limit",
      "schemaName": "spec-driven",
      "artifacts": []
    }
  ],
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest"
  }
}

Nếu một thay đổi không thể tải, quá trình xử lý hàng loạt vẫn tiếp tục. Mục của thay đổi đó chứa changeName và thông tin chẩn đoán status, trong khi các mục khác vẫn khả dụng. Lệnh thoát với mã 1, kể cả ở chế độ JSON, để CI không chấp nhận một báo cáo không đầy đủ là thành công. Đầu ra JSON vẫn là một tài liệu có thể phân tích cú pháp.

Mã thoát

• 0: mọi trạng thái được yêu cầu đã được in; báo cáo --all trống cũng thoát với mã 0.
• 1: một thay đổi được yêu cầu không tải được, thiếu --change hoặc --all, hai cờ được kết hợp, thay đổi không tồn tại, hoặc schema ghi đè không xác định.

openspec instructions

In các hướng dẫn để tạo artifact, áp dụng hoặc lưu trữ. Agent của bạn chạy lệnh này trong quy trình làm việc để lấy văn bản hướng dẫn cho bước tiếp theo.

openspec instructions proposal --change add-rate-limit   # cách viết một artifact
openspec instructions apply --change add-rate-limit      # cách triển khai thay đổi
openspec instructions archive --change add-rate-limit    # đầu vào cho việc lưu trữ

Đối số

Đối số	Mô tả
artifact	Mã artifact từ schema (proposal, specs, design, tasks trong spec-driven), hoặc các từ dành riêng apply và archive.

Tùy chọn

Cờ	Tác dụng
--change <id>	Thay đổi cần tạo hướng dẫn. Bắt buộc.
--schema <name>	Ghi đè schema. Nếu không, được tự động phát hiện từ config.yaml.
--json	In một đối tượng có cấu trúc thay vì văn bản.
--store <id>	Dùng một store đã đăng ký làm root của OpenSpec thay vì dự án hiện tại.

Đầu ra

Dạng artifact in một khối hướng dẫn: nhiệm vụ, tệp cần viết, cách viết, mẫu của artifact và những gì được mở khóa khi hoàn thành nó.

<artifact id="proposal" change="add-rate-limit" schema="spec-driven">

<task>
Create the proposal artifact for change "add-rate-limit".
Initial proposal document outlining the change
</task>

<output>
Write to: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
</output>

<instruction>
Create the proposal document that establishes WHY this change is needed.
...

apply in các tệp ngữ cảnh, tiến trình nhiệm vụ và hướng dẫn làm việc:

## Apply: add-rate-limit
Schema: spec-driven

### Context Files
- proposal: /Users/you/projects/my-app/openspec/changes/add-rate-limit/proposal.md
- specs: /Users/you/projects/my-app/openspec/changes/add-rate-limit/specs/api/spec.md
- tasks: /Users/you/projects/my-app/openspec/changes/add-rate-limit/tasks.md

### Progress
1/3 complete

### Tasks
- [x] 1.1 Add rate limit middleware
- [ ] 1.2 Return 429 with Retry-After header
- [ ] 1.3 Add tests for burst traffic

### Instruction
Read context files, work through pending tasks, mark complete as you go.
Pause if you hit blockers or need clarification.

No project context or operation guidance configured.

Khi thiếu các artifact bắt buộc, apply báo cáo ### ⚠️ Blocked và thay vào đó nêu tên chúng. archive in tên thay đổi cùng với mọi ngữ cảnh dự án và hướng dẫn thao tác từ cấu hình. Nếu không có gì được cấu hình, nó sẽ nói rõ như vậy và không in gì thêm.

Với --json, mỗi dạng trả về một đối tượng. Dạng artifact bắt đầu như sau:

{
  "changeName": "add-rate-limit",
  "artifactId": "proposal",
  "schemaName": "spec-driven",
  "changeDir": "/Users/you/projects/my-app/openspec/changes/add-rate-limit",
  ...

và tiếp tục với outputPath, existingOutputPaths, các chuỗi instruction và template đầy đủ, dependencies, unlocks và root. Dạng apply chứa contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done) và instruction.

Mỗi mục trong tasks có id, description, done, sourcePath và line. sourcePath là đường dẫn tuyệt đối đến tệp được theo dõi đã cung cấp nhiệm vụ. line là số dòng bắt đầu từ 1 của hộp kiểm nhiệm vụ trong tệp đó.

taskTrackingConfigured luôn là giá trị boolean: true khi schema đặt apply.tracks khác null, ngay cả khi không có tệp nào khớp, và false trong các trường hợp khác. Nếu không thể đọc một tệp theo dõi khớp, unavailableTrackingFiles chứa path tuyệt đối của nó và reason lỗi. Trường này được bỏ qua khi mọi tệp khớp đều có thể đọc được. Các tệp có thể đọc vẫn đóng góp vào tasks và progress, nhưng state không thể là all_done cho đến khi mọi tệp khớp được đọc.

Mã thoát

• 0: hướng dẫn đã được in.
• 1: artifact không xác định, thay đổi không xác định, schema không xác định, hoặc thiếu --change. Mỗi lỗi liệt kê các giá trị hợp lệ.

openspec templates

In ra các đường dẫn template đã được phân giải cho các artifact của một schema.

openspec templates          # schema mặc định: spec-driven
openspec templates --json   # ánh xạ id artifact sang đường dẫn

Tùy chọn

Cờ	Tác dụng
--schema <name>	Schema cần phân giải. Mặc định: spec-driven.
--json	In ra ánh xạ JSON từ id artifact sang đường dẫn template.

Đầu ra

Schema: spec-driven
Source: package

proposal:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md
specs:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md
design:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md
tasks:
  /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md

Source cho biết schema được phân giải từ đâu: project (openspec/schemas/ trong dự án của bạn), user (ghi đè toàn cục), hoặc package (được tích hợp sẵn trong CLI). project được ưu tiên hơn user, user hơn package.

{
  "proposal": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/proposal.md",
    "source": "package"
  },
  "specs": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/spec.md",
    "source": "package"
  },
  "design": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/design.md",
    "source": "package"
  },
  "tasks": {
    "path": "/usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven/templates/tasks.md",
    "source": "package"
  }
}

Mã thoát

• 0: đã in các đường dẫn.
• 1: schema không xác định. Lỗi sẽ liệt kê các schema có sẵn.

openspec schemas

Liệt kê các schema workflow có sẵn.

openspec schemas          # tên, mô tả, thứ tự artifact
openspec schemas --json   # dạng máy đọc được, dùng cho agent

Tùy chọn

Cờ	Tác dụng
--json	Xuất dưới dạng JSON (dùng cho agent).

Đầu ra

Available schemas:

  spec-driven
    Default OpenSpec workflow - proposal → specs → design → tasks
    Artifacts: proposal → specs → design → tasks

Các schema từ dự án của bạn được gắn nhãn (project), và các ghi đè toàn cục được gắn nhãn (user override).

[
  {
    "name": "spec-driven",
    "description": "Default OpenSpec workflow - proposal → specs → design → tasks",
    "artifacts": [
      "proposal",
      "specs",
      "design",
      "tasks"
    ],
    "source": "package"
  }
]

Mã thoát

• 0: đã liệt kê các schema.
• 1: không thể đọc danh sách schema.## openspec schema

Kiểm tra, tạo bản sao (fork) hoặc tạo mới một lược đồ (schema) (thử nghiệm). Mỗi lệnh con trước tiên in Note: Schema commands are experimental and may change. ra stderr.

openspec schema which spec-driven          # nơi một lược đồ được phân giải từ đó
openspec schema fork spec-driven my-flow   # sao chép một lược đồ vào dự án
openspec schema init my-schema             # tạo một lược đồ từ đầu

Lệnh con	Chức năng
which	Hiển thị nơi một lược đồ được phân giải từ đó.
validate	Kiểm tra cấu trúc và các mẫu (template) của một lược đồ.
fork	Sao chép một lược đồ hiện có vào dự án để tùy chỉnh.
init	Tạo một lược đồ mới cục bộ trong dự án.

Các lược đồ được phân giải từ ba vị trí. Kết quả khớp đầu tiên được ưu tiên:

Nguồn	Vị trí
project	openspec/schemas/ trong dự án hiện tại.
user	~/.local/share/openspec/schemas/ (tôn trọng XDG_DATA_HOME và %LOCALAPPDATA% trên Windows).
package	Các lược đồ được đóng gói cùng CLI. spec-driven nằm ở đây.

openspec schema which

Hiển thị bản sao lược đồ mà CLI sẽ sử dụng.

openspec schema which spec-driven
openspec schema which --all        # mọi lược đồ, được nhóm theo nguồn

Đối số

Đối số	Ý nghĩa
name	Lược đồ cần tra cứu. Bắt buộc trừ khi --all được đặt. Nếu không có cái nào, lệnh which thoát với mã 1.

Tùy chọn

Cờ	Hiệu ứng
--all	Liệt kê mọi lược đồ cùng với nguồn phân giải của chúng.
--json	In kết quả phân giải dưới dạng JSON.

Đầu ra

Schema: spec-driven
Source: package
Path: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven

Khi một bản sao có mức ưu tiên cao hơn che khuất bản khác, một phần Shadows: sẽ liệt kê các bản sao bị che khuất. Với --json:

{
  "name": "my-flow",
  "source": "project",
  "path": "/Users/you/projects/my-app/openspec/schemas/my-flow",
  "shadows": []
}

Một tên không xác định sẽ thoát với mã 1 và liệt kê các lược đồ khả dụng.

openspec schema validate

Kiểm tra cấu trúc và các mẫu của một lược đồ.

openspec schema validate spec-driven   # một lược đồ, từ bất kỳ nguồn nào
openspec schema validate               # mọi lược đồ cục bộ trong dự án

Lệnh này xác minh rằng schema.yaml tồn tại và phân tích được, rằng cấu trúc khớp với định dạng lược đồ, rằng tệp mẫu của mọi tạo tác (artifact) tồn tại bên trong thư mục templates/ của lược đồ, và rằng đồ thị phụ thuộc không có chu trình hoặc tham chiếu không xác định, bao gồm cả trong apply.requires. Một giá trị apply.tracks không khớp chính xác với giá trị generates của một số tạo tác sẽ in một dòng warning: nhưng không làm hỏng quá trình xác thực, vì khi đó OpenSpec không thể biết tệp đó thuộc về tiến trình của tạo tác nào.

Tùy chọn

Cờ	Hiệu ứng
--json	In một báo cáo có cấu trúc thay vì văn bản.
--verbose	In từng bước xác thực.

Đầu ra

✓ Schema 'spec-driven' is valid

Khi không có tên, mỗi lược đồ dự án nhận một dòng dưới tiêu đề Validation Results:. Một lược đồ bị lỗi liệt kê các vấn đề của nó và quá trình chạy thoát với mã 1:

✗ Schema 'my-schema' has errors:
  error: Template file 'tasks.md' not found for artifact 'tasks'

openspec schema fork

Sao chép một lược đồ hiện có vào dự án để bạn có thể tùy chỉnh nó.

openspec schema fork spec-driven my-flow

Đối số

Đối số	Ý nghĩa
source	Lược đồ cần sao chép, từ bất kỳ vị trí nguồn nào.
name	Tên cho bản sao. Dạng kebab-case (my-workflow). Mặc định: <source>-custom.

Tùy chọn

Cờ	Hiệu ứng
--force	Ghi đè lên một lược đồ đích hiện có.
--json	In kết quả dưới dạng JSON.

Đầu ra

✔ Forked 'spec-driven' to 'my-flow'

Source: /usr/local/lib/node_modules/@fission-ai/openspec/schemas/spec-driven (package)
Destination: /Users/you/projects/my-app/openspec/schemas/my-flow

Bản sao được đặt trong openspec/schemas/, và trường name: trong schema.yaml của nó được viết lại thành tên mới:

openspec/schemas/my-flow/
├── schema.yaml
└── templates/
    ├── design.md
    ├── proposal.md
    ├── spec.md
    └── tasks.md

Một đích đã tồn tại sẽ gây ra lỗi trừ khi bạn truyền --force. Một bản sao giữ nguyên tên của nguồn sẽ che khuất bản gốc.

openspec schema init

Tạo một lược đồ mới cục bộ trong dự án với các mẫu khởi đầu.

openspec schema init my-schema --description "Lightweight flow" --artifacts proposal,tasks

Khi không có --description và không có --artifacts trong một thiết bị đầu cuối tương tác, lệnh init sẽ nhắc nhập mô tả, một danh sách kiểm tra tạo tác và liệu có đặt lược đồ làm mặc định của dự án hay không. Bên ngoài thiết bị đầu cuối, nó sử dụng các giá trị mặc định bên dưới.

Đối số

Đối số	Ý nghĩa
name	Tên cho lược đồ mới. Dạng kebab-case (my-workflow).

Tùy chọn

Cờ	Hiệu ứng
--description <text>	Mô tả lược đồ. Mặc định: Custom workflow schema for <name>.
--artifacts <list>	Danh sách ID tạo tác phân tách bằng dấu phẩy từ proposal, specs, design, tasks. Mặc định: cả bốn.
--default	Ghi schema: <name> vào openspec/config.yaml hoặc openspec/config.yml hiện có. Tạo openspec/config.yaml nếu không có tệp nào tồn tại. Các thay đổi mới sẽ sử dụng lược đồ này.
--no-default	Bỏ qua lời nhắc về lược đồ mặc định.
--force	Ghi đè lên một lược đồ hiện có cùng tên.
--json	In kết quả dưới dạng JSON.

Việc tạo lược đồ và cập nhật cấu hình --default là một thao tác duy nhất. Nếu OpenSpec không thể xác thực hoặc ghi cấu hình, nó sẽ giữ nguyên cả cấu hình và mọi lược đồ hiện có.

Đầu ra

✔ Created schema 'my-schema'

Schema created at: /Users/you/projects/my-app/openspec/schemas/my-schema

Artifacts: proposal, tasks

Bố cục trên đĩa:

openspec/schemas/my-schema/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

schema.yaml kết nối các tạo tác đã chọn với các phụ thuộc của chúng. Khi tasks được bao gồm, nó cũng nhận một giai đoạn apply để theo dõi tasks.md. Sử dụng lược đồ này với openspec new --schema my-schema.

openspec store

Tạo và quản lý các kho lưu trữ (store): các kho OpenSpec độc lập được đăng ký trên máy của bạn.

openspec store setup team-context --path ~/openspec/team-context   # tạo và đăng ký
openspec store register ~/stores/design-system                     # đăng ký một bản sao đã có
openspec store list                                                # xem những gì đã đăng ký

Các đăng ký nằm trong một sổ đăng ký trên mỗi máy: ~/.local/share/openspec/stores/registry.yaml, hoặc $XDG_DATA_HOME/openspec/stores/registry.yaml khi XDG_DATA_HOME được đặt. Mọi lệnh con đều nhận --json để in một báo cáo có cấu trúc thay vì văn bản. Chạy openspec store với một lệnh con bị thiếu hoặc không xác định sẽ thoát với mã 1 và liệt kê các lệnh con.

Lệnh con	Chức năng
setup [id]	Tạo một thư mục kho lưu trữ và đăng ký nó.
register [path]	Đăng ký một thư mục kho lưu trữ hiện có.
unregister <id>	Xóa đăng ký. Thư mục vẫn còn trên đĩa.
remove <id>	Xóa đăng ký và xóa thư mục.
list (bí danh ls)	Liệt kê các kho lưu trữ đã đăng ký.
doctor [id]	Kiểm tra đăng ký, siêu dữ liệu và trạng thái Git cho các kho lưu trữ đã đăng ký.

openspec store setup

Tạo một thư mục kho lưu trữ và đăng ký nó.

openspec store setup team-context --path ~/openspec/team-context

Trong một thiết bị đầu cuối tương tác, setup sẽ nhắc nhập tên và vị trí còn thiếu và xác nhận trước khi tạo bất cứ thứ gì. Bên ngoài thiết bị đầu cuối, thiếu tên hoặc --path sẽ thoát với mã 1 kèm cờ cần truyền. Chạy lại setup cho một kho lưu trữ đã đăng ký sẽ báo cáo Registry: already registered.

Setup thoát với mã 1 và mã lỗi store_setup_inside_git_repo khi --path nằm bên trong một kho Git khác, vì việc khởi tạo kho lưu trữ ở đó sẽ lồng một kho trong một kho khác. --no-init-git không tạo kho lưu trữ, vì vậy nó bỏ qua kiểm tra đó. Hãy sử dụng nó để giữ một kho lưu trữ tại ~/openspec/<id> khi thư mục chính của bạn tự nó là một kho Git, chẳng hạn như kho dotfiles.

Đối số

Đối số	Ý nghĩa
id	Tên kho lưu trữ. Nó trở thành id bạn truyền cho --store.

Tùy chọn

Cờ	Hiệu ứng
--path <path>	Thư mục nơi kho lưu trữ sẽ nằm (~ được mở rộng).
--init-git	Khởi tạo một kho Git với một commit ban đầu. Mặc định.
--no-init-git	Bỏ qua mọi hành động Git: không khởi tạo, không commit ban đầu.
--remote <url>	Nguồn sao chép chuẩn được ghi trong store.yaml.

Đầu ra

Store ready: team-context
Location: /Users/you/stores/team-context
OpenSpec root: ready
Registry: registered

Next: run normal OpenSpec commands against this store, for example:
  openspec new change <change-id> --store team-context
Share this store by committing and pushing it like any Git repo.

--json báo cáo những gì đã được tạo và nơi nó được đăng ký:

{
  "store": {
    "id": "design-system",
    "root": "/Users/you/stores/design-system",
    "metadata_path": "/Users/you/stores/design-system/.openspec-store/store.yaml"
  },
  "registry": {
    "path": "/Users/you/.local/share/openspec/stores/registry.yaml",
    "registered": true,
    "already_registered": false
  },
  "git": {
    "is_repository": true,
    "initialized": true,
    "committed": true
  },
  "created_files": [
    "openspec/",
    "openspec/specs/",
    "openspec/changes/",
    "openspec/changes/archive/",
    "openspec/config.yaml",
    "openspec/specs/.gitkeep",
    "openspec/changes/archive/.gitkeep",
    ".openspec-store/store.yaml"
  ],
  "status": []
}

openspec store register

Đăng ký một thư mục kho lưu trữ hiện có, ví dụ như kho lưu trữ của đồng nghiệp mà bạn đã sao chép.

openspec store register ~/stores/design-system

Thư mục phải chứa một thư mục gốc openspec/ lành mạnh. Khi có .openspec-store/store.yaml, register sẽ tái sử dụng id đã ghi. Khi không có, register sẽ hỏi trước khi tạo siêu dữ liệu đó. Bên ngoài thiết bị đầu cuối tương tác, hãy truyền --yes để thay thế. Một máy có thể đăng ký một bản sao cho mỗi id kho lưu trữ. Một đường dẫn thứ hai dưới cùng một id, hoặc cùng một đường dẫn dưới một id thứ hai, sẽ thoát với mã 1.

Đối số

Đối số	Ý nghĩa
path	Thư mục kho lưu trữ cần đăng ký (~ được mở rộng). Bắt buộc.

Tùy chọn

Cờ	Hiệu ứng
--id <id>	Id kho lưu trữ. Mặc định là siêu dữ liệu hoặc tên thư mục.
--yes	Xác nhận tạo siêu dữ liệu danh tính kho lưu trữ cho một thư mục gốc OpenSpec lành mạnh.

Đầu ra

Store registered: design-system
Location: /Users/you/stores/design-system
OpenSpec root: ready
Registry: registered

--json in cùng một cấu trúc tài liệu như store setup --json.

openspec store unregister

Xóa đăng ký. Thư mục vẫn còn trên đĩa.

openspec store unregister design-system

Unregistered store: design-system
Files kept at: /Users/you/stores/design-system

openspec store remove

Xóa đăng ký và xóa thư mục.

openspec store remove design-system --yes

Khi tương tác, remove sẽ hỏi trước khi xóa. Với --json hoặc bên ngoài thiết bị đầu cuối tương tác, việc xóa yêu cầu --yes:

Error: Pass --yes to delete store files non-interactively.
Fix: openspec store remove design-system --yes

Remove thoát với mã 1 và không xóa gì khi thư mục thiếu siêu dữ liệu kho lưu trữ khớp, hoặc khi nó chứa một kho lưu trữ đã đăng ký khác (ví dụ: một kho lưu trữ được bán như một Git submodule). Trong trường hợp đó, lỗi là store_remove_contains_registered_store: hãy chạy openspec store unregister <nested-id> trước, hoặc openspec store unregister <id> để xóa đăng ký mà không xóa tệp.

Tùy chọn

Cờ	Hiệu ứng
--yes	Xác nhận xóa thư mục kho lưu trữ cục bộ.

Đầu ra

Removed store: design-system
Deleted: /Users/you/stores/design-system

openspec store list

Liệt kê các kho lưu trữ đã đăng ký. ls là một bí danh.

openspec store list

OpenSpec stores (2)

ID              Location
design-system   /Users/you/stores/design-system
team-context    /Users/you/stores/team-context

Khi không có gì được đăng ký, list in No stores registered. và các lệnh setup và register cần chạy tiếp theo.

openspec store doctor

Kiểm tra đăng ký, siêu dữ liệu và trạng thái Git cho các kho lưu trữ đã đăng ký.

openspec store doctor                # mọi kho lưu trữ đã đăng ký
openspec store doctor team-context  # một kho lưu trữ

Đầu ra

Store doctor

team-context
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Metadata: ok
  Git: repository detected (commits: yes, uncommitted changes: no, remote: none)
  Issues: none

Mã thoát

• 0: báo cáo đã được in, ngay cả khi một kho lưu trữ báo cáo vấn đề.
• 1: báo cáo không thể chạy (ví dụ: id kho lưu trữ không xác định).

openspec doctor

Báo cáo tình trạng các mối quan hệ của OpenSpec root được xác định.

openspec doctor                       # openspec/ root gần nhất phía trên cwd của bạn
openspec doctor --store team-context  # một store đã đăng ký làm root

Doctor chỉ đọc: nó không bao giờ clone, sync hay repair. Nó báo cáo liệu root có ở trạng thái tốt hay không và liệu từng tham chiếu được khai báo trong openspec/config.yaml có resolve được trên máy này hay không. Khi không có root nào phía trên cwd của bạn và không có --store, lệnh thoát với mã 1 và liệt kê tên các store đã đăng ký của bạn.

Tùy chọn

Cờ	Tác dụng
--store <id>	Dùng một store đã đăng ký làm OpenSpec root thay vì dự án hiện tại.
--json	In báo cáo tình trạng dưới dạng JSON.

Đầu ra

Doctor

Root
  Location: /Users/you/projects/my-app
  OpenSpec root: ok

References
  - team-context: ok (/Users/you/stores/team-context)

Với --store, root là store và báo cáo thêm một dòng store:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Doctor

Root
  Location: /Users/you/stores/team-context
  OpenSpec root: ok
  Store: team-context (metadata ok)

References
  (none declared)

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "healthy": true,
    "status": []
  },
  "store": null,
  "references": [
    {
      "store_id": "team-context",
      "root": "/Users/you/stores/team-context",
      "status": []
    }
  ],
  "status": []
}

Mã thoát

• 0: báo cáo đã được in, kể cả khi báo cáo liệt kê các vấn đề.
• 1: không xác định được root (không có openspec/ phía trên cwd của bạn và không có --store), hoặc id --store không xác định.

openspec context

In ngữ cảnh làm việc cho OpenSpec root được xác định: root cùng mọi store được tham chiếu và khai báo trong openspec/config.yaml, mỗi store kèm một lệnh fetch.

openspec context                       # openspec/ root gần nhất phía trên cwd của bạn
openspec context --store team-context  # một store đã đăng ký làm root
openspec context --json                # bản tóm tắt cho agent

Các tham chiếu không resolve được trên máy này sẽ xuất hiện trong mục Not available on this machine, mỗi tham chiếu kèm một cách khắc phục.

Tùy chọn

Cờ	Tác dụng
--store <id>	Dùng một store đã đăng ký làm OpenSpec root thay vì dự án hiện tại.
--json	In bản tóm tắt cho agent dưới dạng JSON.
--code-workspace <path>	Đồng thời ghi một tệp workspace VS Code cho tập làm việc này.
--force	Ghi đè tệp hiện có do --code-workspace chỉ định.

Đầu ra

Working context for my-app (/Users/you/projects/my-app)

OpenSpec root
  my-app  /Users/you/projects/my-app

Referenced stores
  team-context  /Users/you/stores/team-context
    Fetch: openspec show <spec-id> --type spec --store team-context

Với --store, store chính là toàn bộ tập làm việc:

Using OpenSpec root: team-context (/Users/you/stores/team-context)
Working context for team-context (/Users/you/stores/team-context)

OpenSpec root
  team-context  /Users/you/stores/team-context

No references declared; the working set is this root alone.

{
  "root": {
    "path": "/Users/you/projects/my-app",
    "source": "nearest",
    "role": "openspec_root"
  },
  "members": [
    {
      "role": "referenced_store",
      "id": "team-context",
      "path": "/Users/you/stores/team-context",
      "fetch": "openspec show <spec-id> --type spec --store team-context",
      "status": []
    }
  ],
  "status": []
}

Ghi tệp workspace

--code-workspace ghi một tệp workspace VS Code tại đường dẫn bạn cung cấp: một thư mục cho root, một thư mục ref:<id> cho mỗi store được tham chiếu khả dụng. Các tham chiếu không khả dụng sẽ bị bỏ qua và được nêu tên trong dòng tóm tắt, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). Dòng tóm tắt được in ra stderr, nên stdout của --json vẫn chỉ là một tài liệu JSON. Một tệp đã tồn tại sẽ khiến lệnh thoát với mã 1 trừ khi bạn truyền --force.

{
  "folders": [
    {
      "name": "my-app",
      "path": "/Users/you/projects/my-app"
    },
    {
      "name": "ref:team-context",
      "path": "/Users/you/stores/team-context"
    }
  ]
}

Mã thoát

• 0: báo cáo đã được in.
• 1: không xác định được root (không có openspec/ phía trên cwd của bạn và không có --store), hoặc việc ghi --code-workspace bị từ chối.## openspec workset

Soạn, lưu giữ và mở các khung làm việc cá nhân. Workset là danh sách thư mục đã lưu, được đặt tên mà bạn làm việc cùng nhau.

openspec workset create checkout --member ~/projects/checkout-api --member web=~/projects/checkout-web
openspec workset list
openspec workset remove checkout --yes

Lệnh con	Chức năng
create [name]	Soạn và lưu một khung làm việc được đặt tên từ các thư mục bạn chọn.
list, ls	Hiển thị các workset đã lưu kèm các thành viên.
open <name>	Mở một workset đã lưu trong công cụ của bạn (cửa sổ trình soạn thảo hoặc phiên agent).
remove <name>	Xóa một workset đã lưu (các thư mục thành viên không bao giờ bị tác động).

Workset hoàn toàn cục bộ:

• Trạng thái của nó nằm trong một thư mục: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ khi được đặt; %LOCALAPPDATA%\openspec\worksets\ trên Windows).
• Không có gì được ghi vào các thư mục thành viên, và không có gì được commit hoặc chia sẻ.
• Xóa thư mục đó sẽ loại bỏ mọi dấu vết.

openspec workset create

Lưu một khung làm việc được đặt tên từ các thư mục.

openspec workset create checkout \
  --member ~/projects/checkout-api \
  --member web=~/projects/checkout-web

Trong terminal tương tác, create sẽ nhắc nhở những gì mà các flag không cung cấp: tên, thư mục từng cái một, một công cụ, sau đó đề xuất mở workset ngay bây giờ. Ngoài terminal tương tác, thiếu tên hoặc thành viên là lỗi. Tên đã được lưu luôn là lỗi. Hãy xóa nó trước.

Đối số

Đối số	Ý nghĩa
name	Tên workset. Kebab-case: chữ thường, số, dấu gạch nối đơn. Bắt buộc ngoài terminal tương tác.

Tùy chọn

Flag	Hiệu lực
--member <member>	Thư mục thành viên dưới dạng <path> hoặc <name>=<path>, có thể lặp lại. Thư mục đầu tiên là chính. Đường dẫn phải là thư mục hiện có, và nhãn mặc định là tên của thư mục đó.
--tool <id>	Công cụ ưa thích để mở workset này. ID tích hợp: code (VS Code), cursor (Cursor). claude và codex tạm thời bị vô hiệu hóa.
--json	In workset đã lưu dưới dạng JSON.

Đầu ra

Đã lưu workset 'checkout' (2 thành viên) vào máy của bạn.
Mở nó bất kỳ lúc nào với: openspec workset open checkout

openspec workset list

Hiển thị các workset đã lưu kèm các thành viên, sắp xếp theo tên.

openspec workset list   # alias: ls

Tùy chọn

Flag	Hiệu lực
--json	In các workset dưới dạng JSON.

Đầu ra

Một khối cho mỗi workset: tên, công cụ của nó khi có, sau đó một hàng name path cho mỗi thành viên. Khi không có gì được lưu, list in No worksets saved. Create one with: openspec workset create.

checkout
  checkout-api  /Users/you/projects/checkout-api
  web           /Users/you/projects/checkout-web
checkout-tool  (opens in VS Code)
  checkout-api  /Users/you/projects/checkout-api

Với --json:

{
  "worksets": [
    {
      "name": "checkout",
      "members": [
        {
          "name": "checkout-api",
          "path": "/Users/you/projects/checkout-api"
        },
        {
          "name": "web",
          "path": "/Users/you/projects/checkout-web"
        }
      ]
    }
  ],
  "status": []
}

openspec workset open

Mở một workset đã lưu trong công cụ của bạn. Công cụ trình soạn thảo (code, cursor) nhận một tệp .code-workspace được tạo. Một cửa sổ mở ra và lệnh trả về. Công cụ agent CLI (claude, codex) sẽ tiếp quản terminal này với mọi thành viên được đính kèm. Chúng tạm thời bị vô hiệu hóa trong khi luồng đó được cải tiến, vì vậy workset hiện mở trong IDE.

openspec workset open checkout                # saved tool, or a prompt
openspec workset open checkout --tool cursor  # this tool just this once

Đối số

Đối số	Ý nghĩa
name	Workset cần mở.

Tùy chọn

Flag	Hiệu lực
--tool <id>	Mở với công cụ này chỉ một lần này.

Không có --tool và không có công cụ đã lưu, open nhắc bạn chọn một công cụ đã cài đặt. Ngoài terminal tương tác, nó thoát với mã 1.

• Thư mục thành viên không còn tồn tại sẽ bị bỏ qua với cảnh báo. Khi thư mục chính bị thiếu, thành viên tiếp theo còn tồn tại sẽ trở thành chính cho lần mở này. Khi không có thư mục thành viên nào tồn tại, việc mở thất bại.
• --json bị từ chối: open trao terminal cho công cụ và không có chế độ JSON.
• Khi khởi chạy thất bại, lỗi kết thúc với cách thủ công: đường dẫn tệp workspace và danh sách thành viên.

Mã thoát

• Phản chiếu công cụ: lệnh thoát với mã thoát của chính công cụ, và tín hiệu trở thành 128+n (130 sau Ctrl-C).
• 1: workset không xác định, không có thư mục thành viên khả dụng, hoặc không có công cụ khả dụng.

openspec workset remove

Xóa một workset đã lưu và tệp .code-workspace được tạo của nó. Các thư mục thành viên không bao giờ bị tác động.

openspec workset remove checkout --yes

Trong terminal tương tác, remove hiển thị workset và yêu cầu bạn xác nhận. Với --json, hoặc ngoài terminal, nó yêu cầu --yes và thoát với mã 1 nếu không có.

Tùy chọn

Flag	Hiệu lực
--yes	Xác nhận xóa không tương tác.
--json	In việc xóa dưới dạng JSON.

Đầu ra

Đã xóa workset 'checkout'. Các thư mục thành viên không bị tác động.

openspec version

Báo cáo phiên bản OpenSpec đang chạy và cách bản sao này được cài đặt.

openspec version                 # local version and install details
openspec version --json          # structured local report
openspec version --check         # also check the registry for an update
openspec version --check --json  # structured local and update report

Không có --check, lệnh này là cục bộ và không liên hệ registry. Nó hoạt động ngoài dự án OpenSpec. Flag openspec --version hiện có vẫn là dạng ngắn nhất và chỉ in số phiên bản trần.

Tùy chọn

Flag	Hiệu lực
--json	In một tài liệu JSON có phiên bản thay vì văn bản.
--check	Kiểm tra registry đã cấu hình để tìm bản phát hành mới hơn.

Đầu ra

Cho cài đặt npm toàn cục:

OpenSpec 1.13.2 (npm, global)

Phạm vi cài đặt là global, project, temporary cho trình chạy tạm thời như npx, source cho checkout, hoặc standalone cho cài đặt độc lập. OpenSpec bỏ qua các chi tiết không thể xác định thay vì đoán.

--json giữ các chi tiết không xác định dưới dạng giá trị null rõ ràng:

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  }
}

Với --check, bản cập nhật có sẵn thêm phiên bản mới nhất và lệnh khi OpenSpec có thể xác định lệnh an toàn cho cài đặt đó:

OpenSpec 1.13.2 (npm, global)
Update available: 1.14.0
  npm install -g @fission-ai/openspec@latest

{
  "schemaVersion": 1,
  "version": "1.13.2",
  "install": {
    "location": "/opt/homebrew/lib/node_modules/@fission-ai/openspec",
    "packageManager": "npm",
    "scope": "global"
  },
  "update": {
    "status": "available",
    "latest": "1.14.0",
    "command": "npm install -g @fission-ai/openspec@latest",
    "canSelfUpgrade": true
  }
}

Giá trị trạng thái cập nhật:

Trạng thái	Ý nghĩa
available	Registry trả về phiên bản an toàn mới hơn phiên bản đang chạy.
current	Kiểm tra hoàn tất và không tìm thấy phiên bản mới hơn.
disabled	Cài đặt quyền riêng tư hoặc kiểm tra cập nhật hiện có đã chặn truy cập registry. latest là null.
offline	Registry không khả dụng hoặc trả về phản hồi không sử dụng được. latest là null.

Cho cài đặt độc lập, lệnh cập nhật là openspec install.

DO_NOT_TRACK, tùy chọn từ chối telemetry, OPENSPEC_NO_UPDATE_CHECK, phát hiện CI và ghi đè registry không HTTPS bị từ chối sẽ vô hiệu hóa kiểm tra. Kiểm tra bị vô hiệu hóa và ngoại tuyến vẫn thoát với mã 0 vì tính khả dụng của bản cập nhật chỉ mang tính khuyến nghị. Lệnh này không bao giờ nâng cấp OpenSpec; canSelfUpgrade chỉ báo cáo liệu đường dẫn openspec update hiện có có thể nâng cấp an toàn bản sao này hay không.

Mã thoát

• 0: báo cáo cục bộ đã in, bao gồm kiểm tra cập nhật bị vô hiệu hóa hoặc ngoại tuyến.
• 1: cú pháp lệnh không hợp lệ, chẳng hạn như tùy chọn --upgrade không được hỗ trợ.

openspec install

Cài đặt openspec dưới dạng bản độc lập (standalone). Chạy lệnh này từ bản cài đặt qua npm hoặc Homebrew để chuyển đổi, hoặc từ bản cài đặt độc lập để nâng cấp tại chỗ.

openspec install          # bản phát hành mới nhất
openspec install 1.15.0   # một bản phát hành cụ thể

Lệnh này chạy script cài đặt, script này chọn bản phát hành mới nhất mà tất cả các tệp đã được đính kèm, cùng với tệp dành cho máy của bạn, rồi đối chiếu nó với SHA256SUMS của bản phát hành đó:

• Từ trình quản lý gói: cài đặt vào ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) và hiển thị lệnh xóa bản cũ, ví dụ như npm uninstall -g @fission-ai/openspec. Nó không bao giờ tự xóa bản sao đó.
• Từ bản cài đặt độc lập: thay thế tệp đang chạy ngay tại vị trí của nó, giữ nguyên tên.

Sau đó, nó cho biết bản sao openspec nào hiện đang được chạy, vì bản sao do trình quản lý gói cài đặt nằm trước trên PATH của bạn sẽ tiếp tục được chạy cho đến khi bạn gỡ bỏ nó.

Đối số

Đối số	Mô tả
version	Bản phát hành cần cài đặt, ví dụ 1.15.0. Tùy chọn; mặc định là bản mới nhất.

OPENSPEC_INSTALL_DIR và OPENSPEC_INSTALL_NAME cho phép chọn thư mục hoặc tên tệp khác.

Mã thoát

• 0: đã cài đặt thành công.
• 1: phiên bản không phải là bản phát hành, hoặc quá trình tải xuống hoặc cài đặt thất bại. Bản sao hiện tại của bạn vẫn được giữ nguyên.

openspec feedback

Gửi phản hồi về OpenSpec.

openspec feedback "Validate output is hard to scan"
openspec feedback "Archive fails on Windows" --body "Steps: init, propose, archive. Error: EPERM."

CLI gửi thông điệp của bạn dưới dạng một GitHub issue trên repo Fission-AI/OpenSpec thông qua gh CLI của bạn. Tiêu đề sẽ là Feedback: <message>. Nội dung dùng các đề mục của mẫu báo lỗi: thông điệp của bạn nằm dưới What happened, văn bản --body của bạn nằm dưới Details, và một mục Minimal steps to reproduce yêu cầu bạn bổ sung các bước, vì CLI không thể tự điền sẵn. Phần chân trang bổ sung phiên bản CLI, nền tảng và dấu thời gian. Issue được gắn nhãn feedback. Nếu repo không định nghĩa nhãn đó, CLI sẽ thử lại mà không dùng nhãn và thông báo điều đó.

Đối số

Đối số	Mô tả
message	Tóm tắt một dòng. Trở thành tiêu đề của issue. Bắt buộc.

Tùy chọn

Cờ	Tác dụng
--body <text>	Mô tả chi tiết hơn được thêm vào nội dung issue.

Kết quả

Khi thành công:

✓ Feedback submitted successfully!
Issue URL: https://github.com/Fission-AI/OpenSpec/issues/1234

Nếu chưa cài gh hoặc gh chưa đăng nhập, sẽ không có gì được gửi. CLI hiển thị phản hồi đã định dạng của bạn giữa hai dấu --- FORMATTED FEEDBACK ---, sau đó là một liên kết mở mẫu báo lỗi với tiêu đề, phần what happened (thông điệp của bạn và văn bản --body), phiên bản CLI và môi trường (nền tảng và phiên bản Node) đã được điền sẵn. Bạn hoàn tất phần còn lại của mẫu trong trình duyệt. Trường hợp chưa đăng nhập sẽ bổ sung dòng To auto-submit in the future: gh auth login.

Mã thoát

• 0: issue đã được tạo, hoặc phương án dự phòng gửi thủ công đã chạy (không có gh, hoặc gh chưa đăng nhập).
• 1: không có thông điệp nào được cung cấp.
• Mã của chính gh: gh thất bại sau khi xác thực (mạng, giới hạn tần suất, issue bị vô hiệu hóa). Trước tiên, CLI hiển thị lại phản hồi của bạn cùng với URL gửi thủ công.

openspec completion

Cài đặt hoặc tạo shell completion (tự động hoàn thành lệnh cho shell).

openspec completion install        # phát hiện shell của bạn, cài đặt và cấu hình luôn
openspec completion generate zsh   # in script ra stdout

Các shell được hỗ trợ: zsh, bash, fish, powershell. Mỗi subcommand đều nhận một đối số shell tùy chọn. Nếu bỏ qua, CLI sẽ tự phát hiện shell của bạn từ môi trường.

Subcommand	Chức năng
generate [shell]	In script completion ra stdout.
install [shell]	Ghi script và cấu hình tệp khởi động shell của bạn.
uninstall [shell]	Xóa script và khối cấu hình.

Khi cài đặt bằng Nix, các completion đã có sẵn: gói flake đi kèm các script Bash, Fish và Zsh tại các vị trí chuẩn, nên không cần install (Cài đặt).

openspec completion generate

In script ra và không ghi tệp nào.

#compdef openspec

# Zsh completion script for OpenSpec CLI
# Auto-generated - do not edit manually

_openspec() {
  local context state line
  typeset -A opt_args
...

openspec completion install

Ghi script và chỉnh sửa tệp cấu hình shell của bạn. Các thay đổi cấu hình nằm giữa hai dấu # OPENSPEC:START và # OPENSPEC:END. Script đã tồn tại sẽ được sao lưu trước (bản sao .backup-<timestamp>).

Shell	Vị trí script	Cấu hình được chỉnh sửa
zsh	~/.zsh/completions/_openspec	$ZDOTDIR/.zshrc khi ZDOTDIR là đường dẫn tuyệt đối, nếu không thì ~/.zshrc
bash	~/.local/share/bash-completion/completions/openspec	~/.bashrc
fish	~/.config/fish/completions/openspec.fish	Không: fish tự động nạp nó.
powershell	OpenSpecCompletion.ps1 bên cạnh profile của bạn	$PROFILE

Nếu Oh My Zsh đã được cài đặt, script sẽ được đặt vào $ZSH_CUSTOM/completions/_openspec thay thế (mặc định là ~/.oh-my-zsh/custom/completions/_openspec).

Giá trị ZDOTDIR là đường dẫn tương đối hoặc có tiền tố ~ sẽ bị bỏ qua, và ~/.zshrc sẽ được chỉnh sửa thay thế. Chạy lại install khi script đã là phiên bản hiện tại vẫn thêm khối vào tệp .zshrc mà zsh đọc.

Tùy chọn

Cờ	Tác dụng
--verbose	Đồng thời hiển thị đường dẫn đã cài đặt, đường dẫn sao lưu (nếu có) và tệp cấu hình nào đã được chỉnh sửa.

Kết quả

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Xóa script và khối cấu hình được đánh dấu. Lệnh sẽ hỏi trước khi can thiệp vào cấu hình của bạn (mặc định: Không).

Đối với zsh, nó dọn dẹp tệp .zshrc mà install chỉnh sửa, và cả ~/.zshrc khi một bản cài đặt cũ đã để lại khối trong đó dưới ZDOTDIR. Nếu không thể xóa khối, uninstall sẽ nêu tên tệp và thoát với mã 1.

Tùy chọn

Cờ	Tác dụng
-y, --yes	Bỏ qua các bước xác nhận.

Kết quả

✓ Completion script removed from /Users/you/.zsh/completions/_openspec. Removed OpenSpec configuration from ~/.zshrc

Mã thoát

• 0: script đã được tạo, cài đặt hoặc xóa. Trường hợp hủy uninstall cũng thoát với mã 0.
• 1: shell không được hỗ trợ hoặc không được phát hiện, hoặc một bước cài đặt/gỡ cài đặt thất bại.

openspec change

Dạng danh từ đã lỗi thời (deprecated) của show, list và validate. Mỗi lần chạy đều hiển thị cảnh báo và chỉ đến các lệnh dạng động từ (verb-first), rồi vẫn tiếp tục chạy:

Warning: The "openspec change ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec list", "openspec validate --changes").
Warning: "openspec change list" is deprecated. Use "openspec list".
add-rate-limit

Đã lỗi thời	Sử dụng thay thế
openspec change show <name>	openspec show <name>
openspec change list	openspec list
openspec change validate <name>	openspec validate <name> (tất cả các change: openspec validate --changes)

Các cờ được mô tả trong các mục về lệnh dạng động từ.

openspec spec

Dạng danh từ đã lỗi thời (deprecated) của show, list và validate. Mỗi lần chạy đều hiển thị cảnh báo và chỉ đến các lệnh dạng động từ (verb-first), rồi vẫn tiếp tục chạy:

Warning: The "openspec spec ..." commands are deprecated. Prefer verb-first commands (e.g., "openspec show", "openspec validate --specs").
api

Đã lỗi thời	Sử dụng thay thế
openspec spec show <id>	openspec show <id>
openspec spec list	openspec list --specs
openspec spec validate <id>	openspec validate <id> (tất cả các spec: openspec validate --specs)

Các cờ được mô tả trong các mục về lệnh dạng động từ.