Tham khảo CLI

OpenSpec CLI (openspec) cung cấp các lệnh terminal cho việc thiết lập dự án, xác thực, kiểm tra trạng thái và quản lý. Các lệnh này bổ sung cho các lệnh slash của AI (như /opsx:propose) được tài liệu hóa trong Commands.

Tổng quan

Danh mục	Lệnh	Mục đích
Thiết lập	`init`, `update`	Khởi tạo và cập nhật OpenSpec trong dự án của bạn
Stores (các repo OpenSpec độc lập)	`store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor`	Quản lý các store — các repo OpenSpec độc lập mà bạn đã đăng ký
Tình trạng	`doctor`	Báo cáo tình trạng mối quan hệ cho root đã được phân giải
Bối cảnh làm việc	`context`	Lắp ráp bộ làm việc (root + các store được tham chiếu)
Bộ làm việc cá nhân	`workset create`, `workset list`, `workset open`, `workset remove`	Lưu và mở các góc nhìn làm việc cá nhân, cục bộ trong công cụ của bạn
Duyệt	`list`, `view`, `show`	Khám phá các thay đổi và specs
Xác thực	`validate`	Kiểm tra các thay đổi và specs để tìm lỗi
Chu kỳ sống	`archive`	Hoàn tất các thay đổi đã hoàn thành
Quy trình làm việc	`new change`, `status`, `instructions`, `templates`, `schemas`	Hỗ trợ quy trình làm việc dựa trên artifact
Schemas	`schema init`, `schema fork`, `schema validate`, `schema which`	Tạo và quản lý các quy trình làm việc tùy chỉnh
Cấu hình	`config`	Xem và sửa đổi cài đặt
Tiện ích	`feedback`, `completion`	Phản hồi và tích hợp shell

Lệnh Người dùng vs Agent

Hầu hết các lệnh CLI được thiết kế để người dùng sử dụng trong terminal. Một số lệnh cũng hỗ trợ sử dụng bởi agent/script thông qua đầu ra JSON.

Lệnh chỉ dành cho Người dùng

Các lệnh này mang tính tương tác và được thiết kế để sử dụng trong terminal:

Lệnh	Mục đích
`openspec init`	Khởi tạo dự án (các lời nhắc tương tác)
`openspec view`	Bảng điều khiển tương tác
`openspec workset open <name>`	Mở một workset đã lưu (cửa sổ trình soạn thảo hoặc phiên làm việc của terminal agent)
`openspec config edit`	Mở cấu hình trong trình soạn thảo
`openspec feedback`	Gửi phản hồi qua GitHub
`openspec completion install`	Cài đặt hoàn thành dòng lệnh (shell completions)

Lệnh tương thích với Agent

Các lệnh này hỗ trợ đầu ra --json để sử dụng lập trình bởi AI agents và scripts:

Lệnh	Sử dụng bởi Người dùng	Sử dụng bởi Agent
`openspec list`	Duyệt qua các thay đổi/specs	`--json` để lấy dữ liệu có cấu trúc
`openspec show <item>`	Đọc nội dung	`--json` để phân tích cú pháp
`openspec validate`	Kiểm tra các vấn đề	`--all --json` để xác thực hàng loạt
`openspec status`	Xem tiến độ của artifact	`--json` để lấy trạng thái có cấu trúc
`openspec instructions`	Lấy các bước tiếp theo	`--json` để lấy hướng dẫn cho agent
`openspec templates`	Tìm đường dẫn template	`--json` để giải quyết đường dẫn
`openspec schemas`	Liệt kê các schema khả dụng	`--json` để khám phá schema; `--store <id>` để chọn một root đã đăng ký
`openspec store setup <id>`	Tạo và đăng ký một kho lưu trữ cục bộ	`--json` với các đầu vào rõ ràng để lấy kết quả thiết lập có cấu trúc
`openspec store register <path>`	Đăng ký một kho lưu trữ hiện có	`--json` để lấy kết quả đăng ký có cấu trúc
`openspec store unregister <id>`	Hủy đăng ký một kho lưu trữ cục bộ	`--json` để lấy kết quả dọn dẹp có cấu trúc
`openspec store remove <id>`	Xóa thư mục kho lưu trữ cục bộ đã đăng ký	`--yes --json` để xóa không tương tác
`openspec store list`	Duyệt qua các kho lưu trữ đã đăng ký	`--json` để lấy danh sách đăng ký có cấu trúc
`openspec store doctor`	Kiểm tra thiết lập kho lưu trữ cục bộ	`--json` để lấy chẩn đoán có cấu trúc
`openspec new change <id>`	Tạo khung thay đổi cục bộ cho repo	`--json`, cộng thêm `--store <id>` để sử dụng kho lưu trữ đã đăng ký làm root OpenSpec
`openspec workset create [name]`	Soạn một chế độ xem làm việc cá nhân	`--member <path> --json` để soạn không tương tác
`openspec workset list`	Duyệt qua các workset đã lưu	`--json` để lấy chế độ xem có cấu trúc
`openspec workset remove <name>`	Xóa một chế độ xem đã lưu	`--yes --json` để xóa không tương tác

Tùy chọn Toàn cục

Các tùy chọn này hoạt động với tất cả các lệnh:

Tùy chọn	Mô tả
`--version`, `-V`	Hiển thị số phiên bản
`--no-color`	Tắt đầu ra có màu
`--help`, `-h`	Hiển thị trợ giúp cho lệnh

Lệnh Thiết lập

`openspec init`

Khởi tạo OpenSpec trong dự án của bạn. Tạo cấu trúc thư mục và định cấu hình các tích hợp công cụ AI.

Hành vi mặc định sử dụng các giá trị mặc định từ cấu hình toàn cầu: profile core, delivery both, workflows propose, explore, apply, update, sync, archive.

openspec init [path] [options]

Sử dụng --language <language> để thêm hướng dẫn ngôn ngữ vào file openspec/config.yaml của dự án mới. Đối với dự án hiện có, hãy chỉnh sửa trường context trong cấu hình để OpenSpec không ghi đè lên hướng dẫn cụ thể của dự án.

Tham số:

Tham số	Bắt buộc	Mô tả
`path`	Không	Thư mục đích (mặc định: thư mục hiện tại)

Tùy chọn:

Tùy chọn	Mô tả
`--tools <list>`	Định cấu hình các công cụ AI không tương tác. Sử dụng `all`, `none`, hoặc danh sách cách nhau bởi dấu phẩy
`--language <language>`	Viết các artifact bằng ngôn ngữ này khi tạo cấu hình mới
`--force`	Tự động dọn dẹp các tệp cũ mà không cần hỏi
`--profile <profile>`	Ghi đè profile toàn cầu cho lần khởi tạo này (`core` hoặc `custom`)
`--no-animation`	Hiển thị màn hình chào mừng tĩnh thay vì màn hình hoạt hình
`--copilot-cloud`	Thiết lập các tệp coding-agent trên đám mây của GitHub Copilot mà không cần hỏi
`--no-copilot-cloud`	Bỏ qua các tệp coding-agent trên đám mây của GitHub Copilot mà không cần hỏi

--profile custom sử dụng bất kỳ workflow nào đang được chọn trong cấu hình toàn cầu (openspec config profile).

Hoạt hình chào mừng cũng bị bỏ qua khi biến môi trường OPENSPEC_NO_ANIMATION được đặt (bất kỳ giá trị nào, kể cả rỗng), khi NO_COLOR được đặt thành giá trị khác rỗng, hoặc khi tùy chọn giảm chuyển động của hệ điều hành được bật (macOS Reduce Motion, GNOME tắt hoạt hình).

Các ID công cụ được hỗ trợ (--tools) — windsurf cũng được chấp nhận, như một bí danh cho devin: amazon-q, antigravity, auggie, bob, claude, cline, command-code, codeartsagent, codex, devin, forgecode, codebuddy, continue, costrict, crush, cursor, factory, gemini, github-copilot, hermes, iflow, junie, kilocode, kimi, kiro, lingma, minimax-code, vibe, oh-my-pi, opencode, pi, codeassistant, qoder, qwen, rovodev, roocode, trae, zed, zcode, agents

Danh sách này trùng khớp với AI_TOOLS trong src/core/config.ts. Xem Công cụ được hỗ trợ để biết đường dẫn kỹ năng và lệnh cho từng công cụ.

Ví dụ:

bash

# Khởi tạo tương tác
openspec init

# Khởi tạo trong một thư mục cụ thể
openspec init ./my-project

# Không tương tác: định cấu hình cho Claude và Cursor
openspec init --tools claude,cursor

# Không tương tác: định cấu hình kỹ năng MiniMax Code toàn cầu
openspec init --tools minimax-code

# Định cấu hình cho tất cả các công cụ được hỗ trợ
openspec init --tools all

# Ghi đè profile cho lần chạy này
openspec init --profile core

# Bỏ qua lời nhắc và tự động dọn dẹp các tệp cũ
openspec init --force

Những gì nó tạo ra:

openspec/
├── specs/              # Các đặc tả của bạn (nguồn sự thật)
├── changes/            # Các thay đổi đề xuất
└── config.yaml         # Cấu hình dự án

.claude/skills/         # Kỹ năng Claude Code (nếu chọn claude)
.cursor/skills/         # Kỹ năng Cursor (nếu chọn cursor)
.cursor/commands/       # Lệnh OPSX của Cursor (nếu delivery bao gồm commands)
.agents/skills/         # Kỹ năng chia sẻ cho các công cụ tương thích AGENTS.md (nếu chọn agents)
... (các cấu hình công cụ khác)

`openspec update`

Cập nhật các tệp hướng dẫn OpenSpec sau khi nâng cấp CLI. Tạo lại các tệp cấu hình công cụ AI bằng cách sử dụng profile toàn cầu hiện tại, các workflow đã chọn và chế độ delivery của bạn.

openspec update [path] [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`path`	Không	Thư mục đích (mặc định: thư mục hiện tại)

Tùy chọn:

Tùy chọn	Mô tả
`--force`	Buộc cập nhật ngay cả khi các tệp đã là mới nhất

Ví dụ:

bash

# Cập nhật các tệp hướng dẫn sau khi nâng cấp npm
npm install -g @fission-ai/openspec@latest
openspec update

Hãy nâng cấp gói trước tiên. Các tệp hướng dẫn được tạo bởi CLI đã cài đặt, vì vậy việc chạy openspec update trên một bản cài đặt lỗi thời sẽ báo cáo mọi thứ đều mới nhất mà không thêm các workflow mà các bản phát hành mới cung cấp.

Để làm điều đó hiển thị rõ ràng, openspec update sẽ hỏi registry npm xem một CLI mới hơn đã được phát hành chưa. Khi bản của bạn cũ hơn, nó sẽ đề xuất nâng cấp:

text

A newer OpenSpec CLI is available (v1.6.0 → v1.7.0).
  Running from: /usr/local/lib/node_modules/@fission-ai/openspec
? Upgrade to v1.7.0 now? (Y/n)

Trả lời yes và nó sẽ chạy npm install -g @fission-ai/openspec@latest, sau đó chạy lại quá trình cập nhật với CLI mới để các workflow mới được áp dụng trong cùng một lệnh. Nó xác nhận việc nâng cấp bằng cách hỏi phiên bản từ binary đã cài đặt thay vì tin tưởng mã thoát của npm, vì vậy nếu một bản cài đặt khác sớm hơn trên PATH của bạn vẫn đang trả lời, nó sẽ nói với bạn thay vì tuyên bố thành công. Trả lời no và nó in ra lệnh và cập nhật với CLI bạn đang có. Ctrl-C dừng lệnh.

Lời đề xuất chỉ xuất hiện trong một terminal tương tác, và chỉ khi npm sở hữu bản cài đặt — trường hợp duy nhất mà npm install -g thực sự khắc phục được. Mọi thứ khác sẽ nhận được lệnh phù hợp với cách nó được cài đặt:

Cách cài đặt OpenSpec	Những gì bạn nhận được
Cài đặt npm toàn cầu	Lời nhắc, và quá trình nâng cấp tự chạy cho bạn — trong một terminal tương tác; đầu ra được pipe sẽ nhận được lệnh đã in thay thế
Cài đặt pnpm, bun, yarn, hoặc volta toàn cầu	Lệnh riêng của trình quản lý đó: `pnpm add -g …@latest`, `bun add -g …@latest`, `yarn global add …@latest`, hoặc `volta install …@latest`
Là một phần phụ thuộc của dự án	Một ghi chú để cập nhật phần phụ thuộc, vì trình quản lý gói của nó sở hữu lockfile
Bộ nhớ đệm `npx` / `dlx`	`npx @fission-ai/openspec@latest update` — lệnh đó chính là bản cập nhật, vì vậy không có bước thứ hai
Clone từ git	Không có gì — phiên bản của bạn là những gì nhánh nói

Bất cứ khi nào có văn bản được in ra, nó sẽ nêu tên thư mục mà CLI đang chạy được tải từ đó — thứ cần kiểm tra khi bạn đã nâng cấp nhưng một shim lỗi thời vẫn chiếm quyền kiểm soát PATH của bạn.

Nó hỏi registry trong npm_config_registry khi npm xuất nó, và https://registry.npmjs.org trong các trường hợp khác. Không đọc .npmrc: việc để nội dung tệp chọn nơi yêu cầu outbound đi là một luồng đáng tránh, và .npmrc của dự án đi kèm với repository. Trên một mirror riêng, hãy xuất npm_config_registry — hoặc đặt OPENSPEC_NO_UPDATE_CHECK để bỏ qua kiểm tra hoàn toàn. Kiểm tra bị bỏ qua khi CI được đặt thành bất kỳ giá trị nào ngoại trừ giá trị tắt rõ ràng (false, 0, no, off, hoặc rỗng), dưới NODE_ENV=test, và bất cứ khi nào OPENSPEC_NO_UPDATE_CHECK (bất kỳ giá trị nào), DO_NOT_TRACK=1, hoặc OPENSPEC_TELEMETRY=0 được đặt. Nó chạy trước khi cập nhật và có thể làm chậm nó tối đa 1.5 giây — nó từ bỏ sau thời gian đó ngay cả khi mạng làm mất gói tin một cách im lặng, và giữ im lặng khi registry không thể truy cập được.

Cách "mới nhất" được quyết định: các tệp kỹ năng ghi lại phiên bản đã tạo chúng, vì vậy OpenSpec so sánh phiên bản đó với CLI đã cài đặt. Các tệp lệnh không mang dấu phiên bản, vì vậy đối với một công cụ có lệnh nhưng không có kỹ năng (delivery commands), OpenSpec so sánh nội dung tệp với những gì nó sẽ tạo ra ngay bây giờ — các chỉnh sửa đối với các tệp đó được coi là lệch pha và sẽ bị ghi đè. Với delivery skills hoặc both, chỉ phiên bản đã ghi lại được kiểm tra, vì vậy một tệp được chỉnh sửa thủ công có phiên bản vẫn khớp sẽ bị bỏ qua; hãy sử dụng --force để ghi đè nó. Dù bằng cách nào, các tệp được tạo là tài sản của OpenSpec — hãy giữ hướng dẫn của bạn ở nơi khác.

Stores (các kho OpenSpec độc lập)

Beta. Stores và các tính năng được xây dựng trên chúng (references, working context, worksets) là mới; tên lệnh, cờ, định dạng tệp và đầu ra JSON có thể thay đổi giữa các bản phát hành. Để xem hướng dẫn chi tiết theo từng vấn đề, hãy xem hướng dẫn stores.

Một store là một kho OpenSpec độc lập mà bạn đã đăng ký trên máy này — ví dụ như một kho lập kế hoạch hoặc một kho hợp đồng. Việc đăng ký một store cho phép các lệnh thông thường (list, show, status, validate, new change, archive, ...) hoạt động trong đó từ bất kỳ đâu bằng cách truyền --store <id>.

`openspec store setup`

Tạo và đăng ký một store cục bộ. Khi không có đối số nào trong terminal, OpenSpec sẽ hướng dẫn người dùng qua quy trình thiết lập. Agents và scripts nên truyền các đầu vào rõ ràng và sử dụng --json.

bash

openspec store setup [id] [options]

Options:

Option	Description
`--path <path>`	Thư mục nơi store sẽ được đặt (ví dụ `~/openspec/<id>`)
`--remote <url>`	Ghi nhận remote chính thức trong tệp `store.yaml` của store mới
`--init-git`	Khởi tạo kho Git với commit ban đầu (mặc định)
`--no-init-git`	Bỏ qua mọi thao tác Git: không init, không commit ban đầu
`--json`	Xuất ra JSON

Các lần chạy không tương tác (--json, scripts, agents) phải truyền cả store id và --path. Trong terminal tương tác, setup sẽ hỏi vị trí với một gợi ý có thể chỉnh sửa ở một vị trí hiển thị rõ ràng, thuộc quyền sở hữu của người dùng (ví dụ ~/openspec/<id>); nó không bao giờ mặc định vào thư mục dữ liệu được quản lý bởi OpenSpec.

Examples:

bash

openspec store setup
openspec store setup team-context
openspec store setup team-context --path ~/openspec/team-context --no-init-git
openspec store setup team-context --path ~/openspec/team-context --no-init-git --json

`openspec store register`

Đăng ký một thư mục store cục bộ hiện có. Trong giai đoạn beta của stores, một root có thể được đăng ký trước khi bất kỳ thay đổi nào tồn tại, specs đã được áp dụng, hoặc thay đổi đã được lưu trữ; trong trường hợp đó openspec/changes/, openspec/specs/, và openspec/changes/archive/ có thể vắng mặt cho đến khi các lệnh thông thường tạo ra chúng. Một kho chỉ chứa config khai báo store: <id> vẫn là một con trỏ đến store khác và không được đăng ký như một store root trừ khi con trỏ đó bị xóa.

bash

openspec store register [path] [options]

Options:

Option	Description
`--id <id>`	Store id; mặc định là metadata của store hoặc tên thư mục
`--yes`	Xác nhận tạo metadata danh tính store cho một OpenSpec root khỏe mạnh
`--json`	Xuất ra JSON

`openspec store unregister`

Quên một đăng ký store cục bộ mà không xóa tệp.

bash

openspec store unregister <id> [--json]

Sử dụng lệnh này khi một store đã được di chuyển, clone ở nơi khác, hoặc không nên xuất hiện nữa trong OpenSpec trên máy này.

`openspec store remove`

Quên một đăng ký store cục bộ và xóa thư mục cục bộ của nó.

bash

openspec store remove <id> [--yes] [--json]

remove hiển thị chính xác thư mục trước khi xóa trong terminal tương tác. Agents, scripts và các caller JSON phải truyền --yes để xác nhận việc xóa. OpenSpec từ chối xóa một thư mục không chứa metadata store phù hợp.

`openspec store list`

Liệt kê các store đã đăng ký cục bộ.

bash

openspec store list [--json]
openspec store ls [--json]

`openspec store doctor`

Kiểm tra đăng ký store cục bộ, metadata và sự hiện diện của Git.

bash

openspec store doctor [id] [--json]

Doctor chỉ dùng để chẩn đoán; nó báo cáo các root bị thiếu, sự không khớp metadata và trạng thái registry cục bộ không hợp lệ mà không sửa đổi store.

Tham chiếu store từ một dự án

Một kho dự án có thể khai báo các store mà công việc của nó dựa vào trong openspec/config.yaml:

yaml

schema: spec-driven
references:
  - team-context

Từ đó trở đi, đầu ra của openspec instructions trong kho đó (cả bề mặt per-artifact và apply, chế độ JSON và chế độ người dùng) sẽ mang theo một chỉ mục specs của mỗi store được tham chiếu — spec ids, một dòng tóm tắt từ phần Purpose của mỗi spec, và lệnh fetch (openspec show <spec-id> --type spec --store <id>). Chỉ mục được xây dựng trực tiếp từ checkout đã đăng ký trong mỗi lần chạy; nội dung spec không bao giờ được sao chép vào đầu ra.

References là ngữ cảnh chỉ đọc. Chúng không bao giờ thay đổi nơi các lệnh hoạt động: công việc vẫn nằm trong root của chính kho, và việc ghi vào một store được tham chiếu vẫn là một hành động --store rõ ràng. Một reference không thể được phân giải (ví dụ, một store chưa được đăng ký trên máy này) sẽ bị giảm xuống thành một cảnh báo trong chỉ mục kèm theo cách sửa chính xác, và instructions vẫn được tạo. openspec doctor báo cáo sức khỏe của references ở một nơi duy nhất.

Ghi nhận nguồn clone của một store

Một store có thể ghi nhận nguồn clone chính thức của nó trong tệp danh tính được commit, để việc onboarding không bao giờ bị tắc ở bước "đăng ký store":

bash

openspec store setup team-context --path ~/openspec/team-context \
  --remote git@github.com:acme/team-context.git

Remote được đặt vào .openspec-store/store.yaml bên trong commit ban đầu, để mọi clone đều biết ngay từ khi sinh ra. Đối với một store hiện có, hãy chỉnh sửa store.yaml thủ công và commit. store doctor hiển thị remote đã ghi nhận (và Git origin quan sát được của checkout); hướng dẫn chia sẻ của setup/register nêu tên nó; và register ghi nhận origin của checkout vào registry cục bộ của máy.

Một khai báo reference cũng có thể mang theo nguồn clone, để một đồng nghiệp chưa có store nhận được một cách sửa hoàn chỉnh, có thể dán ngay (git clone <remote> <path> && openspec store register <path> --id <id>):

yaml

references:
  - { id: team-context, remote: "git@github.com:acme/team-context.git" }

Ghi nhận remote không phải là đồng bộ: OpenSpec không bao giờ tự clone, pull hay push.

Khai báo một store mặc định

Một kho mà việc lập kế hoạch hoàn toàn được ngoại bộ hóa — không có openspec/specs/ hoặc openspec/changes/ cục bộ — có thể khai báo store của nó một lần thay vì truyền --store cho mỗi lệnh:

yaml

# openspec/config.yaml (tệp duy nhất dưới openspec/)
store: team-context

Các lệnh thông thường sau đó sẽ tự động phân giải đến store đã khai báo; banner root và khối JSON root báo cáo source: "declared" kèm store id, và các gợi ý in ra vẫn mang --store <id>. Khai báo này là một phương án dự phòng, không bao giờ là ghi đè: --store rõ ràng luôn thắng, và một thư mục có các thư mục lập kế hoạch thực sự sẽ bỏ qua con trỏ (kèm cảnh báo). Để chuyển một kho con trỏ thành một OpenSpec root cục bộ, hãy xóa dòng store: và chạy openspec init — init từ chối scaffold khi khai báo còn tồn tại.

Một biến thể cấp máy bao phủ mọi kho cùng lúc: openspec config set defaultStore <id> (xem Configuration). Nó chỉ được tham vấn sau khi --store, một root cục bộ và một con trỏ dự án đều không phân giải được; banner root và khối JSON root sau đó báo cáo source: "global_default".

Doctor (sức khỏe liên kết)

Một câu hỏi chỉ đọc, một nơi: liệu gốc OpenSpec có khỏe mạnh không, và các store mà nó tham chiếu có sẵn trên máy này không?

bash

openspec doctor [--store <id>] [--json]

Báo cáo phân tách sức khỏe gốc, sức khỏe metadata của store (bao gồm ghi chú khi remote được ghi lại và origin của nhánh checkout khác nhau, và ghi chú khi nhánh checkout của store đã bị tụt lại phía sau so với ref theo dõi upstream được tải lần cuối), và sức khỏe tham chiếu (các hướng dẫn chẩn đoán tương tự hiển thị, với các bản sửa clone cho các tham chiếu chưa được giải quyết). Các phát hiện về sức khỏe ở bất kỳ mức độ nghiêm trọng nào đều thoát với mã 0 — các agent đọc các mảng status; chỉ các lỗi lệnh (không có gốc, store không xác định) mới thoát với mã 1. Doctor không bao giờ clone, đồng bộ, hay sửa chữa. Để lấy chính tập hợp đã được lắp ráp thay vì sức khỏe của nó, hãy dùng openspec context.

Ngữ cảnh làm việc (tập hợp đã được lắp ráp)

Mọi thứ công việc này liên quan đến thông qua các khai báo OpenSpec, trong một tập hợp làm việc: gốc OpenSpec và các store mà nó tham chiếu.

bash

openspec context [--store <id>] [--json] [--code-workspace <path> [--force]]

Bản tóm tắt JSON có thể được tiêu thụ bởi agent (mỗi store được tham chiếu có sẵn mang theo công thức tải về của nó; các thành viên chưa được giải quyết mang theo cùng các hướng dẫn sửa và hiển thị của doctor). --code-workspace còn ghi thêm một tệp workspace VS Code chứa gốc cùng với các store được tham chiếu có sẵn (các thư mục ref:<id>) — lần ghi duy nhất mà lệnh này thực hiện, bị từ chối mà không có --force nếu tệp đã tồn tại. Các thành viên không có sẵn được báo cáo, không bao giờ đoán.

"Ngữ cảnh làm việc" là tập hợp đã được lắp ráp; trường context: trong openspec/config.yaml là bối cảnh dự án được đưa vào các chỉ thị — hai thứ khác nhau. openspec doctor trả lời liệu tập hợp có khỏe mạnh không; openspec context trả lời tập hợp đó là gì.

Worksets cá nhân

Beta. Worksets là một phần của bề mặt beta mới; các lệnh, cờ và định dạng tệp có thể thay đổi giữa các phiên bản. Để có hướng dẫn, hãy xem hướng dẫn stores.

Một workset là một khung nhìn cá nhân, được đặt tên của các thư mục bạn làm việc cùng nhau — một gốc lập kế hoạch cùng với bất kỳ thứ gì bạn chọn — được lưu trên máy của bạn và mở lại bằng tên trong công cụ của bạn. Nó hoàn toàn cục bộ: không bao giờ được commit, không bao giờ được chia sẻ, không bao giờ được sinh ra từ các khai báo, và việc xóa một workset không bao giờ chạm vào một thư mục thành viên.

bash

openspec workset create [name] [--member <path> | --member <name>=<path>]... [--tool <id>] [--json]
openspec workset list [--json]
openspec workset open <name> [--tool <id>]
openspec workset remove <name> [--yes] [--json]

create chạy một luồng hướng dẫn ngắn (hoặc nhận các cờ --member không tương tác; thành viên đầu tiên là chính — các phiên làm việc bắt đầu tại đó). open khởi chạy công cụ đã chọn: các trình soạn thảo (VS Code, Cursor) mở một cửa sổ với mỗi thành viên và trả về; các agent CLI (Claude Code, codex) chiếm terminal này như một phiên làm việc với mỗi thành viên được gắn kèm và không có lời nhắc nào được điền sẵn, kết thúc khi bạn thoát. Một thư mục thành viên bị thiếu tại thời điểm mở sẽ bị bỏ qua với một ghi chú; phần còn lại mở ra. Tùy chọn công cụ đã lưu có thể được ghi đè mỗi lần mở bằng --tool.

Việc hỗ trợ một công cụ mới là cấu hình, không phải mã. Mỗi công cụ thuộc một trong hai kiểu khởi chạy — workspace-file (được khởi chạy với tệp .code-workspace được sinh ra) hoặc attach-dirs (một cờ đính kèm cho mỗi thành viên) — và khóa openers trong config.json toàn cục (mở nó bằng openspec config edit) thêm các công cụ hoặc điều chỉnh các công cụ có sẵn theo từng trường:

json

{
  "openers": {
    "zed": { "style": "workspace-file" },
    "claude": { "attach_flag": "--dir" }
  }
}

Tất cả trạng thái workset nằm trong thư mục worksets/ của thư mục dữ liệu toàn cục (các khung nhìn đã lưu cộng với các tệp <name>.code-workspace được sinh ra, được tạo lại mỗi lần mở); xóa thư mục đó sẽ xóa mọi dấu vết.

Các lệnh duyệt

`openspec list`

Liệt kê các thay đổi hoặc đặc tả trong dự án của bạn.

openspec list [options]

Tùy chọn:

Tùy chọn	Mô tả
`--specs`	Liệt kê các đặc tả thay vì các thay đổi
`--changes`	Liệt kê các thay đổi (mặc định)
`--sort <order>`	Sắp xếp theo `recent` (gần đây) hoặc `name` (tên)
`--json`	Xuất ra dưới dạng JSON

Ví dụ:

bash

# Liệt kê tất cả các thay đổi đang hoạt động
openspec list

# Liệt kê tất cả các đặc tả
openspec list --specs

# Xuất JSON cho tập lệnh
openspec list --json

Kết quả (văn bản):

Changes:
  add-dark-mode     No tasks      just now

`openspec view`

Hiển thị một bảng điều khiển tương tác để khám phá các đặc tả và thay đổi.

openspec view

Mở một giao diện dựa trên terminal để điều hướng các đặc tả và thay đổi của dự án của bạn.

`openspec show`

Hiển thị chi tiết của một thay đổi hoặc đặc tả.

openspec show [item-name] [options]

Đối số:

Đối số	Bắt buộc	Mô tả
`item-name`	Không	Tên của thay đổi hoặc đặc tả (nhắc nếu bỏ qua)

Tùy chọn:

Tùy chọn	Mô tả
`--type <type>`	Chỉ định kiểu: `change` hoặc `spec` (tự động phát hiện nếu không mơ hồ)
`--json`	Xuất ra dưới dạng JSON
`--no-interactive`	Tắt nhắc nhở

Tùy chọn dành riêng cho thay đổi:

Tùy chọn	Mô tả
`--deltas-only`	Chỉ hiển thị các delta spec (chế độ JSON)

Tùy chọn dành riêng cho đặc tả:

Tùy chọn	Mô tả
`--requirements`	Chỉ hiển thị các yêu cầu, loại trừ kịch bản (chế độ JSON)
`--no-scenarios`	Loại trừ nội dung kịch bản (chế độ JSON)
`-r, --requirement <id>`	Hiển thị yêu cầu cụ thể theo chỉ mục bắt đầu từ 1 (chế độ JSON)

Ví dụ:

bash

# Lựa chọn tương tác
openspec show

# Hiển thị một thay đổi cụ thể
openspec show add-dark-mode

# Hiển thị một đặc tả cụ thể
openspec show auth --type spec

# Xuất JSON cho phân tích
openspec show add-dark-mode --json

Lệnh Xác thực

`openspec validate`

Xác thực các thay đổi và spec về các vấn đề cấu trúc, và kiểm tra các yêu cầu MODIFIED của một thay đổi so với các spec chính mà chúng sẽ thay thế.

openspec validate [item-name] [options]

Một thay đổi có số delta spec bằng không sẽ không vượt qua xác thực trừ khi .openspec.yaml của nó khai báo skip_specs: true (cho các refactor thuần túy, công cụ, hoặc công việc tài liệu — xem Recipe 5).

Tham số:

Tham số	Bắt buộc	Mô tả
`item-name`	Không	Mục cụ thể cần xác thực (hỏi nếu bỏ qua)

Tùy chọn:

Tùy chọn	Mô tả
`--all`	Xác thực tất cả các thay đổi và spec
`--changes`	Xác thực tất cả các thay đổi
`--specs`	Xác thực tất cả các spec
`--archived`	Xác thực rằng các thay đổi đã lưu trữ có tất cả các tác vụ hoàn thành (cho linting pre-commit)
`--type <type>`	Chỉ định loại khi tên không rõ ràng: `change` hoặc `spec`
`--strict`	Bật chế độ xác thực nghiêm ngặt
`--json`	Xuất ra dưới dạng JSON
`--concurrency <n>`	Số xác thực song song tối đa (mặc định: 6, hoặc biến môi trường `OPENSPEC_CONCURRENCY`)
`--no-interactive`	Vô hiệu hóa các lời nhắc

--archived là phạm vi riêng: nó không xác thực các delta spec (đã được áp dụng khi lưu trữ), nó xác minh rằng mọi thay đổi dưới changes/archive/ đều có tất cả các checkbox trong tasks.md được đánh dấu, thoát với mã khác không nếu có bất kỳ cái nào chưa được đánh dấu. Điều này bắt các thay đổi đã được lưu trữ với công việc chưa hoàn thành — hữu ích trong một pre-commit hook.

Ví dụ:

bash

# Xác thực tương tác
openspec validate

# Xác thực một thay đổi cụ thể
openspec validate add-dark-mode

# Xác thực tất cả các thay đổi
openspec validate --changes

# Xác thực tất cả với đầu ra JSON (cho CI/script)
openspec validate --all --json

# Xác thực nghiêm ngặt với độ song song tăng
openspec validate --all --strict --concurrency 12

# Thất bại nếu bất kỳ thay đổi nào đã lưu trữ vẫn còn tác vụ chưa đánh dấu
openspec validate --archived

Đầu ra (text):

Validating add-dark-mode...
  ✓ proposal.md valid
  ✓ specs/ui/spec.md valid
  ⚠ design.md: missing "Technical Approach" section

Tìm thấy 1 cảnh báo

Đầu ra (JSON):

json

{
  "version": "1.0.0",
  "results": {
    "changes": [
      {
        "name": "add-dark-mode",
        "valid": true,
        "warnings": ["design.md: missing 'Technical Approach' section"]
      }
    ]
  },
  "summary": {
    "total": 1,
    "valid": 1,
    "invalid": 0
  }
}

Lệnh Vòng đời

`openspec archive`

Lưu trữ một thay đổi đã hoàn thành và hợp nhất các delta spec vào các spec chính.

openspec archive [change-name] [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`change-name`	Không	Thay đổi cần lưu trữ (hỏi nếu bỏ qua; bắt buộc khi không có gì có thể trả lời lời nhắc)

Tùy chọn:

Tùy chọn	Mô tả
`-y, --yes`	Bỏ qua các lời nhắc xác nhận. Bắt buộc khi không có gì có thể trả lời — một AI agent, một CI job, hoặc bất kỳ lần chạy nào có stdin đóng
`--skip-specs`	Bỏ qua cập nhật spec cho một lần lưu trữ. Một thay đổi vĩnh viễn không có delta spec nên khai báo `skip_specs: true` trong `.openspec.yaml` của nó thay vào đó — nó lưu trữ không cần cờ
`--no-validate`	Bỏ qua xác thực (yêu cầu xác nhận). Cũng vô hiệu hóa việc ngừng sử dụng năng lực — không có phán quyết xác thực, không có gì bị ngừng sử dụng

Ví dụ:

bash

# Lưu trữ tương tác (hỏi thay đổi nào, sau đó xác nhận)
openspec archive

# Lưu trữ thay đổi cụ thể
openspec archive add-dark-mode

# Lưu trữ không cần lời nhắc (agents, CI, scripts)
openspec archive add-dark-mode --yes

# Lưu trữ thay đổi công cụ không ảnh hưởng đến spec
openspec archive update-ci-config --skip-specs

Ngừng sử dụng một năng lực: Thêm dấu hiệu ngừng sử dụng vào metadata của thay đổi:

yaml

# openspec/changes/retire-legacy/.openspec.yaml
schema: spec-driven
retire_capabilities: true

Sau đó lưu trữ thay đổi bình thường:

bash

openspec archive retire-legacy --yes

Khi thay đổi xóa yêu cầu cuối cùng của năng lực, OpenSpec sẽ xóa spec.md đang hoạt động của nó. Các delta năng lực khác trong cùng thay đổi vẫn cập nhật spec chính của chúng. Không có dấu hiệu, lưu trữ sẽ dừng trước khi thay đổi bất kỳ tệp nào và báo cho bạn biết cần thêm nó.

Nó làm gì:

Xác thực thay đổi (trừ khi --no-validate)
Hỏi xác nhận (trừ khi --yes)
Nắm giữ đích lưu trữ trước khi thay đổi bất kỳ spec chính nào
Xác thực và hợp nhất các delta spec đang hoạt động vào openspec/specs/ — một năng lực mà thay đổi xóa yêu cầu cuối cùng của nó sẽ bị ngừng sử dụng, và tệp spec của nó bị xóa, nhưng chỉ khi .openspec.yaml của thay đổi khai báo retire_capabilities: true bên cạnh schema: của nó
Di chuyển thư mục thay đổi vào openspec/changes/archive/YYYY-MM-DD-<name>/
Nếu một đột biến spec hoặc di chuyển cuối cùng thất bại trước khi có một bản lưu trữ hoàn chỉnh, khôi phục các spec và để lại hoặc trả lại thay đổi tại đường dẫn hoạt động của nó
Nếu một bản sao dự phòng đã xác minh hoàn thành nhưng dọn dẹp nguồn đã staged thất bại, giữ lại bản lưu trữ hoàn chỉnh và trạng thái spec đã cam kết để phục hồi

Không có terminal: một AI agent, một CI job, hoặc bất kỳ lần chạy nào có stdin đóng không thể trả lời bước 2, vì vậy lưu trữ sẽ dừng trước khi chạm vào bất cứ thứ gì, thoát với mã 1, và nêu tên lệnh để chạy lại — openspec archive <name> --yes, mang theo bất kỳ cờ nào khác bạn đã truyền. Truyền --yes (và tên thay đổi) ngay từ đầu để bỏ qua vòng lặp.

Lệnh Workflow

Các lệnh này hỗ trợ quy trình làm việc OPSX dựa trên các artifact. Chúng hữu ích cho cả con người kiểm tra tiến độ và các tác nhân (agents) xác định các bước tiếp theo.

`openspec new change`

Tạo thư mục thay đổi (change directory) và siêu dữ liệu (metadata) tùy chọn đã được commit vào gốc OpenSpec đã xác định.

bash

openspec new change <name> [options]

Tên thay đổi phải sử dụng dạng kebab-case chữ thường: chữ cái thường, số và dấu gạch ngang đơn. Tên không được chứa khoảng trắng, dấu gạch dưới, chữ hoa, dấu gạch ngang liên tiếp hoặc dấu gạch ngang ở đầu/cuối. Cho phép bắt đầu bằng số, vì vậy bạn có thể thêm tiền tố để sắp xếp hoặc phân loại các thay đổi, ví dụ 100-add-feature hoặc 00001-add-auth.

Tùy chọn:

Tùy chọn	Mô tả
`--description <text>`	Mô tả để thêm vào `index.md`
`--goal <text>`	Siêu dữ liệu mục tiêu tùy chọn để lưu trữ cùng với thay đổi
`--schema <name>`	Schema workflow để sử dụng
`--store <id>`	ID kho lưu trữ để sử dụng làm gốc OpenSpec (một kho lưu trữ là một repo OpenSpec độc lập mà bạn đã đăng ký)
`--json`	Xuất kết quả dưới dạng JSON

Ví dụ:

bash

openspec new change add-billing-api
openspec new change add-billing-api --store team-context --json

`openspec status`

Hiển thị trạng thái hoàn thành artifact cho một thay đổi.

openspec status [options]

Tùy chọn:

Tùy chọn	Mô tả
`--change <id>`	Tên thay đổi (hỏi nếu bỏ qua)
`--schema <name>`	Ghi đè schema (tự động phát hiện từ cấu hình của thay đổi)
`--json`	Xuất kết quả dưới dạng JSON

Ví dụ:

bash

# Kiểm tra trạng thái tương tác
openspec status

# Trạng thái cho thay đổi cụ thể
openspec status --change add-dark-mode

# JSON để tác nhân sử dụng
openspec status --change add-dark-mode --json

Kết quả (văn bản):

Change: add-dark-mode
Schema: spec-driven
Progress: 2/4 artifacts complete

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

Một thay đổi khai báo skip_specs: true sẽ hiển thị giai đoạn specs của nó là [~] specs (skipped: change declares skip_specs) và loại trừ nó khỏi đếm tiến độ.

Kết quả (JSON):

json

{
  "changeName": "add-dark-mode",
  "schemaName": "spec-driven",
  "isPlanningComplete": false,
  "isComplete": false,
  "applyRequires": ["tasks"],
  "artifacts": [
    {"id": "proposal", "outputPath": "proposal.md", "status": "done", "requires": []},
    {"id": "specs", "outputPath": "specs/**/*.md", "status": "done", "requires": ["proposal"]},
    {"id": "design", "outputPath": "design.md", "status": "ready", "requires": ["proposal"]},
    {"id": "tasks", "outputPath": "tasks.md", "status": "blocked", "requires": ["specs", "design"], "missingDeps": ["design"]}
  ]
}

isPlanningComplete báo cáo xem mọi artifact lập kế hoạch (không bị bỏ qua) có tồn tại hay không; các artifact bị bỏ qua được tính là đã thỏa mãn mà không cần tạo ra. Nó không báo cáo xem các nhiệm vụ triển khai đã hoàn thành hay chưa. isComplete được giữ lại như một bí danh tương thích với cùng giá trị.

Các artifact được liệt kê theo thứ tự phụ thuộc - một dependency không bao giờ xuất hiện sau thứ yêu cầu nó - và các artifact trở nên sẵn sàng cùng lúc (specs và design của spec-driven đều chỉ cần proposal) sẽ giữ nguyên thứ tự mà schema khai báo chúng thay vì thứ tự bảng chữ cái. Vì vậy, mục ready đầu tiên là artifact cần viết tiếp theo.

`openspec instructions`

Nhận hướng dẫn chi tiết để tạo một artifact hoặc áp dụng các nhiệm vụ. Được sử dụng bởi các tác nhân AI để hiểu những gì cần tạo tiếp theo.

openspec instructions [artifact] [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`artifact`	Không	ID Artifact, hoặc bề mặt đầu vào workflow: `apply` hoặc `archive`

Tùy chọn:

Tùy chọn	Mô tả
`--change <id>`	Tên thay đổi (bắt buộc trong chế độ không tương tác)
`--schema <name>`	Ghi đè schema
`--json`	Xuất kết quả dưới dạng JSON

Trường hợp đặc biệt: Sử dụng apply để nhận hướng dẫn triển khai nhiệm vụ. Sử dụng archive để lấy các đầu vào archive hiện tại, chỉ đọc (context và operationGuidance) cho một thay đổi hợp lệ; nó không thực hiện lưu trữ hoặc thay đổi bất kỳ thứ gì.

Ví dụ:

bash

# Nhận hướng dẫn cho artifact tiếp theo
openspec instructions --change add-dark-mode

# Nhận hướng dẫn cho artifact cụ thể
openspec instructions design --change add-dark-mode

# Nhận hướng dẫn apply/triển khai
openspec instructions apply --change add-dark-mode

# Nhận các đầu vào hoạt động archive hiện tại mà không lưu trữ
openspec instructions archive --change add-dark-mode --json

# JSON để tác nhân tiêu thụ
openspec instructions design --change add-dark-mode --json

Kết quả bao gồm:

Nội dung mẫu cho artifact
Ngữ cảnh dự án từ cấu hình
Nội dung từ các artifact phụ thuộc
Quy tắc cho từng artifact từ cấu hình
Ngữ cảnh dự án hiện tại và hướng dẫn hoạt động phù hợp cho apply/archive

Đầu vào hoạt động được đọc từ repo đã giải quyết hoặc kho lưu trữ được chọn trong mỗi lần gọi. Ngữ cảnh dự án là một đầu vào bắt buộc ở mức prompt: các tác nhân đọc nó và áp dụng các sự thật, quy ước và ràng buộc dự án liên quan. Hướng dẫn hoạt động là lời khuyên bổ sung tùy chọn: các tác nhân xem xét mọi mục và chỉ tuân theo các mục phù hợp và tương thích với workflow tích hợp sẵn. Cả hai trường đều tách biệt với các lựa chọn rõ ràng của người dùng, trạng thái được điều khiển bởi CLI, hướng dẫn tích hợp sẵn và quy tắc artifact. Ngữ cảnh xung đột được báo cáo; hướng dẫn xung đột hoặc không phù hợp sẽ không được tuân theo và lý do sẽ được giải thích. Đây là các hợp đồng hành vi cho các tác nhân được tạo ra, không phải là các kiểm tra CLI có thể thực thi. instructions archive chỉ trả về thay đổi đã chọn, các đầu vào tùy chọn và metadata gốc; nó không bao gồm workflow archive tĩnh.

Đối với một artifact bị bỏ qua thông qua skip_specs: true, kết quả chỉ là một cảnh báo (JSON thêm các trường skipped/warning) — artifact không được tạo ra.

`openspec templates`

Hiển thị đường dẫn template đã giải quyết cho tất cả các artifact trong một schema.

openspec templates [options]

Tùy chọn:

Tùy chọn	Mô tả
`--schema <name>`	Schema để kiểm tra (mặc định: `spec-driven`)
`--json`	Xuất kết quả dưới dạng JSON

Ví dụ:

bash

# Hiển thị đường dẫn template cho schema mặc định
openspec templates

# Hiển thị template cho schema tùy chỉnh
openspec templates --schema my-workflow

# JSON để sử dụng chương trình
openspec templates --json

Kết quả (văn bản):

Schema: spec-driven

Templates:
  proposal  → ~/.openspec/schemas/spec-driven/templates/proposal.md
  specs     → ~/.openspec/schemas/spec-driven/templates/specs.md
  design    → ~/.openspec/schemas/spec-driven/templates/design.md
  tasks     → ~/.openspec/schemas/spec-driven/templates/tasks.md

`openspec schemas`

Liệt kê các schema workflow khả dụng với mô tả và luồng artifact của chúng.

openspec schemas [options]

Tùy chọn:

Tùy chọn	Mô tả
`--json`	Xuất kết quả dưới dạng JSON
`--store <id>`	Sử dụng một kho lưu trữ đã đăng ký làm gốc OpenSpec

Ví dụ:

bash

openspec schemas

Kết quả:

Available schemas:

  spec-driven (package)
    The default spec-driven development workflow
    Flow: proposal → specs → design → tasks

  my-custom (project)
    Custom workflow for this project
    Flow: research → proposal → tasks

Lệnh Schema

Các lệnh để tạo và quản lý các schema workflow tùy chỉnh.

`openspec schema init`

Tạo một schema cục bộ cho dự án mới.

openspec schema init <name> [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`name`	Có	Tên schema (kebab-case)

Tùy chọn:

Tùy chọn	Mô tả
`--description <text>`	Mô tả schema
`--artifacts <list>`	Danh sách ID artifact phân cách bằng dấu phẩy (mặc định: `proposal,specs,design,tasks`)
`--default`	Đặt làm schema mặc định của dự án
`--no-default`	Không hỏi đặt làm mặc định
`--force`	Ghi đè schema hiện có
`--json`	Xuất dưới dạng JSON

Ví dụ:

bash

# Tạo schema tương tác
openspec schema init research-first

# Tạo không tương tác với các artifact cụ thể
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Những gì được tạo:

openspec/schemas/<name>/
├── schema.yaml           # Định nghĩa schema
└── templates/
    ├── proposal.md       # Mẫu cho mỗi artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

Sao chép một schema hiện có vào dự án của bạn để tùy chỉnh.

openspec schema fork <source> [name] [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`source`	Có	Schema cần sao chép
`name`	Không	Tên schema mới (mặc định: `<source>-custom`)

Tùy chọn:

Tùy chọn	Mô tả
`--force`	Ghi đè đích hiện có
`--json`	Xuất dưới dạng JSON

Ví dụ:

bash

# Fork schema spec-driven tích hợp sẵn
openspec schema fork spec-driven my-workflow

`openspec schema validate`

Kiểm tra cấu trúc và các mẫu của schema.

openspec schema validate [name] [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`name`	Không	Schema cần kiểm tra (kiểm tra tất cả nếu bỏ qua)

Tùy chọn:

Tùy chọn	Mô tả
`--verbose`	Hiển thị các bước kiểm tra chi tiết
`--json`	Xuất dưới dạng JSON

Ví dụ:

bash

# Kiểm tra một schema cụ thể
openspec schema validate my-workflow

# Kiểm tra tất cả các schema
openspec schema validate

`openspec schema which`

Hiển thị vị trí mà một schema được phân giải từ (hữu ích để gỡ lỗi thứ tự ưu tiên).

openspec schema which [name] [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`name`	Không	Tên schema

Tùy chọn:

Tùy chọn	Mô tả
`--all`	Liệt kê tất cả các schema cùng nguồn của chúng
`--json`	Xuất dưới dạng JSON

Ví dụ:

bash

# Kiểm tra nguồn gốc của một schema
openspec schema which spec-driven

Đầu ra:

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

Thứ tự ưu tiên của schema:

Dự án: openspec/schemas/<name>/
Người dùng: ~/.local/share/openspec/schemas/<name>/
Gói: Các schema tích hợp sẵn

Lệnh Cấu hình

`openspec config`

Xem và sửa đổi cấu hình toàn cục của OpenSpec.

openspec config <subcommand> [options]

Lệnh con:

Lệnh con	Mô tả
`path`	Hiển thị vị trí tệp cấu hình
`list`	Hiển thị tất cả các cài đặt hiện tại
`get <key>`	Lấy một giá trị cụ thể
`set <key> <value>`	Đặt một giá trị
`unset <key>`	Xóa một khóa
`reset`	Đặt lại về mặc định
`edit`	Mở trong `$EDITOR`
`profile [preset]`	Cấu hình hồ sơ workflow tương tác hoặc qua preset

Ví dụ:

bash

# Hiển thị đường dẫn tệp cấu hình
openspec config path

# Liệt kê tất cả các cài đặt
openspec config list

# Lấy một giá trị cụ thể
openspec config get telemetry.enabled

# Đặt một giá trị (vô hiệu hóa đo lường sử dụng ẩn danh)
openspec config set telemetry.enabled false

# Đặt một giá trị chuỗi rõ ràng
openspec config set user.name "My Name" --string

# Xóa một cài đặt tùy chỉnh
openspec config unset user.name

# Đặt kho lưu trữ mặc định cấp máy (gốc dự phòng khi không có --store,
# gốc cục bộ, hoặc kho dự án: con trỏ được phân giải)
openspec config set defaultStore team-plans

# Đặt lại tất cả cấu hình
openspec config reset --all --yes

# Sửa cấu hình trong trình soạn thảo của bạn
openspec config edit

# Cấu hình hồ sơ với trình hướng dẫn dựa trên hành động
openspec config profile

# Preset nhanh: chuyển workflow sang core (giữ chế độ giao hàng)
openspec config profile core

Tùy chọn đo lường: telemetry.enabled mặc định bật khi chưa được đặt (mô hình opt-out). Đặt thành false để vô hiệu hóa thống kê sử dụng ẩn danh và kiểm tra phiên bản openspec update. Biến môi trường có ưu tiên cao hơn cấu hình: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, và giá trị CI chân lý (ví dụ: true/1/yes) luôn vô hiệu hóa đo lường bất kể giá trị cấu hình.

openspec config profile bắt đầu với tóm tắt trạng thái hiện tại, sau đó cho phép bạn chọn:

Thay đổi giao hàng + workflow
Chỉ thay đổi giao hàng
Chỉ thay đổi workflow
Giữ cài đặt hiện tại (thoát)

Nếu bạn giữ cài đặt hiện tại, không có thay đổi nào được ghi và không hiển thị lời nhắc cập nhật. Nếu không có thay đổi cấu hình nhưng các tệp dự án hiện tại không đồng bộ với hồ sơ/giao hàng toàn cục của bạn, OpenSpec sẽ hiển thị cảnh báo và gợi ý openspec update. Nhấn Ctrl+C cũng hủy luồng một cách sạch sẽ (không có stack trace) và thoát với mã 130. Trong danh sách kiểm tra workflow, [x] có nghĩa là workflow được chọn trong cấu hình toàn cục. Để áp dụng các lựa chọn đó vào tệp dự án, chạy openspec update (hoặc chọn Apply changes to this project now? khi được hỏi bên trong một dự án).

Ví dụ tương tác:

bash

# Chỉ cập nhật giao hàng
openspec config profile
# chọn: Change delivery only
# chọn giao hàng: Skills only

# Chỉ cập nhật workflow
openspec config profile
# chọn: Change workflows only
# bật/tắt workflow trong danh sách kiểm tra, sau đó xác nhận

Lệnh Tiện ích

`openspec feedback`

Gửi phản hồi về OpenSpec. Tạo một issue trên GitHub.

openspec feedback <message> [options]

Tham số:

Tham số	Bắt buộc	Mô tả
`message`	Có	Tóm tắt phản hồi; văn bản dài sẽ được rút ngắn trong tiêu đề issue và được giữ nguyên trong nội dung

Tùy chọn:

Tùy chọn	Mô tả
`--body <text>`	Chi tiết bổ sung được bao gồm sau phần tóm tắt

Yêu cầu: GitHub CLI (gh) phải được cài đặt và xác thực.

Ví dụ:

bash

openspec feedback "Add support for custom artifact types" \
  --body "I'd like to define my own artifact types beyond the built-in ones."

`openspec completion`

Quản lý hoàn thành lệnh shell cho CLI OpenSpec.

openspec completion <subcommand> [shell]

Lệnh con:

Lệnh con	Mô tả
`generate [shell]`	Xuất script hoàn thành ra stdout
`install [shell]`	Cài đặt hoàn thành cho shell của bạn
`uninstall [shell]`	Gỡ bỏ hoàn thành đã cài đặt

Các shell được hỗ trợ: bash, zsh, fish, powershell

Ví dụ:

bash

# Cài đặt hoàn thành (tự động phát hiện shell)
openspec completion install

# Cài đặt cho shell cụ thể
openspec completion install zsh

# Tạo script để cài đặt thủ công (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

# Gỡ cài đặt
openspec completion uninstall

Windows (PowerShell): Cài đặt hoàn thành cho host PowerShell hiện tại:

powershell

$env:PROFILE = $PROFILE
openspec completion install powershell
. $PROFILE

$env:PROFILE cho OpenSpec biết hồ sơ nào cần cấu hình trong phiên này. Trình cài đặt tạo các thư mục hồ sơ bị thiếu và thêm một khối được quản lý để tải OpenSpecCompletion.ps1. Nạp lại hồ sơ sẽ kích hoạt hoàn thành ngay lập tức.

Để gỡ cài đặt từ host hiện tại, chạy:

powershell

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

Khởi động lại PowerShell sau khi gỡ cài đặt để xóa hoàn thành khỏi phiên hiện tại.

Hoàn thành là tùy chọn. CLI nhắc một lần duy nhất, trên stderr, lần đầu tiên bạn chạy lệnh trong terminal tương tác, và không bao giờ nhắc lại — nó cũng giữ im lặng nếu bạn đã có hoàn thành được cài đặt. Đặt OPENSPEC_NO_COMPLETIONS=1 để ngăn chặn hoàn toàn lời nhắc đó.

Mã Thoát

Mã	Ý nghĩa
`0`	Thành công
`1`	Lỗi (thất bại kiểm tra, thiếu tệp, v.v.)

Biến Môi trường

Biến	Mô tả
`OPENSPEC_TELEMETRY`	Đặt thành `0` để vô hiệu hóa đo lường và kiểm tra phiên bản `openspec update` (ghi đè `telemetry.enabled` trong cấu hình toàn cục)
`DO_NOT_TRACK`	Đặt thành `1` để vô hiệu hóa đo lường và kiểm tra phiên bản `openspec update` (tín hiệu DNT chuẩn; ghi đè cấu hình)
`OPENSPEC_CONCURRENCY`	Độ song song mặc định cho kiểm tra hàng loạt (mặc định: 6)
`EDITOR` hoặc `VISUAL`	Trình soạn thảo cho `openspec config edit`
`NO_COLOR`	Vô hiệu hóa đầu ra màu khi được đặt
`OPENSPEC_NO_ANIMATION`	Vô hiệu hóa hoạt ảnh chào mừng của `openspec init` khi được đặt
`OPENSPEC_NO_COMPLETIONS`	Đặt thành `1` để ngăn chặn lời nhắc một lần về hoàn thành shell
`OPENSPEC_NO_UPDATE_CHECK`	Vô hiệu hóa kiểm tra `openspec update` cho CLI mới hơn đã phát hành khi được đặt (bất kỳ giá trị nào, bao gồm rỗng). Cũng bị bỏ qua khi `CI` được đặt (trừ khi `false`/`0`/`no`/`off`) hoặc `NODE_ENV=test`
`npm_config_registry`	Registry mà kiểm tra phiên bản `openspec update` truy vấn. Phải là URL `http(s)` hoặc nó sẽ quay về `https://registry.npmjs.org`. Không đọc tệp `.npmrc`

Tài liệu liên quan

Commands - Lệnh slash AI (/opsx:propose, /opsx:apply, v.v.)
Workflows - Các mẫu phổ biến và khi nào sử dụng từng lệnh
Customization - Tạo schema và mẫu tùy chỉnh
Getting Started - Hướng dẫn cài đặt lần đầu

Tham khảo CLI ​

Tổng quan ​

Lệnh Người dùng vs Agent ​

Lệnh chỉ dành cho Người dùng ​

Lệnh tương thích với Agent ​

Tùy chọn Toàn cục ​

Lệnh Thiết lập ​

openspec init ​

openspec update ​

Stores (các kho OpenSpec độc lập) ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

Tham chiếu store từ một dự án ​

Ghi nhận nguồn clone của một store ​

Khai báo một store mặc định ​

Doctor (sức khỏe liên kết) ​

Ngữ cảnh làm việc (tập hợp đã được lắp ráp) ​

Worksets cá nhân ​

Các lệnh duyệt ​

openspec list ​

openspec view ​

openspec show ​

Lệnh Xác thực ​

openspec validate ​

Lệnh Vòng đời ​

openspec archive ​

Lệnh Workflow ​

openspec new change ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

Lệnh Schema ​

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

Lệnh Cấu hình ​

openspec config ​

Lệnh Tiện ích ​

openspec feedback ​

openspec completion ​

Mã Thoát ​

Biến Môi trường ​

Tài liệu liên quan ​

Tham khảo CLI

Tổng quan

Lệnh Người dùng vs Agent

Lệnh chỉ dành cho Người dùng

Lệnh tương thích với Agent

Tùy chọn Toàn cục

Lệnh Thiết lập

`openspec init`

`openspec update`

Stores (các kho OpenSpec độc lập)

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

Tham chiếu store từ một dự án

Ghi nhận nguồn clone của một store

Khai báo một store mặc định

Doctor (sức khỏe liên kết)

Ngữ cảnh làm việc (tập hợp đã được lắp ráp)

Worksets cá nhân

Các lệnh duyệt

`openspec list`

`openspec view`

`openspec show`

Lệnh Xác thực

`openspec validate`

Lệnh Vòng đời

`openspec archive`

Lệnh Workflow

`openspec new change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

Lệnh Schema

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

Lệnh Cấu hình

`openspec config`

Lệnh Tiện ích

`openspec feedback`

`openspec completion`

Mã Thoát

Biến Môi trường

Tài liệu liên quan