CLI Reference

CLI ของ OpenSpec (openspec) ให้คำสั่งสำหรับเทอร์มินัลในการตั้งค่าโปรเจกต์ การตรวจสอบความถูกต้อง การตรวจสอบสถานะ และการจัดการ คำสั่งเหล่านี้เป็นเครื่องมือเสริมสำหรับคำสั่งแบบสแลชของ AI (เช่น /opsx:propose) ที่อธิบายไว้ใน Commands

สรุป

หมวดหมู่	คำสั่ง	วัตถุประสงค์
การตั้งค่า	`init`, `update`	เริ่มต้นและอัปเดต OpenSpec ในโปรเจกต์ของคุณ
ที่เก็บข้อมูล (repo OpenSpec แบบแยก)	`store setup`, `store register`, `store unregister`, `store remove`, `store list`, `store doctor`	จัดการที่เก็บข้อมูล — repo OpenSpec แบบแยกที่คุณได้ลงทะเบียนไว้
สุขภาพระบบ	`doctor`	รายงานสถานะความสัมพันธ์ของรากที่ถูกระบุ
บริบทการทำงาน	`context`	ประกอบชุดงานทำงาน (root + ที่เก็บข้อมูลที่อ้างอิงถึง)
ชุดงานส่วนบุคคล	`workset create`, `workset list`, `workset open`, `workset remove`	รักษาและเปิดมุมมองการทำงานเฉพาะบุคคลในเครื่องของคุณภายในเครื่องมือ
การเรียกดู	`list`, `view`, `show`	สำรวจการเปลี่ยนแปลงและข้อกำหนด
การตรวจสอบความถูกต้อง	`validate`	ตรวจสอบการเปลี่ยนแปลงและข้อกำหนดเพื่อหาปัญหา
วงจรชีวิต	`archive`	ปิดจบการเปลี่ยนแปลงที่เสร็จสมบูรณ์
เวิร์กโฟลว์	`new change`, `status`, `instructions`, `templates`, `schemas`	สนับสนุนเวิร์กโฟลว์ที่ขับเคลื่อนด้วยอาร์ติแฟกต์
สคีมา	`schema init`, `schema fork`, `schema validate`, `schema which`	สร้างและจัดการเวิร์กโฟลว์ที่กำหนดเอง
การกำหนดค่า	`config`	ดูและปรับเปลี่ยนการตั้งค่า
ยูทิลิตี้	`feedback`, `completion`	ข้อเสนอแนะและการผสานรวมกับเชลล์

คำสั่งสำหรับมนุษย์ vs Agent

คำสั่ง CLI ส่วนใหญ่ถูกออกแบบมาเพื่อ การใช้งานโดยมนุษย์ ในเทอร์มินัล บางคำสั่งรองรับการใช้งานโดย agent/script ผ่านการส่งออกข้อมูลแบบ JSON

คำสั่งเฉพาะสำหรับมนุษย์

คำสั่งเหล่านี้เป็นการโต้ตอบแบบ interactive และออกแบบมาสำหรับการใช้งานในเทอร์มินัล:

คำสั่ง	วัตถุประสงค์
`openspec init`	เริ่มต้นโปรเจกต์ (มี prompt แบบ interactive)
`openspec view`	แดชบอร์ดแบบ interactive
`openspec workset open <name>`	เปิด workset ที่บันทึกไว้ (หน้าต่าง editor หรือเซสชัน agent ในเทอร์มินัล)
`openspec config edit`	เปิด config ใน editor
`openspec feedback`	ส่ง feedback ผ่าน GitHub
`openspec completion install`	ติดตั้ง shell completions

คำสั่งที่รองรับ Agent

คำสั่งเหล่านี้รองรับการส่งออกข้อมูลแบบ --json เพื่อการใช้งานเชิงโปรแกรมโดย AI agents และ scripts:

คำสั่ง	การใช้งานโดยมนุษย์	การใช้งานโดย Agent
`openspec list`	ดูรายการ changes/specs	`--json` สำหรับข้อมูลแบบ structured
`openspec show <item>`	อ่านเนื้อหา	`--json` สำหรับ parsing
`openspec validate`	ตรวจสอบปัญหา	`--all --json` สำหรับ validation แบบ bulk
`openspec status`	ดูความคืบหน้าของ artifact	`--json` สำหรับ status แบบ structured
`openspec instructions`	รับขั้นตอนถัดไป	`--json` สำหรับคำแนะนำ agent
`openspec templates`	ค้นหาเส้นทาง template	`--json` สำหรับ path resolution
`openspec schemas`	แสดงรายการ schemas ที่มีอยู่	`--json` สำหรับ schema discovery; `--store <id>` เพื่อเลือก registered root
`openspec store setup <id>`	สร้างและลงทะเบียน local store	`--json` พร้อม explicit inputs สำหรับผลลัพธ์การตั้งค่าแบบ structured
`openspec store register <path>`	ลงทะเบียน store ที่มีอยู่	`--json` สำหรับผลลัพธ์การลงทะเบียนแบบ structured
`openspec store unregister <id>`	ลบบันทึกการลงทะเบียน local store	`--json` สำหรับผลลัพธ์การทำความสะอาดแบบ structured
`openspec store remove <id>`	ลบโฟลเดอร์ local store ที่ลงทะเบียนไว้	`--yes --json` สำหรับการลบแบบ non-interactive
`openspec store list`	ดูรายการ stores ที่ลงทะเบียนไว้	`--json` สำหรับข้อมูลการลงทะเบียนแบบ structured
`openspec store doctor`	ตรวจสอบการตั้งค่า local store	`--json` สำหรับ diagnostics แบบ structured
`openspec new change <id>`	สร้าง repo-local change scaffolding	`--json`, พร้อม `--store <id>` เพื่อใช้ registered store เป็น OpenSpec root
`openspec workset create [name]`	สร้างมุมมองการทำงานส่วนตัว	`--member <path> --json` สำหรับการประกอบแบบ non-interactive
`openspec workset list`	ดูรายการ worksets ที่บันทึกไว้	`--json` สำหรับมุมมองแบบ structured
`openspec workset remove <name>`	ลบมุมมองที่บันทึกไว้	`--yes --json` สำหรับการลบแบบ non-interactive

ตัวเลือกทั่วไป (Global Options)

ตัวเลือกเหล่านี้ทำงานร่วมกับทุกคำสั่ง:

ตัวเลือก	คำอธิบาย
`--version`, `-V`	แสดงหมายเลขเวอร์ชัน
`--no-color`	ปิดการแสดงผลสี
`--help`, `-h`	แสดงความช่วยเหลือสำหรับคำสั่ง

คำสั่งการตั้งค่า (Setup Commands)

`openspec init`

เริ่มต้น OpenSpec ในโปรเจกต์ของคุณ สร้างโครงสร้างโฟลเดอร์และกำหนดการบูรณาการเครื่องมือ AI

พฤติกรรมเริ่มต้นใช้ค่า default จาก global config: profile core, delivery both, workflows propose, explore, apply, update, sync, archive

openspec init [path] [options]

ใช้ --language <language> เพื่อเพิ่มคำสั่งภาษาใน openspec/config.yaml ของโปรเจกต์ใหม่ สำหรับโปรเจกต์ที่มีอยู่แล้ว ให้แก้ไขฟิลด์ context ใน config เพื่อให้ OpenSpec ไม่เขียนทับคำแนะนำเฉพาะโปรเจกต์

อาร์กิวเมนต์:

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
`path`	ไม่จำเป็น	โฟลเดอร์เป้าหมาย (default: โฟลเดอร์ปัจจุบัน)

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--tools <list>`	กำหนดค่าเครื่องมือ AI แบบ non-interactive ใช้ `all`, `none`, หรือรายการที่คั่นด้วยเครื่องหมายจุลภาค
`--language <language>`	เขียน artifacts เป็นภาษานี้เมื่อสร้าง config ใหม่
`--force`	ทำความสะอาดไฟล์ legacy อัตโนมัติโดยไม่ต้องถาม
`--profile <profile>`	ครอบคลุม global profile สำหรับ init ครั้งนี้ (`core` หรือ `custom`)
`--no-animation`	แสดงหน้าต้อนรับแบบนิ่งแทนแบบแอนิเมชัน
`--copilot-cloud`	ตั้งค่า GitHub Copilot cloud coding-agent files โดยไม่ต้องถาม
`--no-copilot-cloud`	ข้ามไฟล์ cloud coding-agent ของ GitHub Copilot โดยไม่ต้องถาม

--profile custom ใช้ workflows ที่เลือกไว้ใน global config (openspec config profile)

แอนิเมชันต้อนรับจะถูกข้ามเมื่อตัวแปรสภาพแวดล้อม OPENSPEC_NO_ANIMATION ถูกตั้งค่า (ค่าใดก็ได้ รวมถึงค่าว่าง), เมื่อ NO_COLOR ถูกตั้งค่าเป็นค่าที่ไม่ว่าง, หรือเมื่อการตั้งค่าลดการเคลื่อนไหวของ OS ถูกเปิดใช้งาน (macOS Reduce Motion, GNOME animations disabled)

Tool IDs ที่รองรับ (--tools) — windsurf ก็ยอมรับเช่นกัน ในฐานะ alias ของ 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

รายการนี้สะท้อน AI_TOOLS ใน src/core/config.ts ดู Supported Tools สำหรับ skill และ command paths ของแต่ละเครื่องมือ

ตัวอย่าง:

bash

# เริ่มต้นแบบ interactive
openspec init

# เริ่มต้นในโฟลเดอร์เฉพาะ
openspec init ./my-project

# Non-interactive: กำหนดค่าสำหรับ Claude และ Cursor
openspec init --tools claude,cursor

# Non-interactive: กำหนดค่า global MiniMax Code skills
openspec init --tools minimax-code

# กำหนดค่าสำหรับทุกเครื่องมือที่รองรับ
openspec init --tools all

# ครอบคลุม profile สำหรับครั้งนี้
openspec init --profile core

# ข้าม prompts และทำความสะอาดไฟล์ legacy อัตโนมัติ
openspec init --force

สิ่งที่ถูกสร้าง:

openspec/
├── specs/              # ข้อกำหนดของคุณ (source of truth)
├── changes/            # การเปลี่ยนแปลงที่เสนอ
└── config.yaml         # การตั้งค่าโปรเจกต์

.claude/skills/         # Claude Code skills (ถ้าเลือก claude)
.cursor/skills/         # Cursor skills (ถ้าเลือก cursor)
.cursor/commands/       # Cursor OPSX commands (ถ้า delivery รวม commands)
.agents/skills/         # Skills ร่วมสำหรับเครื่องมือที่รองรับ AGENTS.md (ถ้าเลือก agents)
... (การตั้งค่าเครื่องมืออื่น ๆ)

`openspec update`

อัปเดตไฟล์คำแนะนำของ OpenSpec หลังจากอัปเกรด CLI สร้างไฟล์การตั้งค่าเครื่องมือ AI ใหม่โดยใช้ global profile, workflows ที่เลือกไว้, และ delivery mode ปัจจุบันของคุณ

openspec update [path] [options]

อาร์กิวเมนต์:

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
`path`	ไม่จำเป็น	โฟลเดอร์เป้าหมาย (default: โฟลเดอร์ปัจจุบัน)

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--force`	บังคับอัปเดตแม้ว่าไฟล์จะอัปเดตแล้ว

ตัวอย่าง:

bash

# อัปเดตไฟล์คำแนะนำหลังอัปเกรด npm
npm install -g @fission-ai/openspec@latest
openspec update

อัปเกรดแพ็กเกจก่อน ไฟล์คำแนะนำถูกสร้างโดย CLI ที่ติดตั้งไว้ ดังนั้นการรัน openspec update กับเวอร์ชันเก่าจะรายงานทุกอย่างว่าอัปเดตแล้วโดยไม่เพิ่ม workflows ใหม่ที่เวอร์ชันใหม่ส่งมา

เพื่อให้เรื่องนี้ชัดเจน openspec update จะสอบถาม npm registry ว่ามี CLI เวอร์ชันใหม่กว่าถูกเผยแพร่หรือไม่ เมื่อเวอร์ชันของคุณล้าหลัง มันจะเสนอให้อัปเกรด:

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)

ตอบ yes แล้วมันจะรัน npm install -g @fission-ai/openspec@latest จากนั้นรัน update ใหม่ด้วย CLI ใหม่เพื่อให้ workflows ใหม่ถูกเพิ่มในคำสั่งเดียว มันยืนยันการอัปเกรดโดยสอบถามเวอร์ชันจาก binary ที่ติดตั้งไว้แทนการเชื่อถือ exit code ของ npm ดังนั้นถ้าการติดตั้งอื่นใน PATH ของคุณยังตอบอยู่ มันจะบอกคุณแทนการอ้างว่าสำเร็จ ตอบ no แล้วมันจะพิมพ์คำสั่งและอัปเดตด้วย CLI ที่มีอยู่ Ctrl-C หยุดคำสั่ง

ข้อเสนอปรากฏเฉพาะในเทอร์มินัลแบบ interactive และเฉพาะเมื่อ npm เป็นเจ้าของการติดตั้ง — กรณีเดียวที่ npm install -g แก้ได้จริง กรณีอื่น ๆ จะได้คำสั่งที่ตรงกับวิธีการติดตั้งแทน:

วิธีที่ OpenSpec ถูกติดตั้ง	สิ่งที่คุณได้รับ
ติดตั้ง global ผ่าน npm	Prompt และการอัปเกรดที่รันให้ — ในเทอร์มินัลแบบ interactive; output ที่ถูก pipe จะได้คำสั่งที่พิมพ์แทน
ติดตั้ง global ผ่าน pnpm, bun, yarn, หรือ volta	คำสั่งของ manager นั้นเอง: `pnpm add -g …@latest`, `bun add -g …@latest`, `yarn global add …@latest`, หรือ `volta install …@latest`
เป็น dependency ของโปรเจกต์	ข้อความให้อัปเดต dependency เนื่องจาก package manager ของโปรเจกต์เป็นเจ้าของ lockfile
แคชของ `npx` / `dlx`	`npx @fission-ai/openspec@latest update` — คำสั่งนั้นคือการอัปเดตอยู่แล้ว จึงไม่มีขั้นตอนที่สอง
Git clone	ไม่มีอะไร — เวอร์ชันของคุณคือสิ่งที่ branch บอก

ทุกครั้งที่มีการพิมพ์ มันจะระบุโฟลเดอร์ที่ CLI ที่กำลังรันถูกโหลดจาก — สิ่งที่ต้องตรวจสอบเมื่อคุณอัปเกรดแล้วแต่ stale shim ยังครอบครอง PATH ของคุณ

มันสอบถาม registry ใน npm_config_registry เมื่อ npm export ออกมา และ https://registry.npmjs.org ในกรณีอื่น ๆ ไม่มีการอ่าน .npmrc: การให้เนื้อหาไฟล์เลือกปลายทางของคำขอ outbound เป็น flow ที่ควรหลีกเลี่ยง และ .npmrc ของโปรเจกต์เดินทางไปกับ repository บน private mirror ให้ export npm_config_registry — หรือตั้งค่า OPENSPEC_NO_UPDATE_CHECK เพื่อข้ามการตรวจสอบทั้งหมด การตรวจสอบจะถูกข้ามเมื่อ CI ถูกตั้งค่าเป็นค่าใดก็ได้ที่ไม่ใช่ค่าปิดชัดเจน (false, 0, no, off, หรือว่าง), ภายใต้ NODE_ENV=test, และเมื่อใดก็ตามที่ OPENSPEC_NO_UPDATE_CHECK (ค่าใดก็ได้), DO_NOT_TRACK=1, หรือ OPENSPEC_TELEMETRY=0 ถูกตั้งค่า มันรันก่อนการอัปเดตและอาจทำให้ล่าช้าได้ไม่เกิน 1.5 วินาที — มันยอมแพ้หลังจากนั้นแม้ว่าเครือข่ายจะ drop packets แบบเงียบ ๆ และเงียบเมื่อ registry เข้าถึงไม่ได้

การตัดสินว่า "อัปเดตแล้ว" อย่างไร: skill files บันทึกเวอร์ชันที่สร้างมันไว้ ดังนั้น OpenSpec จะเปรียบเทียบเวอร์ชันนั้นกับ CLI ที่ติดตั้งไว้ Command files ไม่มี version stamp ดังนั้นสำหรับเครื่องมือที่มี commands แต่ไม่มี skills (delivery commands), OpenSpec จะเปรียบเทียบเนื้อหาไฟล์กับสิ่งที่มันจะสร้างตอนนี้ — การแก้ไขไฟล์เหล่านั้นถือเป็น drift และจะถูกเขียนทับ เมื่อ delivery เป็น skills หรือ both, จะตรวจสอบเฉพาะเวอร์ชันที่บันทึกไว้ ดังนั้นไฟล์ที่แก้ไขด้วยมือซึ่งเวอร์ชันยังตรงกันจะถูกละไว้; ใช้ --force เพื่อเขียนทับ ในทุกกรณี ไฟล์ที่สร้างโดยอัตโนมัติเป็นของ OpenSpec — เก็บคำแนะนำของคุณไว้ในที่อื่น

Stores (คลังข้อมูลแบบแยกอิสระที่เป็น repo ของ OpenSpec)

Beta. Stores และฟีเจอร์ที่สร้างบนพื้นฐานของ Stores (references, working context, worksets) เป็นฟีเจอร์ใหม่; ชื่อคำสั่ง, flags, รูปแบบไฟล์, และ JSON output อาจมีการเปลี่ยนแปลงโครงสร้างระหว่างเวอร์ชัน สำหรับ walkthrough แบบ problem-first ดูที่ stores guide

Store คือ repo ของ OpenSpec แบบแยกอิสระที่คุณได้ลงทะเบียนไว้บนเครื่องนี้ — ตัวอย่างเช่น repo สำหรับวางแผนหรือ repo สำหรับสัญญา Registering a store ช่วยให้คำสั่งปกติ (list, show, status, validate, new change, archive, ...) ทำงานใน store นั้นได้จากทุกที่โดยส่ง --store <id>

`openspec store setup`

สร้างและลงทะเบียน store ในเครื่อง ด้วยไม่มีอาร์กิวเมนต์ใน terminal, OpenSpec จะแนะนำผู้ใช้ผ่านกระบวนการตั้งค่า Agents และ scripts ควรส่ง inputs ที่ชัดเจนและใช้ --json

bash

openspec store setup [id] [options]

Options:

Option	Description
`--path <path>`	โฟลเดอร์ที่ store ควรตั้งอยู่ (ตัวอย่างเช่น `~/openspec/<id>`)
`--remote <url>`	บันทึก canonical remote ใน `store.yaml` ของ store ใหม่
`--init-git`	เริ่มต้น Git repository พร้อม initial commit (ค่าเริ่มต้น)
`--no-init-git`	ข้ามทุกการกระทำของ Git: ไม่มี init, ไม่มี initial commit
`--json`	Output JSON

การรันแบบ non-interactive (--json, scripts, agents) ต้องส่งทั้ง store id และ --path ใน interactive terminal, setup จะถามตำแหน่งพร้อมคำแนะนำที่แก้ไขได้ในตำแหน่งที่ผู้ใช้เป็นเจ้าของและมองเห็นได้ชัดเจน (ตัวอย่างเช่น ~/openspec/<id>); จะไม่ default ไปยัง managed data directory ของ OpenSpec

ตัวอย่าง:

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`

ลงทะเบียนโฟลเดอร์ store ที่มีอยู่แล้วในเครื่อง ในช่วง stores beta, root อาจลงทะเบียนได้ก่อนที่ changes จะถูกสร้าง, specs ถูก apply, หรือ changes ถูก archive; ในกรณีนั้น openspec/changes/, openspec/specs/, และ openspec/changes/archive/ อาจยังไม่มีอยู่จนกว่าคำสั่งปกติจะสร้าง它们 A config-only repo ที่ประกาศ store: <id> ยังคงเป็น pointer ไปยัง store อื่นและไม่ถูกลงทะเบียนเป็น store root เว้นแต่ pointer นั้นจะถูกนำออก

bash

openspec store register [path] [options]

Options:

Option	Description
`--id <id>`	Store id; ค่าเริ่มต้นคือ store metadata หรือชื่อโฟลเดอร์
`--yes`	ยืนยันการสร้าง store identity metadata สำหรับ OpenSpec root ที่สมบูรณ์
`--json`	Output JSON

`openspec store unregister`

ลืมการลงทะเบียน store ในเครื่องโดยไม่ลบไฟล์

bash

openspec store unregister <id> [--json]

ใช้คำสั่งนี้เมื่อ store ถูกย้าย, clone ไปยังที่อื่น, หรือไม่ควรแสดงโดย OpenSpec บนเครื่องนี้อีกต่อไป

`openspec store remove`

ลืมการลงทะเบียน store ในเครื่องและลบโฟลเดอร์ในเครื่อง

bash

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

remove จะแสดงโฟลเดอร์ที่แน่นอนก่อนลบใน interactive terminal Agents, scripts, และ JSON callers ต้องส่ง --yes เพื่อยืนยันการลบ OpenSpec จะปฏิเสธการลบโฟลเดอร์ที่ไม่มี store metadata ที่ตรงกัน

`openspec store list`

แสดงรายการ stores ที่ลงทะเบียนในเครื่อง

bash

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

`openspec store doctor`

ตรวจสอบการลงทะเบียน store ในเครื่อง, metadata, และการมีอยู่ของ Git

bash

openspec store doctor [id] [--json]

Doctor เป็นเครื่องมือวินิจฉัยเท่านั้น; รายงาน root ที่หายไป, metadata ที่ไม่ตรงกัน, และ local registry state ที่ไม่ถูกต้องโดยไม่แก้ไข store

การอ้างอิง stores จากโปรเจกต์

repo ของโปรเจกต์สามารถประกาศว่างานของมันอ้างอิง stores ใดใน openspec/config.yaml:

yaml

schema: spec-driven
references:
  - team-context

ตั้งแต่นั้นเป็นต้นไป, openspec instructions output ใน repo นั้น (ทั้ง per-artifact และ apply surfaces, JSON และ human modes) จะประกอบด้วย index ของ specs จากแต่ละ store ที่อ้างอิง — spec ids, สรุปหนึ่งบรรทัดจากส่วน Purpose ของแต่ละ spec, และคำสั่ง fetch (openspec show <spec-id> --type spec --store <id>) Index ถูกสร้างแบบ live จาก registered checkout ทุกครั้งที่รัน; เนื้อหา spec จะไม่ถูกคัดลอกไปยัง output

References เป็นบริบทแบบ read-only เท่านั้น ไม่เปลี่ยนตำแหน่งที่คำสั่งทำงาน: งานยังคงอยู่ใน root ของ repo เอง และการเขียนไปยัง store ที่อ้างอิงยังคงเป็นการกระทำ --store ที่ชัดเจน Reference ที่ไม่สามารถ resolve ได้ (ตัวอย่างเช่น store ที่ไม่ได้ลงทะเบียนบนเครื่องนี้) จะลดระดับเป็น warning ใน index พร้อมวิธีแก้ไขที่แน่นอน และ instructions ยังคงสร้างได้ openspec doctor รายงานสุขภาพของ references ในที่เดียว

การบันทึกแหล่ง clone ของ store

Store สามารถบันทึกแหล่ง clone ที่ถูกต้องใน identity file ที่ commit ไว้ เพื่อให้ onboarding ไม่ติดขัดที่ "register the store":

bash

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

Remote จะถูกบันทึกใน .openspec-store/store.yaml ภายใน initial commit เพื่อให้ทุก clone รู้ตั้งแต่แรกเกิด สำหรับ store ที่มีอยู่แล้ว ให้แก้ไข store.yaml ด้วยตนเองและ commit store doctor จะแสดง remote ที่บันทึกไว้ (และ Git origin ที่สังเกตได้จาก checkout); setup/register sharing guidance จะระบุชื่อมัน; และ register จะบันทึก origin ของ checkout ใน machine-local registry

Reference declaration สามารถนำแหล่ง clone ไปด้วย เพื่อให้เพื่อนร่วมทีมที่ยังไม่มี store ได้รับวิธีแก้ไขที่ครบถ้วนและสามารถ paste ได้ (git clone <remote> <path> && openspec store register <path> --id <id>):

yaml

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

การบันทึก remote ไม่ใช่ sync: OpenSpec จะไม่ clone, pull, หรือ push ด้วยตนเอง

การประกาศ default store

repo ที่การวางแผนถูก externalize ทั้งหมด — ไม่มี openspec/specs/ หรือ openspec/changes/ ในเครื่อง — สามารถประกาศ store ของมันครั้งเดียวแทนการส่ง --store ทุกคำสั่ง:

yaml

# openspec/config.yaml (ไฟล์เดียวภายใต้ openspec/)
store: team-context

คำสั่งปกติจะ resolve ไปยัง store ที่ประกาศโดยอัตโนมัติ; root banner และ JSON root block จะรายงาน source: "declared" พร้อม store id และ printed hints ยังคงประกอบด้วย --store <id> การประกาศนี้เป็น fallback ไม่ใช่ override: --store ที่ชัดเจนจะชนะเสมอ และ directory ที่มีโฟลเดอร์วางแผนจริงจะเพิกเฉย pointer (พร้อม warning) เพื่อแปลง pointer repo เป็น local OpenSpec root ให้ลบบรรทัด store: และรัน openspec init — init จะปฏิเสธการ scaffold ขณะที่การประกาศนี้ยังมีอยู่

แบบ machine-level ครอบคลุมทุก repo ในครั้งเดียว: openspec config set defaultStore <id> (ดู Configuration) จะถูกปรึกษาเฉพาะเมื่อ --store, local root, และ project pointer ล้วนไม่สามารถ resolve ได้; root banner และ JSON root block จะรายงาน source: "global_default"

Doctor (ตรวจสอบสุขภาพความสัมพันธ์)

คำถามแบบอ่านได้อย่างเดียว ในที่เดียว: รากของ OpenSpec มีสุขภาพดีหรือไม่ และสต็อกข้อมูลที่มันอ้างอิงถึงพร้อมใช้งานบนเครื่องนี้หรือไม่?

bash

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

รายงานจะแยกการตรวจสอบสุขภาพของราก, สุขภาพของเมตาดาต้าสต็อก (รวมถึงหมายเหตุเมื่อระยะทางไกลที่บันทึกไว้และต้นทางของการดึงข้อมูลเบี่ยงเบนกัน และหมายเหตุเมื่อการดึงข้อมูลสต็อกล้าหลังกว่าการอ้างอิงติดตามจากแหล่งที่มาล่าสุดที่ได้รับมา), และสุขภาพของการอ้างอิง (คำแนะนำการวินิจฉัยเดียวกันแสดงออกมา พร้อมการแก้ไขการโคลนสำหรับรายการอ้างอิงที่ไม่สามารถแก้ได้) การพบปัญหาสุขภาพที่มีความรุนแรงใดๆ จะออกสถานะ 0 — เอเจนต์จะอ่านอาร์เรย์ status; เฉพาะความล้มเหลวของคำสั่ง (ไม่มีราก, สต็อกไม่รู้จัก) เท่านั้นที่จะออกสถานะ 1. Doctor ไม่ทำการโคลน, ซิงค์ หรือซ่อมแซมเลย หากต้องการได้รับชุดข้อมูลที่ประกอบขึ้นแล้วแทนที่จะเป็นสุขภาพของมัน ให้ใช้ openspec context

Working context (ชุดข้อมูลที่ประกอบขึ้นแล้ว)

ทุกสิ่งที่งานนี้เกี่ยวข้องผ่านคำประกาศของ OpenSpec ในชุดการทำงานชุดเดียว: รากของ OpenSpec และสต็อกข้อมูลที่มันอ้างอิงถึง

bash

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

บทสรุป JSON สามารถบริโภคโดยเอเจนต์ได้ (แต่ละสต็อกอ้างอิงที่พร้อมใช้งานจะมีสูตรการดึงข้อมูลของมัน; สมาชิกที่ยังไม่สามารถแก้ได้จะมีคำแนะนำการแก้ไขเดียวกันและแสดงใน doctor) --code-workspace ยังเขียนไฟล์พื้นที่ทำงานของ VS Code ที่ประกอบด้วยรากบวกกับสต็อกอ้างอิงที่พร้อมใช้งาน (ref:<id> โฟลเดอร์) — การเขียนเพียงครั้งเดียวที่คำสั่งนี้ทำ ปฏิเสธหากไฟล์มีอยู่แล้ว เว้นแต่จะใช้ --force สมาชิกที่ไม่พร้อมใช้งานจะถูกแจ้ง แต่จะไม่มีการคาดเดา

"Working context" คือชุดข้อมูลที่ประกอบขึ้นแล้ว; ฟิลด์ context: ใน openspec/config.yaml เป็นบริบทของโปรเจกต์ที่ถูกฉีดเข้าไปในคำแนะนำ — สองสิ่งที่แตกต่างกัน openspec doctor ตอบคำถามว่าชุดข้อมูลนั้นมีสุขภาพดีหรือไม่; openspec context ตอบคำถามว่าชุดข้อมูลนั้นคืออะไร

Personal worksets

เบตา Worksets เป็นส่วนหนึ่งของพื้นผิวเบตาใหม่; คำสั่ง, แฟลก และรูปแบบไฟล์อาจเปลี่ยนแปลงรูปร่างระหว่างเวอร์ชัน สำหรับการเดินผ่านดู คู่มือสต็อก

Workset คือมุมมองส่วนตัวที่มีชื่อของโฟลเดอร์ที่คุณทำงานร่วมกัน — รากการวางแผนบวกกับอะไรก็ตามที่คุณเลือก — เก็บไว้ในเครื่องของคุณและเปิดใหม่ตามชื่อในเครื่องมือของคุณ มันเป็นแบบโลคอลเท่านั้น: ไม่เคยถูกคอมมิต, ไม่เคยแชร์, ไม่เคยได้มาจากคำประกาศ และการลบหนึ่งรายการไม่เคยกระทบต่อโฟลเดอร์สมาชิก

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 รันขั้นตอนแนะนำสั้นๆ (หรือรับแฟลก --member แบบไม่โต้ตอบ; สมาชิกตัวแรกจะเป็นหลัก — เซสชันจะเริ่มที่นั่น) open เรียกใช้เครื่องมือที่เลือก: ตัวแก้ไข (VS Code, Cursor) เปิดหน้าต่างที่มีสมาชิกทั้งหมดและกลับคืน; เอเจนต์ CLI (Claude Code, codex) เข้าควบคุมเทอร์มินัลนี้เป็นเซสชันที่มีสมาชิกทั้งหมดแนบอยู่และไม่มีการป้อนข้อความล่วงหน้า เริ่มต้นเมื่อคุณออก สมาชิกที่ขาดหายไประหว่างการเปิดจะถูกข้ามพร้อมหมายเหตุ; ส่วนที่เหลือจะเปิด ความชอบเครื่องมือที่บันทึกไว้สามารถปรับแต่งต่อการเปิดแต่ละครั้งด้วย --tool

การรองรับเครื่องมือใหม่เป็นการกำหนดค่า ไม่ใช่โค้ด เครื่องมือแต่ละชนิดเป็นหนึ่งในสองสไตล์การเรียกใช้ — workspace-file (เรียกใช้ด้วย .code-workspace ที่สร้าง) หรือ attach-dirs (แฟลกแนบหนึ่งอันต่อสมาชิก) และคีย์ openers ใน config.json ระดับโลก (เปิดด้วย openspec config edit) เพิ่มเครื่องมือหรือปรับแต่งฟังก์ชันภายในตามฟิลด์:

json

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

สถานะ workset ทั้งหมดอยู่ในโฟลเดอร์ worksets/ ของไดเรกทอรีข้อมูลระดับโลก (มุมมองที่บันทึกไว้บวกกับไฟล์ <name>.code-workspace ที่สร้าง ซึ่งสร้างใหม่ทุกครั้งเมื่อเปิด); การลบโฟลเดอร์นี้จะลบร่องรอยทั้งหมด

คำสั่งสำหรับการเรียกดู

`openspec list`

รายการการเปลี่ยนแปลงหรือข้อกำหนดในโปรเจกต์ของคุณ

openspec list [options]

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--specs`	แสดงรายการข้อกำหนดแทนการเปลี่ยนแปลง
`--changes`	แสดงรายการการเปลี่ยนแปลง (ค่าเริ่มต้น)
`--sort <order>`	เรียงลำดับตาม `recent` (ค่าเริ่มต้น) หรือ `name`
`--json`	เอาต์พุตเป็น JSON

ตัวอย่าง:

bash

# แสดงรายการการเปลี่ยนแปลงที่ใช้งานอยู่ทั้งหมด
openspec list

# แสดงรายการข้อกำหนดทั้งหมด
openspec list --specs

# เอาต์พุต JSON สำหรับสคริปต์
openspec list --json

เอาต์พุต (ข้อความ):

Changes:
  add-dark-mode     No tasks      just now

`openspec view`

แสดงแดชบอร์ดแบบอินเทอร์แอคทีฟสำหรับการสำรวจข้อกำหนดและการเปลี่ยนแปลง

openspec view

เปิดอินเทอร์เฟซฐานเทอร์มินัลสำหรับการนำทางข้อกำหนดและการเปลี่ยนแปลงในโปรเจกต์ของคุณ

`openspec show`

แสดงรายละเอียดของการเปลี่ยนแปลงหรือข้อกำหนด

openspec show [item-name] [options]

อาร์กิวเมนต์:

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
`item-name`	ไม่	ชื่อของการเปลี่ยนแปลงหรือข้อกำหนด (จะถามหากละเว้น)

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--type <type>`	ระบุประเภท: `change` หรือ `spec` (ตรวจจับอัตโนมัติหากไม่กำกวม)
`--json`	เอาต์พุตเป็น JSON
`--no-interactive`	ปิดการใช้งานการถาม

ตัวเลือกเฉพาะสำหรับการเปลี่ยนแปลง:

ตัวเลือก	คำอธิบาย
`--deltas-only`	แสดงเฉพาะข้อกำหนดเดลต้า (โหมด JSON)

ตัวเลือกเฉพาะสำหรับข้อกำหนด:

ตัวเลือก	คำอธิบาย
`--requirements`	แสดงเฉพาะความต้องการ ไม่รวมสถานการณ์ (โหมด JSON)
`--no-scenarios`	ไม่รวมเนื้อหาสถานการณ์ (โหมด JSON)
`-r, --requirement <id>`	แสดงความต้องการเฉพาะตามดัชนี 1-based (โหมด JSON)

ตัวอย่าง:

bash

# การเลือกแบบอินเทอร์แอคทีฟ
openspec show

# แสดงการเปลี่ยนแปลงเฉพาะ
openspec show add-dark-mode

# แสดงข้อกำหนดเฉพาะ
openspec show auth --type spec

# เอาต์พุต JSON สำหรับการวิเคราะห์
openspec show add-dark-mode --json

คำสั่งการตรวจสอบความถูกต้อง (Validation Commands)

`openspec validate`

ตรวจสอบการเปลี่ยนแปลงและสเปกเพื่อหาปัญหาเชิงโครงสร้าง และตรวจสอบข้อกำหนด MODIFIED ของการเปลี่ยนแปลงเทียบกับสเปกหลักที่มันจะแทนที่

openspec validate [item-name] [options]

การเปลี่ยนแปลงที่มี spec deltas เป็นศูนย์จะล้มเหลวในการตรวจสอบความถูกต้อง เว้นแต่ .openspec.yaml ของมันจะระบุ skip_specs: true (สำหรับงาน refactor ล้วนๆ, tooling, หรือเอกสาร — ดู Recipe 5)

อาร์กิวเมนต์:

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
`item-name`	ไม่จำเป็น	รายการเฉพาะที่ต้องการตรวจสอบ (จะถามหากเว้นว่าง)

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--all`	ตรวจสอบการเปลี่ยนแปลงและสเปกทั้งหมด
`--changes`	ตรวจสอบการเปลี่ยนแปลงทั้งหมด
`--specs`	ตรวจสอบสเปกทั้งหมด
`--archived`	ตรวจสอบว่าการเปลี่ยนแปลงที่ถูกเก็บถาวรแล้วมีงานทั้งหมดเสร็จสมบูรณ์ (สำหรับ pre-commit linting)
`--type <type>`	ระบุประเภทเมื่อชื่อกำกวม: `change` หรือ `spec`
`--strict`	เปิดโหมดตรวจสอบความถูกต้องแบบเข้มงวด
`--json`	ออกรูปแบบ JSON
`--concurrency <n>`	จำนวนการตรวจสอบแบบขนานสูงสุด (ค่าเริ่มต้น: 6 หรือ env `OPENSPEC_CONCURRENCY`)
`--no-interactive`	ปิดการถาม

--archived เป็นขอบเขตของมันเอง: มันไม่ตรวจสอบ spec deltas (ซึ่งถูกนำไปใช้แล้วตอนเก็บถาวร) แต่ตรวจสอบว่าทุกการเปลี่ยนแปลงภายใต้ changes/archive/ มี checkboxes ใน tasks.md ถูกติ๊กครบทั้งหมด และจะ exit ด้วยค่าที่ไม่ใช่ศูนย์หากมีอันใดไม่ถูกติ๊ก สิ่งนี้ช่วยจับการเปลี่ยนแปลงที่ถูกเก็บถาวรโดยมีงานที่ยังไม่เสร็จ — มีประโยชน์ใน pre-commit hook

ตัวอย่าง:

bash

# ตรวจสอบแบบ interactive
openspec validate

# ตรวจสอบการเปลี่ยนแปลงเฉพาะ
openspec validate add-dark-mode

# ตรวจสอบการเปลี่ยนแปลงทั้งหมด
openspec validate --changes

# ตรวจสอบทุกอย่างพร้อม output แบบ JSON (สำหรับ CI/scripts)
openspec validate --all --json

# ตรวจสอบแบบเข้มงวดพร้อมเพิ่มจำนวนการประมวลผลแบบขนาน
openspec validate --all --strict --concurrency 12

# ล้มเหลวหากมีการเปลี่ยนแปลงที่ถูกเก็บถาวรแล้วยังมีงานที่ไม่ถูกติ๊ก
openspec validate --archived

ผลลัพธ์ (ข้อความ):

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

1 warning found

ผลลัพธ์ (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
  }
}

คำสั่งวงจรชีวิต (Lifecycle Commands)

`openspec archive`

เก็บถาวรการเปลี่ยนแปลงที่เสร็จสมบูรณ์และรวม delta specs เข้ากับสเปกหลัก

openspec archive [change-name] [options]

อาร์กิวเมนต์:

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
`change-name`	ไม่จำเป็น	การเปลี่ยนแปลงที่ต้องการเก็บถาวร (จะถามหากเว้นว่าง; จำเป็นเมื่อไม่มีอะไรตอบคำถามได้)

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`-y, --yes`	ข้ามการยืนยัน จำเป็นเมื่อไม่มีอะไรตอบคำถามได้ — AI agent, CI job, หรือการรันใดๆ ที่ stdin ปิดอยู่
`--skip-specs`	ข้ามการอัปเดตสเปกสำหรับการเก็บถาวรครั้งเดียว การเปลี่ยนแปลงที่ไม่มี spec deltas อย่างถาวรควรระบุ `skip_specs: true` ใน `.openspec.yaml` แทน — มันจะเก็บถาวรได้โดยไม่ต้องใช้ flag
`--no-validate`	ข้ามการตรวจสอบความถูกต้อง (ต้องมีการยืนยัน) ปิดการเลิกใช้ capability ด้วย — เมื่อไม่มีผลการตรวจสอบ ไม่มีอะไรถูกเลิกใช้

ตัวอย่าง:

bash

# เก็บถาวรแบบ interactive (ถามว่าการเปลี่ยนแปลงใด แล้วยืนยัน)
openspec archive

# เก็บถาวรการเปลี่ยนแปลงเฉพาะ
openspec archive add-dark-mode

# เก็บถาวรโดยไม่ต้องถาม (agents, CI, scripts)
openspec archive add-dark-mode --yes

# เก็บถาวรการเปลี่ยนแปลง tooling ที่ไม่กระทบสเปก
openspec archive update-ci-config --skip-specs

เลิกใช้ capability: เพิ่มเครื่องหมายการเลิกใช้ใน metadata ของการเปลี่ยนแปลง:

yaml

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

จากนั้นเก็บถาวรการเปลี่ยนแปลงตามปกติ:

bash

openspec archive retire-legacy --yes

เมื่อการเปลี่ยนแปลงลบ requirement สุดท้ายของ capability นั้น OpenSpec จะลบ spec.md ที่ใช้งานอยู่ของมัน Delta ของ capability อื่นๆ ในการเปลี่ยนแปลงเดียวกันยังคงอัปเดตสเปกหลักของมัน หากไม่มีเครื่องหมายนี้ archive จะหยุดก่อนเปลี่ยนไฟล์ใดๆ และบอกให้คุณเพิ่มเครื่องหมายนั้น

สิ่งที่มันทำ:

ตรวจสอบความถูกต้องของการเปลี่ยนแปลง (เว้นแต่ใช้ --no-validate)
ถามเพื่อยืนยัน (เว้นแต่ใช้ --yes)
จองปลายทาง archive ก่อนเปลี่ยนสเปกหลักใดๆ
ตรวจสอบและรวม delta specs ที่ใช้งานอยู่เข้ากับ openspec/specs/ — capability ที่ requirement สุดท้ายถูกการเปลี่ยนแปลงลบจะถูกเลิกใช้ และไฟล์ spec ของมันถูกลบ แต่เฉพาะเมื่อ .openspec.yaml ของการเปลี่ยนแปลงระบุ retire_capabilities: true อยู่ข้าง schema:
ย้ายโฟลเดอร์การเปลี่ยนแปลงไปยัง openspec/changes/archive/YYYY-MM-DD-<name>/
หากการแก้ไขสเปกหรือการย้ายสุดท้ายล้มเหลวก่อนที่จะได้ archive ที่สมบูรณ์ จะกู้คืนสเปกและทิ้งหรือคืนการเปลี่ยนแปลงไว้ที่เส้นทางใช้งานเดิม
หาก fallback copy ที่ยืนยันแล้วเสร็จสมบูรณ์แต่การทำความสะอาด staged-source ล้มเหลว จะเก็บ archive ที่สมบูรณ์และสถานะสเปกที่ commit ไว้สำหรับการกู้คืน

เมื่อไม่มี terminal: AI agent, CI job, หรือการรันใดๆ ที่ stdin ปิดอยู่ไม่สามารถตอบขั้นตอนที่ 2 ได้ ดังนั้น archive จะหยุดก่อนแตะอะไรใดๆ exit ด้วยค่า 1 และระบุคำสั่งที่ต้องรันซ้ำ — openspec archive <name> --yes พร้อม flag อื่นๆ ที่คุณส่งมา ส่ง --yes (พร้อมชื่อการเปลี่ยนแปลง) ไว้ตั้งแต่ต้นเพื่อข้ามการวนกลับ

คำสั่ง Workflow

คำสั่งเหล่านี้รองรับ workflow แบบ artifact-driven ของ OPSX มีประโยชน์ทั้งสำหรับมนุษย์ที่ต้องการตรวจสอบความคืบหน้า และสำหรับ agent ที่ต้องการกำหนดขั้นตอนถัดไป

`openspec new change`

สร้างไดเรกทอรีการเปลี่ยนแปลงและ metadata ที่เลือก check-in ไว้ใน OpenSpec root ที่ถูกรับรองแล้ว

bash

openspec new change <name> [options]

ชื่อการเปลี่ยนแปลงต้องใช้ lowercase kebab-case: ตัวอักษรพิมพ์เล็ก ตัวเลข และขีดเดียวเท่านั้น ไม่สามารถมีช่องว่าง เส้นใต้ ตัวอักษรพิมพ์ใหญ่ ขีดติดกัน หรือขีดนำหน้า/ท้ายได้ การนำหน้าด้วยตัวเลขได้รับอนุญาต เพื่อให้สามารถจัดลำดับหรือจัดชั้นการเปลี่ยนแปลงได้ เช่น 100-add-feature หรือ 00001-add-auth

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--description <text>`	คำอธิบายที่จะเพิ่มลงใน `index.md`
`--goal <text>`	Metadata เป้าหมาย (ไม่บังคับ) ที่จะจัดเก็บพร้อมกับ change
`--schema <name>`	Workflow schema ที่จะใช้
`--store <id>`	Store id ที่จะใช้เป็น OpenSpec root (store คือ OpenSpec repo แบบ standalone ที่คุณได้ลงทะเบียนไว้)
`--json`	Output เป็น JSON

ตัวอย่าง:

bash

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

`openspec status`

แสดงสถานะการเสร็จสมบูรณ์ของ artifact สำหรับ change หนึ่ง

openspec status [options]

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--change <id>`	ชื่อ change (จะถามหากไม่ได้ระบุ)
`--schema <name>`	Override schema (ตรวจหาอัตโนมัติจาก config ของ change)
`--json`	Output เป็น JSON

ตัวอย่าง:

bash

# ตรวจสอบสถานะแบบ interactive
openspec status

# สถานะสำหรับ change เฉพาะ
openspec status --change add-dark-mode

# JSON สำหรับ agent ใช้
openspec status --change add-dark-mode --json

Output (ข้อความ):

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

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

Change ที่ประกาศ skip_specs: true จะแสดงขั้นตอน specs เป็น [~] specs (skipped: change declares skip_specs) และไม่นับรวมในจำนวนความคืบหน้า

Output (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 รายงานว่า artifact การวางแผนที่ไม่ได้ skip ทุกตัวมีอยู่ครบหรือไม่ artifact ที่ถูก skip จะนับว่าครบโดยไม่ต้องสร้าง ไม่รายงานว่าการ implement task เสร็จสมบูรณ์หรือยัง isComplete ถูกเก็บไว้เป็น alias ความเข้ากันได้ที่มีค่าเดียวกัน

Artifact จะเรียงตามลำดับ dependency — dependency จะไม่ปรากฏหลังสิ่งที่ต้องการมัน — และ artifact ที่พร้อมพร้อมกัน (เช่น specs และ design ของ spec-driven ต้องการแค่ proposal) จะคงลำดับที่ schema ประกาศไว้ ไม่ใช่เรียงตามตัวอักษร ดังนั้น entry ready ตัวแรกคือ artifact ที่ต้องเขียนถัดไป

`openspec instructions`

รับคำแนะนำที่สมบูรณ์สำหรับการสร้าง artifact หรือการ apply task ใช้โดย AI agent เพื่อทำความเข้าใจว่าต้องสร้างอะไรถัดไป

openspec instructions [artifact] [options]

อาร์กิวเมนต์:

อาร์กิวเมนต์	จำเป็น	คำอธิบาย
`artifact`	ไม่จำเป็น	Artifact ID หรือ workflow input surface: `apply` หรือ `archive`

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--change <id>`	ชื่อ change (จำเป็นในโหมด non-interactive)
`--schema <name>`	Override schema
`--json`	Output เป็น JSON

กรณีพิเศษ: ใช้ apply เพื่อรับคำแนะนำการ implement task ใช้ archive เพื่อดึง archive inputs ปัจจุบันแบบ read-only (context และ operationGuidance) สำหรับ change ที่ถูกต้อง ไม่ได้ archive หรือแก้ไขอะไร

ตัวอย่าง:

bash

# รับคำแนะนำสำหรับ artifact ถัดไป
openspec instructions --change add-dark-mode

# รับคำแนะนำสำหรับ artifact เฉพาะ
openspec instructions design --change add-dark-mode

# รับคำแนะนำการ apply/implement
openspec instructions apply --change add-dark-mode

# รับ archive operation inputs ปัจจุบันโดยไม่ archive
openspec instructions archive --change add-dark-mode --json

# JSON สำหรับ agent ใช้
openspec instructions design --change add-dark-mode --json

Output ประกอบด้วย:

Template content สำหรับ artifact
Project context จาก config
Content จาก dependency artifacts
กฎเฉพาะ artifact จาก config
Project context ปัจจุบันและ operation guidance ที่ตรงกันสำหรับ apply/archive

Operation inputs จะอ่านจาก repo ที่รับรองแล้วหรือ store ที่เลือกในทุกครั้งที่เรียกใช้ Project context เป็น input ระดับ prompt ที่จำเป็น: agent จะอ่านและนำข้อเท็จจริง ธรรมเนียมปฏิบัติ และข้อจำกัดของโปรเจกต์ที่เกี่ยวข้องมาปรับใช้ Operation guidance เป็นคำแนะนำเพิ่มเติมแบบไม่บังคับ: agent จะพิจารณาทุก entry และปฏิบัติตามเฉพาะ entry ที่เกี่ยวข้องและเข้ากันได้กับ workflow ในตัว ทั้งสองฟิลด์ยังคงแยกจากตัวเลือกของผู้ใช้โดยตรง สถานะที่ควบคุมด้วย CLI คำสั่งในตัว และกฎของ artifact Context ที่ขัดแย้งกันจะถูกรายงาน Guidance ที่ขัดแย้งหรือไม่เกี่ยวข้องจะไม่ถูกปฏิบัติตามและจะอธิบายเหตุผล สิ่งเหล่านี้เป็น behavioral contracts สำหรับ agent ที่ถูกสร้าง ไม่ใช่ CLI checks ที่บังคับได้ instructions archive คืนเฉพาะ change ที่เลือก optional inputs และ root metadata เท่านั้น ไม่รวม static archive workflow

สำหรับ artifact ที่ถูก skip ผ่าน skip_specs: true output จะเป็นเพียงคำเตือน (JSON เพิ่มฟิลด์ skipped/warning) — artifact นั้นต้องไม่ถูกสร้าง

`openspec templates`

แสดง template paths ที่รับรองแล้วสำหรับทุก artifact ใน schema

openspec templates [options]

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--schema <name>`	Schema ที่จะตรวจสอบ (ค่าเริ่มต้น: `spec-driven`)
`--json`	Output เป็น JSON

ตัวอย่าง:

bash

# แสดง template paths สำหรับ schema เริ่มต้น
openspec templates

# แสดง templates สำหรับ custom schema
openspec templates --schema my-workflow

# JSON สำหรับใช้แบบ programmatic
openspec templates --json

Output (ข้อความ):

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`

แสดงรายการ workflow schemas ที่มีพร้อมคำอธิบายและ artifact flows

openspec schemas [options]

ตัวเลือก:

ตัวเลือก	คำอธิบาย
`--json`	Output เป็น JSON
`--store <id>`	ใช้ store ที่ลงทะเบียนไว้เป็น OpenSpec root

ตัวอย่าง:

bash

openspec schemas

Output:

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

คำสั่ง Schema

คำสั่งสำหรับสร้างและจัดการ schema ของ workflow แบบกำหนดเอง

`openspec schema init`

สร้าง project-local schema ใหม่

openspec schema init <name> [options]

Arguments:

Argument	Required	Description
`name`	Yes	ชื่อ schema (kebab-case)

Options:

Option	Description
`--description <text>`	คำอธิบาย schema
`--artifacts <list>`	รายการ artifact IDs ที่คั่นด้วยเครื่องหมายจุลภาค (ค่าเริ่มต้น: `proposal,specs,design,tasks`)
`--default`	ตั้งค่าเป็น schema มาตรฐานของโปรเจกต์
`--no-default`	ไม่ถามเพื่อตั้งค่าเป็นค่าเริ่มต้น
`--force`	ทับซ้อน schema ที่มีอยู่
`--json`	แสดงผลลัพธ์ในรูปแบบ JSON

Examples:

bash

# การสร้าง schema แบบโต้ตอบ
openspec schema init research-first

# แบบไม่โต้ตอบพร้อมระบุ artifacts เฉพาะ
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

สิ่งที่สร้างขึ้น:

openspec/schemas/<name>/
├── schema.yaml           # นิยาม Schema
└── templates/
    ├── proposal.md       # เทมเพลตสำหรับแต่ละ artifact
    ├── specs.md
    ├── design.md
    └── tasks.md

`openspec schema fork`

คัดลอก schema ที่มีอยู่ไปยังโปรเจกต์ของคุณเพื่อการปรับแต่ง

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

Arguments:

Argument	Required	Description
`source`	Yes	Schema ที่จะคัดลอก
`name`	No	ชื่อ schema ใหม่ (ค่าเริ่มต้น: `<source>-custom`)

Options:

Option	Description
`--force`	ทับซ้อนปลายทางที่มีอยู่
`--json`	แสดงผลลัพธ์ในรูปแบบ JSON

Example:

bash

# Fork schema spec-driven ในตัว
openspec schema fork spec-driven my-workflow

`openspec schema validate`

ตรวจสอบโครงสร้างและเทมเพลตของ schema

openspec schema validate [name] [options]

Arguments:

Argument	Required	Description
`name`	No	Schema ที่จะตรวจสอบ (จะตรวจสอบทั้งหมดหากเว้นว่าง)

Options:

Option	Description
`--verbose`	แสดงขั้นตอนการตรวจสอบโดยละเอียด
`--json`	แสดงผลลัพธ์ในรูปแบบ JSON

Example:

bash

# ตรวจสอบ schema เฉพาะ
openspec schema validate my-workflow

# ตรวจสอบทุก schema
openspec schema validate

`openspec schema which`

แสดงที่มาของการแก้ไข schema (มีประโยชน์สำหรับการดีบักลำดับความสำคัญ)

openspec schema which [name] [options]

Arguments:

Argument	Required	Description
`name`	No	ชื่อ schema

Options:

Option	Description
`--all`	แสดงรายการ schema ทั้งหมดพร้อมแหล่งที่มา
`--json`	แสดงผลลัพธ์ในรูปแบบ JSON

Example:

bash

# ตรวจสอบที่มาของ schema
openspec schema which spec-driven

Output:

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

ลำดับความสำคัญของ Schema:

Project: openspec/schemas/<name>/
User: ~/.local/share/openspec/schemas/<name>/
Package: Schema ในตัว

คำสั่ง Configuration

`openspec config`

ดูและปรับเปลี่ยนการตั้งค่า OpenSpec ทั่วโลก

openspec config <subcommand> [options]

Subcommands:

Subcommand	Description
`path`	แสดงตำแหน่งไฟล์ config
`list`	แสดงการตั้งค่าปัจจุบันทั้งหมด
`get <key>`	รับค่าเฉพาะ
`set <key> <value>`	ตั้งค่าค่า
`unset <key>`	ลบ key
`reset`	รีเซ็ตกลับเป็นค่าเริ่มต้น
`edit`	เปิดใน `$EDITOR`
`profile [preset]`	กำหนดค่าโปรไฟล์ workflow แบบโต้ตอบหรือผ่าน preset

Examples:

bash

# แสดงเส้นทางไฟล์ config
openspec config path

# แสดงการตั้งค่าทั้งหมด
openspec config list

# รับค่าเฉพาะ
openspec config get telemetry.enabled

# ตั้งค่าค่า (ปิดใช้งาน telemetry การใช้งานแบบนิรนาม)
openspec config set telemetry.enabled false

# ตั้งค่า string อย่างชัดเจน
openspec config set user.name "My Name" --string

# ลบการตั้งค่าที่กำหนดเอง
openspec config unset user.name

# ตั้งค่า default store ระดับเครื่อง (fallback root เมื่อไม่มี --store,
# local root หรือ project store: pointer แก้ไขได้)
openspec config set defaultStore team-plans

# รีเซ็ตการตั้งค่าทั้งหมด
openspec config reset --all --yes

# แก้ไข config ใน editor ของคุณ
openspec config edit

# กำหนดค่า profile ด้วย wizard แบบ action-based
openspec config profile

# Preset เร็ว: สลับ workflows เป็น core (คงโหมด delivery ไว้)
openspec config profile core

การเลือกออกจากการส่ง Telemetry: telemetry.enabled จะตั้งเป็นเปิดเมื่อไม่ได้กำหนด (รูปแบบ opt-out) ตั้งค่าเป็น false เพื่อปิดใช้งานสถิติการใช้งานแบบนิรนามและการตรวจสอบเวอร์ชัน openspec update ตัวแปรสภาพแวดล้อมจะมีลำดับความสำคัญเหนือ config: OPENSPEC_TELEMETRY=0, DO_NOT_TRACK=1, และค่า CI ที่เป็น truthy (เช่น true/1/yes) จะปิดใช้งาน telemetry เสมอโดยไม่คำนึงถึงค่าใน config

openspec config profile เริ่มต้นด้วยการสรุปสถานะปัจจุบัน จากนั้นให้คุณเลือก:

เปลี่ยน delivery + workflows
เปลี่ยนเฉพาะ delivery
เปลี่ยนเฉพาะ workflows
เก็บการตั้งค่าปัจจุบัน (ออก)

หากคุณเก็บการตั้งค่าปัจจุบัน จะไม่มีการเขียนการเปลี่ยนแปลงและไม่แสดง prompt อัปเดต หากไม่มีการเปลี่ยนแปลง config แต่ไฟล์โปรเจกต์ปัจจุบันไม่ตรงกับโปรไฟล์/การส่งข้อมูลระดับโลกของคุณ OpenSpec จะแสดงคำเตือนและแนะนำ openspec update การกด Ctrl+C จะยกเลิกกระบวนการอย่างสะอาด (ไม่มี stack trace) และออกจากโปรแกรมด้วยรหัส 130 ในรายการตรวจสอบ workflow [x] หมายถึง workflow นั้นถูกเลือกในการตั้งค่าระดับ global หากต้องการนำการเลือกเหล่านั้นไปใช้กับไฟล์โปรเจกต์ ให้รัน openspec update (หรือเลือก Apply changes to this project now? เมื่อได้รับแจ้งภายในโปรเจกต์)

Interactive examples:

bash

# อัปเดตเฉพาะ Delivery
openspec config profile
# เลือก: Change delivery only
# เลือก delivery: Skills only

# อัปเดตเฉพาะ Workflows
openspec config profile
# เลือก: Change workflows only
# สลับ workflows ในรายการตรวจสอบ แล้วยืนยัน

คำสั่ง Utility

`openspec feedback`

ส่งความคิดเห็นเกี่ยวกับ OpenSpec สร้าง GitHub issue

openspec feedback <message> [options]

Arguments:

Argument	Required	Description
`message`	Yes	สรุปความคิดเห็น; ข้อความยาวจะถูกย่อในหัวข้อ issue และคงไว้ในส่วนเนื้อหา

Options:

Option	Description
`--body <text>`	รายละเอียดเพิ่มเติมที่รวมหลังจากส่วนสรุป

Requirements: ต้องติดตั้ง GitHub CLI (gh) และเข้าสู่ระบบแล้ว

Example:

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`

จัดการ shell completions สำหรับ OpenSpec CLI

openspec completion <subcommand> [shell]

Subcommands:

Subcommand	Description
`generate [shell]`	ส่งออกสคริปต์ completion ไปยัง stdout
`install [shell]`	ติดตั้ง completion สำหรับ shell ของคุณ
`uninstall [shell]`	ลบการติดตั้ง completions

Shells ที่รองรับ: bash, zsh, fish, powershell

Examples:

bash

# ติดตั้ง completions (ตรวจจับ shell อัตโนมัติ)
openspec completion install

# ติดตั้งสำหรับ shell เฉพาะ
openspec completion install zsh

# สร้างสคริปต์สำหรับการติดตั้งด้วยตนเอง (bash)
openspec completion generate bash > ~/.bash_completion.d/openspec

# ถอนการติดตั้ง
openspec completion uninstall

Windows (PowerShell): ติดตั้ง completions สำหรับโฮสต์ PowerShell ปัจจุบัน:

powershell

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

$env:PROFILE บอก OpenSpec ว่าควรกำหนดค่าโปรไฟล์ใดในเซสชันนี้ ผู้ติดตั้งจะสร้างไดเรกทอรีโปรไฟล์ที่ขาดหายไปและเพิ่มบล็อกที่จัดการซึ่งโหลด OpenSpecCompletion.ps1 การโหลดโปรไฟล์ใหม่จะทำให้ completions ทำงานทันที

หากต้องการถอนการติดตั้งจากโฮสต์ปัจจุบัน ให้รัน:

powershell

$env:PROFILE = $PROFILE
openspec completion uninstall powershell

รีสตาร์ท PowerShell หลังจากถอนการติดตั้งเพื่อล้าง completions จากเซสชันปัจจุบัน

Completions เป็นการเลือกเข้าร่วม (opt-in) CLI จะกล่าวถึงครั้งเดียว บน stderr ครั้งแรกที่คุณ รันคำสั่งในเทอร์มินัลแบบโต้ตอบ และไม่ทำอีกเลย — นอกจากนี้จะไม่แสดงข้อความใดๆ หากคุณติดตั้ง completions อยู่แล้ว ตั้งค่า OPENSPEC_NO_COMPLETIONS=1 เพื่อ ระงับคำแนะนำนั้นทั้งหมด

Exit Codes

Code	Meaning
`0`	สำเร็จ
`1`	เกิดข้อผิดพลาด (การตรวจสอบล้มเหลว ไฟล์หาย ฯลฯ)

Environment Variables

Variable	Description
`OPENSPEC_TELEMETRY`	ตั้งค่าเป็น `0` เพื่อปิดใช้งาน telemetry และการตรวจสอบเวอร์ชัน `openspec update` (แทนที่ `telemetry.enabled` ใน config ทั่วโลก)
`DO_NOT_TRACK`	ตั้งค่าเป็น `1` เพื่อปิดใช้งาน telemetry และการตรวจสอบเวอร์ชัน `openspec update` (สัญญาณ DNT มาตรฐาน; แทนที่ config)
`OPENSPEC_CONCURRENCY`	ความพร้อมใช้งานเริ่มต้นสำหรับการตรวจสอบแบบกลุ่ม (ค่าเริ่มต้น: 6)
`EDITOR` หรือ `VISUAL`	Editor สำหรับ `openspec config edit`
`NO_COLOR`	ปิดเอาต์พุตสีเมื่อตั้งค่า
`OPENSPEC_NO_ANIMATION`	ปิดแอนิเมชันยินดีต้อนรับ `openspec init` เมื่อตั้งค่า
`OPENSPEC_NO_COMPLETIONS`	ตั้งค่าเป็น `1` เพื่อระงับคำแนะนำครั้งเดียวเกี่ยวกับ shell completions
`OPENSPEC_NO_UPDATE_CHECK`	ปิดการตรวจสอบ `openspec update` สำหรับ CLI ที่เผยแพร่ใหม่เมื่อตั้งค่า (ค่าใด ๆ รวมถึงค่าว่าง) จะข้ามการตรวจสอบนี้เมื่อตั้งค่า `CI` ด้วยเช่นกัน (ยกเว้น `false`/`0`/`no`/`off`) หรือ `NODE_ENV=test`
`npm_config_registry`	Registry ที่การตรวจสอบเวอร์ชัน `openspec update` ถาม Must be an `http(s)` URL หรือจะกลับไปใช้ `https://registry.npmjs.org` ไม่มีการอ่านไฟล์ `.npmrc`

เอกสารที่เกี่ยวข้อง

Commands - คำสั่ง AI slash (/opsx:propose, /opsx:apply, ฯลฯ)
Workflows - รูปแบบทั่วไปและเวลาที่เหมาะสมในการใช้คำสั่งแต่ละคำสั่ง
Customization - สร้าง schema และเทมเพลตแบบกำหนดเอง
Getting Started - คู่มือการตั้งค่าครั้งแรก

CLI Reference ​

สรุป ​

คำสั่งสำหรับมนุษย์ vs Agent ​

คำสั่งเฉพาะสำหรับมนุษย์ ​

คำสั่งที่รองรับ Agent ​

ตัวเลือกทั่วไป (Global Options) ​

คำสั่งการตั้งค่า (Setup Commands) ​

openspec init ​

openspec update ​

Stores (คลังข้อมูลแบบแยกอิสระที่เป็น repo ของ OpenSpec) ​

openspec store setup ​

openspec store register ​

openspec store unregister ​

openspec store remove ​

openspec store list ​

openspec store doctor ​

การอ้างอิง stores จากโปรเจกต์ ​

การบันทึกแหล่ง clone ของ store ​

การประกาศ default store ​

Doctor (ตรวจสอบสุขภาพความสัมพันธ์) ​

Working context (ชุดข้อมูลที่ประกอบขึ้นแล้ว) ​

Personal worksets ​

คำสั่งสำหรับการเรียกดู ​

openspec list ​

openspec view ​

openspec show ​

คำสั่งการตรวจสอบความถูกต้อง (Validation Commands) ​

openspec validate ​

คำสั่งวงจรชีวิต (Lifecycle Commands) ​

openspec archive ​

คำสั่ง Workflow ​

openspec new change ​

openspec status ​

openspec instructions ​

openspec templates ​

openspec schemas ​

คำสั่ง Schema ​

openspec schema init ​

openspec schema fork ​

openspec schema validate ​

openspec schema which ​

คำสั่ง Configuration ​

openspec config ​

คำสั่ง Utility ​

openspec feedback ​

openspec completion ​

Exit Codes ​

Environment Variables ​

เอกสารที่เกี่ยวข้อง ​

CLI Reference

สรุป

คำสั่งสำหรับมนุษย์ vs Agent

คำสั่งเฉพาะสำหรับมนุษย์

คำสั่งที่รองรับ Agent

ตัวเลือกทั่วไป (Global Options)

คำสั่งการตั้งค่า (Setup Commands)

`openspec init`

`openspec update`

Stores (คลังข้อมูลแบบแยกอิสระที่เป็น repo ของ OpenSpec)

`openspec store setup`

`openspec store register`

`openspec store unregister`

`openspec store remove`

`openspec store list`

`openspec store doctor`

การอ้างอิง stores จากโปรเจกต์

การบันทึกแหล่ง clone ของ store

การประกาศ default store

Doctor (ตรวจสอบสุขภาพความสัมพันธ์)

Working context (ชุดข้อมูลที่ประกอบขึ้นแล้ว)

Personal worksets

คำสั่งสำหรับการเรียกดู

`openspec list`

`openspec view`

`openspec show`

คำสั่งการตรวจสอบความถูกต้อง (Validation Commands)

`openspec validate`

คำสั่งวงจรชีวิต (Lifecycle Commands)

`openspec archive`

คำสั่ง Workflow

`openspec new change`

`openspec status`

`openspec instructions`

`openspec templates`

`openspec schemas`

คำสั่ง Schema

`openspec schema init`

`openspec schema fork`

`openspec schema validate`

`openspec schema which`

คำสั่ง Configuration

`openspec config`

คำสั่ง Utility

`openspec feedback`

`openspec completion`

Exit Codes

Environment Variables

เอกสารที่เกี่ยวข้อง