CLI

Perintah terminal openspec.

Perintah

Penyiapan

Perintah	Fungsinya
openspec init	Menginisialisasi OpenSpec dalam sebuah proyek.
openspec update	Memperbarui file instruksi OpenSpec yang terpasang.
openspec config	Melihat dan mengubah konfigurasi global.

Perubahan dan spesifikasi

Perintah	Fungsinya
openspec list	Menampilkan daftar perubahan, atau spesifikasi dengan --specs.
openspec show	Mencetak perubahan atau spesifikasi, sebagai markdown atau JSON.
openspec view	Dasbor satu layar untuk spesifikasi dan perubahan.
openspec validate	Memeriksa perubahan dan spesifikasi untuk masalah struktural.
openspec archive	Memindahkan perubahan yang selesai ke arsip dan memperbarui spesifikasi utama.

Alur kerja dan skema

Agen Anda menjalankan sebagian besar perintah ini selama alur kerja.

Perintah	Fungsinya
openspec new	Membuat direktori perubahan baru.
openspec status	Status penyelesaian artefak untuk satu atau setiap perubahan aktif.
openspec instructions	Instruksi untuk membuat artefak, menerapkan, atau mengarsipkan.
openspec templates	Jalur template yang telah diselesaikan untuk artefak skema.
openspec schemas	Menampilkan daftar skema alur kerja yang tersedia.
openspec schema	Memeriksa, melakukan fork, atau membuat skema (eksperimental).

Multi-repo (beta)

Perintah	Fungsinya
openspec store	Membuat dan mengelola store: repositori OpenSpec mandiri yang terdaftar di mesin Anda.
openspec doctor	Melaporkan kesehatan relasi untuk root OpenSpec yang terselesaikan.
openspec context	Mencetak konteks kerja untuk root OpenSpec yang terselesaikan.
openspec workset	Menyusun, menyimpan, dan membuka tampilan kerja pribadi.

Utilitas

Perintah	Fungsinya
openspec version	Melaporkan versi yang terpasang dan secara opsional memeriksa pembaruan.
openspec install	Memasang openspec mandiri, yang berjalan tanpa Node.js.
openspec feedback	Mengirimkan umpan balik tentang OpenSpec.
openspec completion	Memasang atau menghasilkan pelengkapan shell.

Sudah tidak direkomendasikan

Perintah	Fungsinya
openspec change	Bentuk kata benda dari show, list, dan validate untuk perubahan. CLI akan memperingatkan dan mengarahkan ke perintah berbasis kata kerja.
openspec spec	Bentuk kata benda dari show, list, dan validate untuk spesifikasi, dengan peringatan yang sama.

Setiap perintah menerima -h, --help. Perintah openspec polos juga menerima:

• -V, --version: mencetak versi CLI.
• --no-color: menonaktifkan keluaran berwarna.## openspec init

Menginisialisasi OpenSpec dalam proyek.

openspec init                        # direktori saat ini, pemilih alat interaktif
openspec init --tools claude,cursor  # mengatur alat tertentu, tanpa prompt
openspec init --tools none           # hanya struktur openspec/, tanpa file alat

Tanpa --tools, init meminta Anda untuk memilih alat di terminal interaktif. Di luar lingkungan terminal interaktif, alat yang terdeteksi dalam proyek akan disetel. Jika tidak ada yang terdeteksi, perintah keluar dengan kode 1 dan menampilkan daftar id yang valid.

Repositori hanya penyimpanan

Jika openspec/config.yaml berisi baris store: dan repositori tidak memiliki spesifikasi atau perubahan lokal, jalankan init dari root repositori:

# menginstal file integrasi Claude Code di repositori kode
openspec init --tools claude

• File integrasi: ditulis di repositori kode.
• openspec/config.yaml: dipertahankan byte demi byte.
• openspec/specs/ dan openspec/changes/: tidak dibuat di repositori kode.

Menjalankan init dari subdirektori akan keluar dengan kode 1 dan memberi tahu Anda untuk menjalankannya dari root repositori. --language juga akan keluar dengan kode 1 karena bahasa harus ada di konfigurasi penyimpanan eksternal. Jalankan init di root penyimpanan atau edit konfigurasi tersebut secara langsung.

Argumen

Argumen	Penjelasan
path	Direktori proyek untuk diinisialisasi. Bawaan: direktori saat ini. Dibuat jika tidak ada.

Opsi

Flag	Efek
--tools <tools>	Id alat dipisah koma, all, atau none. Melewati pemilih. Id terdaftar di Alat yang didukung.
--language <language>	Menambahkan instruksi bahasa ke konfigurasi proyek baru. Ditolak jika baris store: repositori mengarah ke penyimpanan eksternal.
--force	Menghapus file dari tata letak OpenSpec lama tanpa bertanya. Eksekusi interaktif biasanya mengonfirmasi pembersihan terlebih dahulu.
--profile <profile>	Menghimpau profil konfigurasi global untuk eksekusi ini: core (set workflow standar) atau custom (workflow yang disimpan di konfigurasi global).
--no-animation	Menampilkan layar sambutan statis alih-alih animasi.

Output

Setiap alat yang dipilih mendapatkan skill dan perintah OpenSpec di direktorinya masing-masing:

▌ Struktur OpenSpec dibuat
✔ Setup selesai untuk Claude Code

OpenSpec Setup Selesai

Dibuat: Claude Code
6 skill dan 6 perintah di .claude/
Konfigurasi: openspec/config.yaml (skema: spec-driven)

Cara memulai:
  Mulai perubahan pertama Anda: /opsx:propose "ide Anda"

Mulai ulang IDE Anda agar perintah baru dapat diterapkan.

--tools none hanya membuat openspec/config.yaml. Pada proyek yang sudah diinisialisasi, init menulis ulang file yang terinstal di tempatnya dan ringkasan membaca Disegarkan: Claude Code dengan Konfigurasi: openspec/config.yaml (ada).

Kode keluar

• 0: setup selesai.
• 1: nilai --tools atau --profile tidak valid, eksekusi non-interaktif tanpa alat terdeteksi dan tanpa --tools, atau pemanggilan hanya penyimpanan tidak valid.

openspec update

Memperbarui file instruksi OpenSpec yang terinstal.

openspec update             # menyegarkan alat yang file-nya lebih tua daripada CLI
openspec update --force     # menulis ulang file bahkan jika sudah mutakhir
openspec update --dry-run   # menampilkan daftar perubahan yang akan dilakukan, tanpa mengubah apa pun

update menemukan alat yang disetel oleh init dan membandingkan file hasil generasinya dengan versi CLI. Jika rilis OpenSpec yang lebih baru ada, CLI terlebih dahulu menawarkan peningkatan, lalu menjalankan ulang dengan versi yang ditingkatkan. Setel OPENSPEC_NO_UPDATE_CHECK=1 untuk melewatkan pemeriksaan.

Argumen

Argumen	Penjelasan
path	Direktori proyek untuk diperbarui. Bawaan: direktori saat ini.

Opsi

Flag	Efek
--force	Menulis ulang file untuk setiap alat yang dikonfigurasi bahkan jika sudah mutakhir.
--dry-run	Melaporkan setiap file yang akan ditambahkan, diubah, atau dihapus oleh update, dan tidak menulis apa pun. Tidak ada pemeriksaan peningkatan CLI, tidak ada prompt. Gabungkan dengan --force untuk preview update paksa.
--json	Dengan --dry-run, mencetak rencana sebagai JSON. Tanpa --dry-run keluar dengan kode 1.

Mempreview update

--dry-run merencanakan update yang akan dilakukan oleh eksekusi non-interaktif: jalur kode yang sama, dengan setiap penulisan dan penghapusan dicatat alih-alih dilakukan. Setiap file yang akan disentuh oleh update sebenarnya akan terdaftar, termasuk:

• memindahkan file OpenSpec dari direktori lama alat (.kimi/ ke .kimi-code/, .windsurf/ ke .devin/, .codex/ dan .agent/ ke .agents/);
• menyimpan konfigurasi global saat instalasi sebelum profil mendapatkan profil;
• mensinkronkan file agen awan GitHub Copilot;
• dengan --force, menyiapkan alat yang hanya ditemukan dalam artefak legacy dan membersihkannya, termasuk prompt Codex global yang pensiun.

openspec update --dry-run

2 file akan berubah:
  update  .claude/skills/openspec-propose/SKILL.md  (claude)
  add     ~/.config/openspec/config.json  (openspec)

--dry-run --json mencetak rencana yang sama sebagai satu dokumen JSON:

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

Bidang	Isi
changes[].path	Path relatif proyek. File di luar proyek, seperti skill global atau konfigurasi global, ditampilkan dari direktori home Anda sebagai ~/..., atau sebagai path absolut jika di luar home.
changes[].action	add, update, atau delete. File yang byte barunya cocok dengan yang lama tidak terdaftar.
changes[].tool	Alat yang dikonfigurasi tempat file tersebut berada, seperti claude. File yang milik OpenSpec itu sendiri dan bukan satu alat, konfigurasi global, dan pembersihan artefak legacy, adalah openspec.
notes[]	{ code, message } untuk langkah yang akan ditanyakan kepada pengguna terminal. legacy-tool-directories: perpindahan yang akan ditanyakan terlebih dahulu oleh eksekusi interaktif; changes mencantumkannya sebagai sudah dilakukan. legacy-artifacts: file dari tata letak OpenSpec lama ditemukan, seperti perintah slash openspec-proposal.md atau blok penanda OpenSpec di AGENTS.md. Tanpa --force, update non-interaktif membiarkannya apa adanya, sehingga changes juga tidak mencantumkannya; --dry-run --force mencantumkan pembersihannya. Kosong untuk penyegaran biasa.
failures[]	{ tool, error } untuk setiap alat tempat update sebenarnya akan gagal, termasuk penulisan yang tidak dapat dilakukan: direktori tempat seharusnya ada file, file tempat seharusnya ada direktori, atau file/direktori tanpa izin tulis. Untuk alat tersebut, changes berhenti di tempat update sebenarnya berhenti; alat lain tetap direncanakan. Kegagalan yang hanya dilaporkan oleh disk saat menulis, seperti kehabisan ruang, tidak dapat diprediksi sebelumnya.

Kegagalan sebelum perencanaan, seperti tidak adanya direktori OpenSpec, tetap mencetak tepat satu dokumen JSON: rencana kosong plus array status dengan severity, code (update_error), dan message. Kode keluar adalah 1.

Output

Jika file semua alat cocok dengan versi CLI:

✓ Semua 1 alat mutakhir (v1.7.0)
  Alat: claude

Gunakan --force untuk menyegarkan file tetap.

Jika file alat berasal dari CLI yang lebih lama (atau dengan --force, yang mencetak Memperbarui paksa 1 alat: claude sebagai gantinya):

Memperbarui 1 alat: claude (1.6.0 → 1.7.0)

✔ Claude Code diperbarui

✓ Diperbarui: Claude Code (v1.7.0)
Alat: Claude Code

Mulai ulang IDE Anda agar perubahan dapat diterapkan.

Di direktori tanpa OpenSpec, update ditolak:

✖ Error: Direktori OpenSpec tidak ditemukan. Jalankan 'openspec init' terlebih dahulu.

Kode keluar

• 0: file diperbarui, atau semuanya sudah mutakhir.
• 1: tidak ada direktori OpenSpec di path, atau update gagal.

openspec config

Melihat dan mengubah konfigurasi global.

openspec config list                  # melihat pengaturan saat ini
openspec config set delivery skills   # mengubah satu nilai
openspec config profile               # pemilih workflow interaktif

Subperintah	Fungsi
path	Mencetak lokasi file konfigurasi.
list	Menampilkan semua pengaturan saat ini.
get <key>	Mencetak satu nilai, mentah dan bisa dikontrol skrip.
set <key> <value>	Mengatur nilai, memaksakan tipenya.
unset <key>	Menghapus key sehingga bawaan berlaku.
reset	Mereset semua konfigurasi ke bawaan.
edit	Membuka file konfigurasi di $EDITOR.
profile [preset]	Mengonfigurasi mode delivery dan workflow.

Konfigurasi bersifat global untuk mesin Anda, disimpan sebagai JSON di tempat yang diarahkan config path: $XDG_CONFIG_HOME/openspec/config.json jika disetel, jika tidak ~/.config/openspec/config.json (macOS, Linux) atau %APPDATA%\openspec\config.json (Windows). Setiap subperintah menerima --scope <scope>, tetapi hanya global yang berfungsi saat ini. Scope lain keluar dengan kode 1 dengan Error: Konfigurasi lokal proyek belum diimplementasikan.

openspec config path

openspec config path

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

openspec config list

openspec config list          # pengaturan yang terbaca plus ringkasan profil
openspec config list --json   # konfigurasi mentah sebagai JSON

Opsi

Flag	Efek
--json	Mencetak objek konfigurasi sebagai JSON.

Output

Setiap pengaturan, lalu ringkasan profil yang menandai nilai sebagai eksplisit atau bawaan:

featureFlags: {}
profile: core
delivery: both

Pengaturan profil:
  profile: core (bawaan)
  delivery: both (bawaan)
  workflows: propose, explore, apply, update, sync, archive (dari profil core)

openspec config get

openspec config get delivery

Argumen

Argumen	Penjelasan
key	Key yang dibaca. Titik mencapai nilai bersarang (featureFlags.workspaces).

Output

Nilai polos, siap untuk skrip. Objek dicetak sebagai JSON ringkas:

both

Kode keluar

• 0: nilai dicetak.
• 1: key tidak memiliki nilai, dan tidak ada yang dicetak.

openspec config set

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

Argumen

Argumen	Penjelasan
key	Key yang ditulis, dengan titik untuk nilai bersarang.
value	Nilai baru. true/false menjadi boolean, string numerik menjadi angka.

Opsi

Flag	Efek
--string	Menyimpan nilai sebagai string, melewatkan pemaksaan tipe.
--allow-unknown	Mengizinkan key yang tidak diketahui skema.

Output

Set featureFlags.workspaces = true

Key yang tidak diketahui dan nilai yang tidak valid gagal dengan keluar 1 sebelum apa pun disimpan:

Error: Kunci konfigurasi "bogus.key" tidak valid. Kunci tingkat atas "bogus" tidak dikenal.
Gunakan "openspec config list" untuk melihat kunci yang tersedia.
Lewati --allow-unknown untuk melewati pemeriksaan ini.

Error: Konfigurasi tidak valid - delivery: Pilihan tidak valid: diharapkan salah satu dari "both"|"skills"|"commands"

Jika file konfigurasi ada tetapi tidak berisi objek JSON, baik karena tidak valid JSON sama sekali maupun karena root-nya adalah sesuatu yang lain seperti null atau array, config set, config unset, dan config profile keluar dengan 1 dan meninggalkan file tanpa perubahan. Perbaiki dengan openspec config edit, atau ganti dengan openspec config reset --all:

Error: /home/you/.config/openspec/config.json tidak dapat dianalisis, jadi dibiarkan tanpa perubahan.
Perbaiki dengan "openspec config edit", atau reset dengan "openspec config reset --all".

Hingga diperbaiki, telemetri dan pemeriksaan update tetap mati.

openspec config unset

openspec config unset delivery

Menghapus key sehingga bawaan berlaku lagi. Key dengan bawaan bawaan selalu dihitung sebagai telah disetel, jadi ini melaporkan sukses bahkan jika Anda tidak pernah menyetelnya:

Unset delivery (dibalik ke bawaan)

Key yang sama sekali tidak memiliki nilai mencetak Key "featureFlags.nothere" tidak disetel. Kedua kasus keluar 0. File konfigurasi yang tidak dapat dianalisis keluar 1 sebagai gantinya, seperti untuk config set.

openspec config reset

openspec config reset --all      # meminta konfirmasi
openspec config reset --all -y   # tanpa prompt

Opsi

Flag	Efek
--all	Wajib. Reset semua.
-y, --yes	Melewati prompt konfirmasi.

Output

Konfigurasi direset ke bawaan

Tanpa --all keluar 1 dan mencetak baris penggunaan.

Kode keluar

• 0: reset selesai, atau Anda menjawab tidak di prompt.
• 1: --all tidak ada.
• 130: prompt dibatalkan dengan Ctrl-C.

openspec config edit

openspec config edit

Membuka file konfigurasi di $EDITOR (dengan fallback ke $VISUAL), membuatnya dengan bawaan terlebih dahulu jika tidak ada. Ketika editor ditutup, file divalidasi. JSON tidak valid atau konfigurasi tidak valid keluar 1.

Nilai editor dapat membawa argumen dan path yang dikutip, misalnya code --wait atau "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Ini dipecah menjadi kata-kata tanpa shell, jadi $VAR, ~ dan ; diteruskan apa adanya. Editor yang tidak dapat dimulai, atau keluar non-nol, mencetak error satu baris dan keluar 1.

Tanpa editor yang dikonfigurasi, keluar 1:

Error: Editor tidak dikonfigurasi
Setel variabel lingkungan EDITOR atau VISUAL ke editor pilihan Anda
Contoh: export EDITOR=vim

openspec config profile

openspec config profile        # pemilih interaktif (butuh terminal)
openspec config profile core   # menerapkan preset core secara langsung

Argumen

Argumen	Penjelasan
preset	Nama preset opsional. Hanya core yang ada. Memilih workflow core dan mempertahankan pengaturan delivery Anda.

Tanpa preset, pemilih interaktif menampilkan delivery dan workflow Anda saat ini, memungkinkan Anda mengubah salah satu atau keduanya (delivery: both, hanya skills, atau hanya commands; workflows: daftar kotak centang), mencetak diff, dan di dalam proyek OpenSpec menawarkan untuk menjalankan openspec update untuk Anda. Di luar terminal, keluar 1:

Mode interaktif diperlukan. Gunakan `openspec config profile core` atau setel konfigurasi melalui lingkungan/flag.

Output

Konfigurasi yang berubah tidak sampai ke proyek hingga mereka memperbarui:

Konfigurasi diperbarui. Jalankan `openspec update` di proyek Anda untuk menerapkan.

Kode keluar

• 0: profil disimpan, atau Anda mempertahankan pengaturan saat ini.
• 1: preset tidak dikenal, tidak ada terminal, atau openspec update yang ditawarkan gagal.
• 130: pemilih dibatalkan dengan Ctrl-C.

openspec list

Mencantumkan perubahan, atau spesifikasi dengan --specs.

openspec list                    # perubahan aktif, terakhir dimodifikasi lebih dulu
openspec list --archived         # perubahan yang diarsipkan
openspec list --all              # perubahan aktif dan yang diarsipkan
openspec list --specs            # spesifikasi dengan jumlah persyaratan
openspec list --json             # dapat dibaca mesin, menyertakan root yang diselesaikan

Baris berasal dari openspec/changes/ dan openspec/specs/ di bawah root yang diselesaikan. Daftar perubahan default melewatkan openspec/changes/archive/.

Opsi

Bendera	Efek
--specs	Mencantumkan spesifikasi alih-alih perubahan.
--changes	Mencantumkan perubahan. Ini adalah default.
--archived	Mencantumkan hanya perubahan yang diarsipkan. Tidak dapat digabungkan dengan --specs.
--all	Mencantumkan perubahan aktif dan yang diarsipkan. Tidak dapat digabungkan dengan --specs. Lebih diutamakan daripada --archived.
--sort <order>	recent (terakhir dimodifikasi lebih dulu) atau name. Default: recent. Spesifikasi selalu diurutkan berdasarkan nama.
--json	Mencetak JSON alih-alih tabel.
--store <id>	Menggunakan store terdaftar sebagai root OpenSpec alih-alih proyek saat ini.

Keluaran

Satu baris per perubahan: nama, status tugas, terakhir dimodifikasi. Kolom status menampilkan No tasks, 2/5 tasks, atau ✓ Complete.

Changes:
  add-rate-limit     No tasks      just now

--all mengelompokkan perubahan aktif dan yang diarsipkan di bawah judul terpisah. Setiap grup menggunakan urutan sortir yang dipilih:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json menambahkan jumlah tugas dan status dari no-tasks, in-progress, atau complete:

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

Dengan --archived atau --all, setiap objek perubahan menyertakan boolean archived. Array gabungan menggunakan urutan sortir yang dipilih. Perubahan yang diarsipkan masih dapat memiliki status in-progress ketika file tugas yang dilacak memiliki tugas yang belum diperiksa. Tanpa salah satu flag, bentuk JSON tetap tidak berubah.

Daftar kosong mencetak No active changes found., No archived changes found., No changes found., atau No specs found. dan tetap keluar dengan kode 0.

Perubahan adalah direktori yang langsung berada di bawah openspec/changes/. Tidak seperti spesifikasi, perubahan tidak dapat bersarang di folder namespace. Folder seperti changes/mobile/ yang hanya membungkus perubahan (changes/mobile/refresh-token/) dicantumkan dengan status not a change, diikuti dengan peringatan yang menyebutkan direktori bersarang. --json menandai entri tersebut dengan array nested dan menambahkan array warnings tingkat atas. show, status, validate, dan archive menolak folder tersebut dengan pesan yang sama. Untuk memperbaikinya, pindahkan perubahan ke atas dan lipat namespace ke dalam namanya:

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

Kode keluar

• 0: daftar dicetak, bahkan saat kosong.
• 1: root OpenSpec tidak ditemukan (di luar proyek, tanpa --store).

openspec show

Mencetak perubahan atau spesifikasi, sebagai markdown atau JSON.

openspec show add-rate-limit              # perubahan: mencetak proposal.md
openspec show add-rate-limit --diff       # perubahan: menambahkan diff delta persyaratan
openspec show api                         # spesifikasi: mencetak spec.md
openspec show api --json --no-scenarios   # JSON spesifikasi tanpa teks skenario

Tanpa nama, show meminta perubahan atau spesifikasi, lalu mencantumkan item untuk dipilih. Di luar terminal interaktif, ia keluar dengan kode 1 dan mencetak bentuk langsung sebagai gantinya.

Argumen

Argumen	Deskripsi
item-name	Perubahan atau spesifikasi yang akan ditampilkan, berdasarkan nama folder (add-rate-limit, api).

Opsi

Bendera	Efek
--json	Mencetak JSON terstruktur alih-alih markdown mentah.
--type <change|spec>	Pilih jenis ketika perubahan dan spesifikasi berbagi nama.
--no-interactive	Jangan pernah meminta: nama yang hilang menjadi kesalahan.
--deltas-only	JSON, perubahan: batasi keluaran hanya pada delta. JSON perubahan sudah delta-only, jadi keluaran cocok dengan --json biasa.
--requirements-only	Alias yang sudah usang untuk --deltas-only. Memberi peringatan di stderr.
--diff	Perubahan: tambahkan diff delta per persyaratan. Diabaikan dengan peringatan untuk spesifikasi.
--requirements	JSON, spesifikasi: pertahankan teks persyaratan, kosongkan array scenarios.
--no-scenarios	JSON, spesifikasi: keluaran yang sama dengan --requirements.
-r, --requirement <id>	JSON, spesifikasi: keluarkan satu persyaratan berdasarkan posisi berbasis 1. Tidak dapat digabungkan dengan --requirements.
--store <id>	Menggunakan store terdaftar sebagai root OpenSpec alih-alih proyek saat ini.

Bendera yang tidak berlaku untuk jenis yang diselesaikan diabaikan dengan peringatan di stderr.

Keluaran

Mode teks adalah penerusan mentah: perubahan mencetak proposal.md, spesifikasi mencetak spec.md.

# Add rate limiting
```## Mengapa
Klien tanpa autentikasi dapat membuat API kehabisan kapasitas.

## Apa yang Berubah
- Tambahkan pembatasan laju per klien ke API publik.

Untuk sebuah perubahan, --diff mencetak proposal terlebih dahulu, lalu bagian Specifications Changed (diffs). Persyaratan ADDED menyertakan teks lengkapnya. Persyaratan REMOVED mempertahankan Reason dan Migration yang ditulis. Persyaratan RENAMED menampilkan FROM dan TO. Persyaratan MODIFIED menampilkan diff terpadu terhadap persyaratan utama yang cocok.

Jika header MODIFIED baru cocok setelah normalisasi kapitalisasi atau spasi, output menyertakan diff dan peringatan bahwa pencocokan arsip bersifat persis. Jika spec utama atau persyaratan tidak ada, output memberi peringatan dan mencetak blok delta lengkap. Blok MODIFIED tanpa perbedaan tekstual mencetak (no textual changes).

Perubahan dengan --json berbentuk delta:

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

Setiap persyaratan membawa name-nya, yaitu teks header setelah Requirement:. Ini adalah nama yang dicocokkan oleh arsip terhadap entri MODIFIED, REMOVED, dan RENAMED. Setiap skenario membawa name-nya, yaitu teks header setelah Scenario:. Deretan # penutup pada salah satu header bukan bagian dari nama.

--json --diff mempertahankan bentuk tingkat atas ini. Delta MODIFIED memperoleh string diff, string warning, atau keduanya. Operasi lain tidak berubah. String diff kosong berarti blok utama dan delta identik secara tekstual.

Spec dengan --json mencantumkan persyaratan beserta skenarionya. Persyaratan dan skenario membawa field name yang sama seperti JSON perubahan:

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

Nama yang tidak dikenal menyarankan kecocokan terdekat: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Nama yang cocok dengan perubahan sekaligus spec akan menghasilkan error dan meminta --type.

Kode keluar

• 0: item dicetak.
• 1: nama tidak dikenal atau ambigu, tidak ada nama saat di luar terminal, indeks -r di luar rentang, --requirements digabungkan dengan -r, atau delta atau spec utama tidak dapat dibaca untuk --diff.

openspec view

Mencetak dasbor satu layar untuk spec dan perubahan.

openspec view   # ringkasan proyek dalam satu layar

view mencetak dasbor satu kali lalu keluar. Perintah ini tidak membaca input keyboard apa pun. Perubahan dikelompokkan berdasarkan kemajuan tugas: Draf (belum ada tugas), Aktif (tugas sedang berjalan, dengan bilah kemajuan dan persentase), Selesai (setiap tugas telah dicentang). Spec dicantumkan dengan jumlah persyaratan, yang terbesar lebih dahulu.

Opsi

Flag	Efek
--store <id>	Gunakan store terdaftar sebagai root OpenSpec alih-alih proyek saat ini.

Keluaran

OpenSpec Dashboard

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

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

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

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

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

Baris ringkasan Task Progress muncul ketika ada perubahan yang memiliki tugas sedang berjalan.

Setiap perubahan aktif juga menampilkan skema dan status artefaknya di bawah bilah kemajuan tugasnya:

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

Penanda	Status artefak
✓	Keluarannya ada. Artefak tasks yang sudah ada dianggap selesai meskipun checklist-nya belum tuntas.
→	Siap dibuat.
Tanpa penanda	Diblokir karena dependensi yang hilang.
(skipped)	Perubahan melewatinya.

Jika workflow tidak dapat dimuat, view mencetak peringatan dan tetap menampilkan kemajuan tugas perubahan tersebut. Jalankan openspec status --change <name> untuk memeriksa workflow secara terpisah. Setelah openspec view --store <id>, teruskan --store <id> yang sama ke status.

Kode keluar

• 0: dasbor dicetak.
• 1: root OpenSpec tidak ditemukan (di luar proyek, tanpa --store).

openspec validate

Memeriksa perubahan dan spec untuk masalah struktural.

openspec validate add-rate-limit   # satu perubahan atau spec, berdasarkan nama
openspec validate --all            # setiap perubahan dan spec

Tanpa nama dan tanpa flag bulk, validate akan meminta Anda memilih item. Di luar terminal interaktif, perintah ini keluar dengan kode 1 dan mencetak flag bulk sebagai gantinya.

Argumen

Argumen	Keterangan
item-name	Perubahan atau spec yang akan divalidasi, berdasarkan nama folder (add-rate-limit, api).

Opsi

Flag	Efek
--all	Validasi setiap perubahan dan spec.
--changes	Validasi setiap perubahan.
--specs	Validasi setiap spec.
--archived	Periksa penyelesaian tugas pada perubahan yang diarsipkan, tanpa memvalidasi delta spec yang diterapkan.
--strict	Perlakukan peringatan sebagai kegagalan.
--type <change|spec>	Pilih tipe saat perubahan dan spec memiliki nama yang sama.
--json	Cetak laporan terstruktur alih-alih teks.
--report <mode>	Output bulk: full (default) atau findings. Memerlukan cakupan bulk eksplisit.
--concurrency <n>	Validasi paralel maksimum dalam proses bulk. Default: OPENSPEC_CONCURRENCY, jika tidak ada maka 6.
--no-interactive	Jangan pernah meminta input: nama yang hilang atau ambigu menjadi error.
--store <id>	Gunakan store terdaftar sebagai root OpenSpec alih-alih proyek saat ini.

Keluaran

Proses bulk mencetak satu baris status per item, diikuti temuan apa pun, lalu diakhiri dengan total:

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

Temuan checkbox tugas

Kemajuan hanya menghitung checkbox dan tidak menghitung hal lain, sehingga file tugas yang ditulis sebagai butir biasa terbaca sebagai nol tugas: openspec list dan openspec status melaporkan tidak ada pekerjaan, dan openspec archive tidak memiliki apa pun untuk ditandai sebagai belum selesai. Validate melaporkan WARNING pada setiap file tugas terlacak yang mencantumkan pekerjaan tanpa checkbox:

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

Peringatan muncul hanya ketika seluruh kumpulan terlacak pada perubahan tidak memiliki satu checkbox pun. Satu file berisi prosa di samping checklist sungguhan tidak dilaporkan, dan perubahan yang masih dalam proses penulisan tetap mempertahankan kemajuannya begitu satu checkbox saja ada. --strict mengubah peringatan menjadi kegagalan. Nomor baris ada di laporan --json.

Blok fenced, komentar HTML, front matter YAML, dan kode terindentasi tidak dipindai, sehingga contoh terminal yang ditempel tidak pernah disalahartikan sebagai daftar tugas.

Temuan merge arsip

Untuk perubahan, validate menjalankan pembangun merge arsip terhadap spec utama saat ini tanpa menulis file. Perintah ini melaporkan konflik merge, seperti target MODIFIED yang hilang atau persyaratan ADDED yang berkonflik, sebagai INFO:

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

Temuan ini muncul bahkan ketika validasi lolos, baik dalam output teks maupun JSON. INFO tidak pernah mengubah kode keluar, termasuk dengan --strict: target yang hilang mungkin milik perubahan lain yang belum diarsipkan. Delta yang sudah disinkronkan ke spec utama mengikuti aturan merge arsip yang sudah ada.

Pemeriksaan ini tidak menjalankan validasi spec hasil merge atau pemeriksaan retirement yang dijalankan arsip pada tahap berikutnya. Laporan yang bersih tidak menjamin arsip akan berhasil.

Jika preflight merge tidak dapat dimulai, temuan INFO menjelaskan alasannya. Temuan validasi yang sudah ada dan kode keluar tetap tidak berubah.

Item yang gagal mencantumkan setiap masalah dan perbaikannya:

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

--json mencetak satu laporan untuk proses tersebut:

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

Entri issues membawa level bernilai ERROR, WARNING, atau INFO.

Kode keluar

• 0: setiap item yang divalidasi lolos, termasuk cakupan bulk yang kosong.
• 1: ada item yang gagal, permintaan laporan tidak valid, openspec/config.yaml tidak dapat dibaca atau bukan YAML valid, atau proses gagal (misalnya nama tidak dikenal atau tidak ada root OpenSpec). Config yang tidak dapat dibaca atau diurai menghentikan proses sebelum item apa pun diperiksa; dengan --json, hal ini dilaporkan sebagai satu entri status dengan kode unreadable_config atau unparseable_config.

--report full|findings

Memilih output untuk cakupan validasi bulk eksplisit:

• full: setiap item. Ini adalah default. --report full eksplisit mempertahankan bentuk output yang ada tanpa menambahkan metadata laporan.
• findings: hanya item yang memiliki masalah, termasuk item yang lolos dengan peringatan atau informasi. Setiap item tetap divalidasi. Total, perilaku mode strict, dan kode keluar tidak berubah.

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

Cakupan

Flag	report.scope pada findings
--all	all
--changes	changes
--specs	specs
--changes --specs, atau --all dengan salah satu flag	all
--archived	archived

Kedua mode laporan eksplisit menolak nama item posisional, cakupan bulk yang hilang, atau cakupan arsip dan aktif yang digabungkan.

Output teks findings

Output yang dapat dibaca manusia: stdout mencetak Scope: <scope> (<count> items), lalu total. Jika tidak ada item bermasalah:

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

Label item bermasalah, label keparahan, path, dan pesan dicetak ke stderr. Kegagalan cakupan aktif mempertahankan petunjuk menjalankan ulang Details: setelah total. Banner root dan output kemajuan yang sudah ada dapat mendahului laporan.

Output JSON findings

--report findings --json mencetak satu dokumen. Contoh ini memiliki dua item bersih:

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

• report.kind dan report.version: mengidentifikasi bentuk validation-findings, versi 1.0. Tidak ada version atau items tingkat atas.
• report.returnedItems dan report.totalItems: masing-masing menghitung record yang dikembalikan dan seluruh item yang divalidasi.
• itemFindings: record item lengkap yang array issues-nya tidak kosong. Mencakup masalah ERROR, WARNING, dan INFO. Setiap record mempertahankan id, type, valid, issues, dan durationMs. Item yang diarsipkan menggunakan type: "change".
• summary: total seluruh proses dan jumlah per tipe, bukan jumlah subset yang dikembalikan. Cakupan kosong memiliki total nol dan keluar dengan kode 0.
• root: metadata root terpilih yang sama seperti laporan lengkap.

Pemeliharaan record: item yang dikembalikan mempertahankan urutan laporan lengkapnya dan field tambahan apa pun pada item atau issues. Pemfilteran tidak menulis ulang pesan atau lokasi, termasuk field opsional line dan column.

Kegagalan perintah: kegagalan pemilihan root atau penemuan item mempertahankan diagnostik status yang sudah ada dan keluar dengan kode 1. Kegagalan tersebut tidak mengembalikan laporan findings yang selesai atau laporan kosong yang berhasil.

Permintaan laporan tidak valid

Kedua mode laporan eksplisit menolak permintaan berikut sebelum pemilihan root atau penemuan item:

• Nilai laporan yang tidak didukung, termasuk string kosong.
• Nama item posisional, bahkan dengan flag bulk.
• Tidak ada cakupan bulk eksplisit.
• --archived digabungkan dengan --all, --changes, atau --specs.

Dalam mode JSON, permintaan yang ditolak keluar dengan kode 1 hanya dengan array status satu elemen. Permintaan tersebut tidak memiliki root atau payload laporan:

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

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

Mode untuk manusia mencetak error ke stderr. --report tanpa nilai merupakan error sintaks Commander di stderr, termasuk dengan --json; perintah ini tidak menggunakan envelope diagnostik tersebut.

Memfilter laporan lengkap secara eksternal

Untuk tampilan JSON kustom, filter laporan lengkap dengan jq atau PowerShell. Contoh skrip ini mempertahankan kode keluar validasi dan membiarkan dokumen error perintah tetap utuh.

Dalam Bash dengan jq:

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

Dalam PowerShell:

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

Tampilan kustom ini mempertahankan key laporan lengkap tetapi menghilangkan item bersih. Tampilan tersebut bukan laporan full-v1 yang lengkap maupun bentuk --report findings yang berversi.

openspec archive

Memindahkan change yang telah selesai ke arsip dan memperbarui spesifikasi utama.

openspec archive add-rate-limit -y                # arsipkan satu change, gabungkan delta-nya
openspec archive add-rate-limit -y --skip-specs   # arsipkan tanpa menyentuh spesifikasi

Tanpa nama, perintah archive akan meminta Anda memilih sebuah change. Di luar terminal interaktif, perintah ini akan keluar dengan kode 1 dan mencetak perintah untuk dijalankan ulang sebagai gantinya.

Argumen

Argumen	Penjelasan
change-name	Change yang akan diarsipkan, berdasarkan nama foldernya (add-rate-limit).

Opsi

Flag	Efek
-y, --yes	Menjawab yes untuk setiap konfirmasi: pembaruan spesifikasi, tugas yang belum selesai, validasi yang dilewati.
--skip-specs	Mengarsipkan tanpa menyentuh spesifikasi utama (perubahan infrastruktur, tooling, atau hanya dokumentasi).
--no-validate	Melewati validasi. Perintah archive akan meminta konfirmasi terlebih dahulu, dan -y menjawabnya.
--json	Mencetak hasil terstruktur alih-alih teks. Memerlukan --yes untuk mengonfirmasi pembaruan spesifikasi.
--store <id>	Menggunakan store yang terdaftar sebagai root OpenSpec, bukan proyek saat ini.

Output

Eksekusi yang berhasil akan melaporkan status tugas, menampilkan pratinjau pembaruan spesifikasi, menerapkannya, dan menyebutkan nama folder arsip:

Task status: ✓ Complete

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

Folder change dipindahkan utuh ke openspec/changes/archive/2026-08-11-add-rate-limit/, dengan tanggal hari ini sebagai awalan pada namanya. Setiap delta digabungkan ke spesifikasi utamanya: requirement ADDED di atas ditambahkan ke openspec/specs/api/spec.md. Tanpa -y, perintah archive menampilkan pratinjau dan meminta konfirmasi sebelum memperbarui. Jika ditolak, change tetap diarsipkan dan spesifikasi dibiarkan tidak tersentuh.

Dengan --json --yes:

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

Perintah archive memvalidasi change terlebih dahulu dan menolak change yang gagal:

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

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

Tugas yang belum selesai hanya memicu peringatan dan tidak memblokir. Secara interaktif, perintah archive akan menanyakan apakah ingin melanjutkan, dan -y melanjutkan secara otomatis:

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

Kode keluar

• 0: change berhasil diarsipkan, dengan atau tanpa pembaruan spesifikasi.
• 1: validasi gagal, nama change tidak dikenal, atau konfirmasi diperlukan tetapi tidak ada jawaban yang dapat dibaca.

openspec new

Membuat direktori change baru.

openspec new change add-caching                                # hanya metadata
openspec new change add-search --goal "Users can search docs"  # catat goal

new memiliki satu subcommand, yaitu new change <name>. Perintah ini membuat openspec/changes/<name>/ yang berisi satu file metadata .openspec.yaml:

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

Artifact (proposal, spesifikasi, desain, tugas) tidak dibuatkan kerangkanya di sini. Anda menulisnya nanti, dan openspec status akan memberi tahu mana yang berikutnya.

Argumen

Argumen	Penjelasan
name	Nama folder untuk change (add-caching).

Opsi

Flag	Efek
--description <text>	Juga membuat README.md di direktori change dengan teks ini.
--goal <text>	Menyimpan baris goal: di .openspec.yaml.
--schema <name>	Skema alur kerja untuk change. Default: spec-driven, satu-satunya skema yang tersedia.
--json	Mencetak change yang dibuat sebagai JSON alih-alih teks.
--store <id>	Menggunakan store yang terdaftar sebagai root OpenSpec, bukan proyek saat ini.

Output

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

Ketika direktori openspec/ tidak ditemukan, new change membuatnya di lokasi Anda berada dan memberitahukannya:

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

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

Pemberitahuan tersebut dikirim ke stdout bersama output lainnya yang ditujukan untuk manusia, dan tidak pernah muncul dengan --json.

Dengan --json, pada proyek yang sudah memiliki openspec/:

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

Ketika direktori openspec/ tidak ditemukan dan new change membuatnya, JSON memiliki bentuk yang sama. root.path adalah direktori tempat Anda menjalankan perintah, dan root.source bernilai implicit:

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

Kode keluar

• 0: change berhasil dibuat.
• 1: change sudah ada, atau skema tidak dikenal.## openspec status

Melaporkan status penyelesaian artefak untuk satu perubahan atau setiap perubahan aktif.

openspec status --change add-rate-limit          # tampilan daftar periksa
openspec status --change add-rate-limit --json   # laporan terstruktur
openspec status --all                            # setiap perubahan aktif
openspec status --all --json                     # satu laporan batch

Ketika perubahan aktif ada, gunakan tepat salah satu dari --change atau --all. Tanpa keduanya, status akan keluar dengan kode 1 dan mencantumkan perubahan yang tersedia, bahkan ketika hanya ada satu:

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

Ketika proyek tidak memiliki perubahan aktif, status mencetak No active changes. Create one with: openspec new change <name> dan keluar dengan kode 0 meskipun tanpa flag apapun. Dengan --all --json, keadaan kosong yang sama adalah { "changes": [], "message": "No active changes.", "root": ... }.

Opsi

Flag	Efek
--change <id>	Perubahan yang akan dilaporkan, berdasarkan nama folder.
--all	Laporkan setiap perubahan aktif, diurutkan berdasarkan nama. Tidak dapat digabungkan dengan --change.
--schema <name>	Timpa skema yang terdeteksi secara otomatis dari openspec/config.yaml. Nama yang tidak dikenal akan menyebabkan error.
--json	Cetak laporan terstruktur alih-alih teks.
--store <id>	Gunakan store terdaftar sebagai root OpenSpec alih-alih proyek saat ini.

Output

Daftar periksa artefak dari skema: [x] selesai, [ ] siap ditulis, [-] terhambat hingga artefak yang menjadi dependensinya ada.

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

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

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

Baris Next: menyebutkan satu perintah yang memajukan perubahan, sehingga openspec status cukup untuk memilih kembali perubahan dalam sesi baru. Baris ini menyebutkan artefak berikutnya yang siap saat perencanaan belum selesai, dan openspec instructions apply setelah semua artefak perencanaan ada:

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

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

Perintah ini menyertakan --store <id> kapan pun root yang diselesaikan adalah sebuah store, dan menyebutkan perintah yang sama dengan kalimat JSON nextSteps.

--json menambahkan dependensi per-artefak, jalur file yang telah diselesaikan, dan langkah selanjutnya yang disarankan. Dipangkas:

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

Dengan --all --json, changes berisi objek status yang sama untuk setiap perubahan, tanpa root per-perubahan. Root yang dipilih muncul sekali pada amplop. Contoh ini memangkas bidang status per-perubahan yang ditampilkan di atas:

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

Jika satu perubahan tidak dapat dimuat, batch tetap berlanjut. Entri tersebut berisi changeName dan diagnostik status sementara entri lainnya tetap tersedia. Perintah keluar dengan kode 1, termasuk dalam mode JSON, agar CI tidak menerima laporan yang tidak lengkap sebagai sukses. Output JSON tetap merupakan satu dokumen yang dapat diparsing.

Kode Keluar

• 0: setiap status yang diminta dicetak; laporan --all kosong juga keluar dengan kode 0.
• 1: perubahan yang diminta gagal dimuat, --change atau --all hilang, kedua flag digabungkan, perubahan tidak ada, atau timpa skema tidak dikenal.

openspec instructions

Mencetak instruksi untuk membuat artefak, menerapkan, atau mengarsipkan. Agen Anda menjalankan ini selama alur kerja untuk mengambil teks instruksi untuk langkah selanjutnya.

openspec instructions proposal --change add-rate-limit   # cara menulis satu artefak
openspec instructions apply --change add-rate-limit      # cara menerapkan perubahan
openspec instructions archive --change add-rate-limit    # input untuk pengarsipan

Argumen

Argumen	Apa itu
artifact	ID artefak dari skema (proposal, specs, design, tasks dalam spec-driven), atau kata cadangan apply dan archive.

Opsi

Flag	Efek
--change <id>	Perubahan untuk menghasilkan instruksi. Wajib.
--schema <name>	Timpa skema. Secara otomatis terdeteksi dari config.yaml jika tidak ditentukan.
--json	Cetak objek terstruktur alih-alih teks.
--store <id>	Gunakan store terdaftar sebagai root OpenSpec alih-alih proyek saat ini.

Output

Bentuk artefak mencetak satu blok instruksi: tugas, file yang harus ditulis, cara menulisnya, templat artefak, dan apa yang dibuka dengan menyelesaikannya.

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

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

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

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

apply mencetak file konteks, kemajuan tugas, dan instruksi kerja:

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

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

### Progress
1/3 complete

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

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

No project context or operation guidance configured.

Ketika artefak wajib hilang, apply melaporkan ### ⚠️ Blocked dan menyebutkan namanya. archive mencetak nama perubahan plus konteks proyek dan panduan operasi apa pun dari konfigurasi. Jika tidak ada yang dikonfigurasi, ia mengatakan demikian dan tidak lebih.

Dengan --json, setiap bentuk mengembalikan satu objek. Bentuk artefak dimulai dengan:

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

dan dilanjutkan dengan outputPath, existingOutputPaths, string instruction dan template lengkap, dependencies, unlocks, dan root. Bentuk apply membawa contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done), dan instruction.

Setiap entri tasks membawa id, description, done, sourcePath, dan line. sourcePath adalah jalur absolut ke file yang dilacak yang menyediakan tugas tersebut. line adalah nomor baris satu-based kotak centang tugas dalam file tersebut.

taskTrackingConfigured selalu berupa boolean: true ketika skema mengatur apply.tracks yang tidak null, bahkan jika tidak ada file yang cocok, dan false sebaliknya. Jika file pelacakan yang cocok tidak dapat dibaca, unavailableTrackingFiles berisi path absolut dan alasan error reason. Bidang ini dihilangkan ketika setiap file yang cocok dapat dibaca. File yang dapat dibaca masih berkontribusi pada tasks dan progress, tetapi state tidak dapat menjadi all_done sampai setiap file yang cocok dibaca.

Kode Keluar

• 0: instruksi dicetak.
• 1: artefak tidak dikenal, perubahan tidak dikenal, skema tidak dikenal, atau --change hilang. Setiap error mencantumkan nilai yang valid.

openspec templates

Mencetak path template hasil resolusi untuk artefak suatu skema.

openspec templates          # skema default: spec-driven
openspec templates --json   # peta id artefak ke path

Opsi

Flag	Efek
--schema <name>	Skema yang akan di-resolve. Default: spec-driven.
--json	Mencetak peta JSON dari id artefak ke path template.

Output

Schema: spec-driven
Source: package

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

Source menunjukkan asal resolusi skema: project (openspec/schemas/ di proyek Anda), user (override global), atau package (bawaan CLI). Proyek diprioritaskan di atas user, dan user di atas package.

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

Kode keluar

• 0: path dicetak.
• 1: skema tidak dikenal. Error mencantumkan skema yang tersedia.

openspec schemas

Menampilkan daftar skema workflow yang tersedia.

openspec schemas          # nama, deskripsi, urutan artefak
openspec schemas --json   # dapat dibaca mesin, untuk penggunaan agent

Opsi

Flag	Efek
--json	Output sebagai JSON (untuk penggunaan agent).

Output

Available schemas:

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

Skema dari proyek Anda diberi label (project), dan override global diberi label (user override).

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

Kode keluar

• 0: skema ditampilkan.
• 1: daftar skema tidak dapat dibaca.## openspec schema

Memeriksa, mem-fork, atau membuat skema (eksperimental). Setiap subperintah pertama-tama mencetak Note: Schema commands are experimental and may change. ke stderr.

openspec schema which spec-driven          # lokasi asal resolusi skema
openspec schema fork spec-driven my-flow   # salin skema ke proyek
openspec schema init my-schema             # buat skema dari awal

Subperintah	Fungsinya
which	Menampilkan lokasi asal resolusi skema.
validate	Memeriksa struktur dan templat skema.
fork	Menyalin skema yang sudah ada ke proyek untuk disesuaikan.
init	Membuat skema lokal proyek baru.

Skema diresolusikan dari tiga lokasi. Kecocokan pertama digunakan:

Sumber	Lokasi
project	openspec/schemas/ di proyek saat ini.
user	~/.local/share/openspec/schemas/ (XDG_DATA_HOME dan %LOCALAPPDATA% Windows diikuti).
package	Skema yang disertakan dengan CLI. spec-driven berada di sini.

openspec schema which

Menampilkan salinan skema mana yang akan digunakan CLI.

openspec schema which spec-driven
openspec schema which --all        # semua skema, dikelompokkan berdasarkan sumber

Argumen

Argumen	Deskripsi
name	Skema yang dicari. Wajib kecuali --all diset. Tanpa keduanya, which keluar dengan kode 1.

Opsi

Flag	Efek
--all	Mencantumkan setiap skema dengan sumber resolusinya.
--json	Mencetak resolusi sebagai JSON.

Keluaran

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

Ketika salinan berprioritas lebih tinggi menyembunyikan salinan lain, bagian Shadows: mencantumkan salinan yang tersembunyi. Dengan --json:

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

Nama yang tidak dikenal keluar dengan kode 1 dan mencantumkan skema yang tersedia.

openspec schema validate

Memeriksa struktur dan templat skema.

openspec schema validate spec-driven   # satu skema, dari sumber mana pun
openspec schema validate               # semua skema lokal proyek

Perintah ini memverifikasi bahwa schema.yaml ada dan dapat diurai, bahwa struktur sesuai dengan format skema, bahwa setiap file templat artefak ada di dalam direktori templates/ skema, dan bahwa graf dependensi tidak memiliki siklus atau referensi tidak dikenal, termasuk di apply.requires. Nilai apply.tracks yang tidak sama persis dengan nilai generates artefak mana pun akan mencetak baris warning: tetapi tidak menggagalkan validasi, karena OpenSpec kemudian tidak dapat menentukan progres artefak mana yang dimiliki file tersebut.

Opsi

Flag	Efek
--json	Mencetak laporan terstruktur alih-alih teks.
--verbose	Mencetak setiap langkah validasi.

Keluaran

✓ Schema 'spec-driven' is valid

Tanpa nama, setiap skema proyek mendapatkan satu baris di bawah header Validation Results:. Skema yang gagal mencantumkan masalahnya dan eksekusi keluar dengan kode 1:

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

openspec schema fork

Menyalin skema yang sudah ada ke proyek agar dapat disesuaikan.

openspec schema fork spec-driven my-flow

Argumen

Argumen	Deskripsi
source	Skema yang akan disalin, dari lokasi sumber mana pun.
name	Nama untuk salinan. Kebab-case (my-workflow). Default: <source>-custom.

Opsi

Flag	Efek
--force	Menimpa skema tujuan yang sudah ada.
--json	Mencetak hasil sebagai JSON.

Keluaran

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

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

Hasil fork disimpan di openspec/schemas/, dan field name: di schema.yaml ditulis ulang menjadi nama baru:

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

Tujuan yang sudah ada menyebabkan error kecuali Anda menyertakan --force. Fork yang mempertahankan nama sumber akan menyembunyikan skema asli.

openspec schema init

Membuat skema lokal proyek baru dengan templat awal.

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

Tanpa --description dan tanpa --artifacts di terminal interaktif, init akan meminta deskripsi, daftar periksa artefak, dan apakah skema akan dijadikan default proyek. Di luar terminal, perintah menggunakan default di bawah ini.

Argumen

Argumen	Deskripsi
name	Nama untuk skema baru. Kebab-case (my-workflow).

Opsi

Flag	Efek
--description <text>	Deskripsi skema. Default: Custom workflow schema for <name>.
--artifacts <list>	ID artefak yang dipisahkan koma dari proposal, specs, design, tasks. Default: keempatnya.
--default	Menulis schema: <name> ke openspec/config.yaml atau openspec/config.yml yang ada. Membuat openspec/config.yaml jika keduanya tidak ada. Perubahan baru menggunakan skema ini.
--no-default	Melewati prompt tentang default.
--force	Menimpa skema yang sudah ada dengan nama yang sama.
--json	Mencetak hasil sebagai JSON.

Pembuatan skema dan pembaruan konfigurasi --default merupakan satu operasi. Jika OpenSpec tidak dapat memvalidasi atau menulis konfigurasi, konfigurasi dan skema yang sudah ada tetap tidak berubah.

Keluaran

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

Tata letak di disk:

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

schema.yaml menghubungkan artefak yang dipilih dengan dependensinya. Ketika tasks disertakan, artefak tersebut juga mendapatkan fase apply yang melacak tasks.md. Gunakan skema ini dengan openspec new --schema my-schema.

openspec store

Membuat dan mengelola store: repositori OpenSpec mandiri yang terdaftar di mesin Anda.

openspec store setup team-context --path ~/openspec/team-context   # buat dan daftarkan
openspec store register ~/stores/design-system                     # daftarkan checkout yang sudah ada
openspec store list                                                # lihat yang terdaftar

Pendaftaran disimpan dalam registri per mesin: ~/.local/share/openspec/stores/registry.yaml, atau $XDG_DATA_HOME/openspec/stores/registry.yaml ketika XDG_DATA_HOME diset. Setiap subperintah menerima --json untuk mencetak laporan terstruktur alih-alih teks. Menjalankan openspec store dengan subperintah yang hilang atau tidak dikenal keluar dengan kode 1 dan mencantumkan subperintah tersebut.

Subperintah	Fungsinya
setup [id]	Membuat folder store dan mendaftarkannya.
register [path]	Mendaftarkan folder store yang sudah ada.
unregister <id>	Melupakan pendaftaran. Folder tetap ada di disk.
remove <id>	Melupakan pendaftaran dan menghapus folder.
list (alias ls)	Mencantumkan store terdaftar.
doctor [id]	Memeriksa pendaftaran, metadata, dan status Git untuk store terdaftar.

openspec store setup

Membuat folder store dan mendaftarkannya.

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

Di terminal interaktif, setup meminta nama dan lokasi yang belum diberikan dan mengonfirmasi sebelum membuat apa pun. Di luar terminal, nama atau --path yang hilang keluar dengan kode 1 beserta flag yang harus diberikan. Menjalankan ulang setup untuk store yang sudah terdaftar melaporkan Registry: already registered.

setup keluar dengan kode 1 dengan store_setup_inside_git_repo ketika --path berada di dalam repositori Git lain, karena menginisialisasi store di sana akan menyarangkan satu repositori di repositori lain. --no-init-git tidak membuat repositori, sehingga melewatkan pemeriksaan tersebut. Gunakan opsi ini untuk menyimpan store di ~/openspec/<id> ketika direktori home Anda sendiri adalah repositori Git, misalnya repositori dotfiles.

Argumen

Argumen	Deskripsi
id	Nama store. Ini menjadi id yang Anda berikan ke --store.

Opsi

Flag	Efek
--path <path>	Folder tempat store berada (~ diperluas).
--init-git	Menginisialisasi repositori Git dengan commit awal. Default.
--no-init-git	Melewati semua aksi Git: tanpa init, tanpa commit awal.
--remote <url>	Sumber kloning kanonik yang dicatat di store.yaml.

Keluaran

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

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

--json melaporkan apa yang dibuat dan di mana pendaftarannya:

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

openspec store register

Mendaftarkan folder store yang sudah ada, misalnya store rekan setim yang Anda kloning.

openspec store register ~/stores/design-system

Folder harus berisi root openspec/ yang sehat. Jika .openspec-store/store.yaml ada, register menggunakan kembali id yang tercatat. Tanpanya, register bertanya sebelum membuat metadata tersebut. Di luar terminal interaktif, sertakan --yes sebagai gantinya. Sebuah mesin dapat mendaftarkan satu checkout per id store. Jalur kedua di bawah id yang sama, atau jalur yang sama di bawah id kedua, keluar dengan kode 1.

Argumen

Argumen	Deskripsi
path	Folder store yang akan didaftarkan (~ diperluas). Wajib.

Opsi

Flag	Efek
--id <id>	Id store. Default ke metadata atau nama folder.
--yes	Mengonfirmasi pembuatan metadata identitas store untuk root OpenSpec yang sehat.

Keluaran

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

--json mencetak bentuk dokumen yang sama seperti store setup --json.

openspec store unregister

Melupakan pendaftaran. Folder tetap ada di disk.

openspec store unregister design-system

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

openspec store remove

Melupakan pendaftaran dan menghapus folder.

openspec store remove design-system --yes

Secara interaktif, remove bertanya sebelum menghapus. Dengan --json atau di luar terminal interaktif, penghapusan memerlukan --yes:

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

remove keluar dengan kode 1 dan tidak menghapus apa pun ketika folder tidak memiliki metadata store yang cocok, atau ketika folder berisi store terdaftar lain (misalnya store yang disertakan sebagai submodule Git). Dalam kasus itu, error-nya adalah store_remove_contains_registered_store: jalankan openspec store unregister <nested-id> terlebih dahulu, atau openspec store unregister <id> untuk melupakan store tanpa menghapus file.

Opsi

Flag	Efek
--yes	Mengonfirmasi penghapusan folder store lokal.

Keluaran

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

openspec store list

Mencantumkan store terdaftar. ls adalah alias.

openspec store list

OpenSpec stores (2)

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

Jika tidak ada yang terdaftar, list mencetak No stores registered. serta perintah setup dan register untuk dijalankan berikutnya.

openspec store doctor

Memeriksa pendaftaran, metadata, dan status Git untuk store terdaftar.

openspec store doctor                # semua store terdaftar
openspec store doctor team-context  # satu store

Keluaran

Store doctor

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

Kode keluar

• 0: laporan dicetak, bahkan ketika store melaporkan masalah.
• 1: laporan tidak dapat dijalankan (misalnya id store tidak dikenal).

openspec doctor

Melaporkan kesehatan relasi untuk root OpenSpec yang telah diresolusikan.

openspec doctor                       # root openspec/ terdekat di atas cwd Anda
openspec doctor --store team-context  # store terdaftar sebagai root

Doctor bersifat hanya-baca: perintah ini tidak pernah melakukan clone, sinkronisasi, atau perbaikan. Perintah ini melaporkan apakah root sehat dan apakah setiap referensi yang dideklarasikan dalam openspec/config.yaml dapat diresolusikan di mesin ini. Jika tidak ada root di atas cwd Anda dan tidak ada --store, perintah ini keluar dengan kode 1 dan menyebutkan store terdaftar Anda.

Opsi

Flag	Efek
--store <id>	Gunakan store terdaftar sebagai root OpenSpec, bukan proyek saat ini.
--json	Cetak laporan kesehatan sebagai JSON.

Keluaran

Doctor

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

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

Dengan --store, root adalah store dan laporan menambahkan baris store:

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

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

References
  (none declared)

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

Kode keluar

• 0: laporan tercetak, termasuk saat laporan mencantumkan masalah.
• 1: tidak ada root yang diresolusikan (tidak ada openspec/ di atas cwd Anda dan tidak ada --store), atau id --store tidak dikenal.

openspec context

Mencetak konteks kerja untuk root OpenSpec yang telah diresolusikan: root beserta setiap store yang direferensikan dan dideklarasikan dalam openspec/config.yaml, masing-masing dengan perintah fetch.

openspec context                       # root openspec/ terdekat di atas cwd Anda
openspec context --store team-context  # store terdaftar sebagai root
openspec context --json                # ringkasan agen

Referensi yang tidak dapat diresolusikan di mesin ini akan masuk ke bagian Not available on this machine, masing-masing dengan cara memperbaikinya.

Opsi

Flag	Efek
--store <id>	Gunakan store terdaftar sebagai root OpenSpec, bukan proyek saat ini.
--json	Cetak ringkasan agen sebagai JSON.
--code-workspace <path>	Juga tulis file workspace VS Code untuk kumpulan ini.
--force	Timpa file --code-workspace yang sudah ada.

Keluaran

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

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

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

Dengan --store, store menjadi seluruh kumpulan:

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

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

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

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

Menulis file workspace

--code-workspace menulis file workspace VS Code di path yang Anda berikan: satu folder untuk root, satu folder ref:<id> per store yang direferensikan dan tersedia. Referensi yang tidak tersedia dilewati dan disebutkan dalam baris ringkasan, Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). Ringkasan dicetak ke stderr, sehingga stdout --json tetap berupa satu dokumen JSON. Jika file sudah ada, perintah keluar dengan kode 1 kecuali Anda meneruskan --force.

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

Kode keluar

• 0: laporan tercetak.
• 1: tidak ada root yang diresolusikan (tidak ada openspec/ di atas cwd Anda dan tidak ada --store), atau penulisan --code-workspace ditolak.## openspec workset

Menyusun, menyimpan, dan membuka tampilan kerja pribadi. Workset adalah daftar folder bernama yang tersimpan yang Anda gunakan bersama-sama.

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

Subcommand	Apa yang dilakukannya
create [name]	Menyusun dan menyimpan tampilan kerja bernama dari folder yang Anda pilih.
list, ls	Menampilkan workset tersimpan beserta anggotanya.
open <name>	Membuka workset tersimpan di alat Anda (jendela editor atau sesi agen).
remove <name>	Menghapus workset tersimpan (folder anggota tidak pernah disentuh).

Workset sepenuhnya lokal:

• Keadaannya berada di satu folder: ~/.local/share/openspec/worksets/ ($XDG_DATA_HOME/openspec/worksets/ ketika diatur; %LOCALAPPDATA%\openspec\worksets\ di Windows).
• Tidak ada yang ditulis ke folder anggota, dan tidak ada yang dikomit atau dibagikan.
• Menghapus satu folder itu menghapus setiap jejak.

openspec workset create

Menyimpan tampilan kerja bernama dari folder.

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

Di terminal interaktif, create akan meminta apa pun yang tidak disediakan oleh flag: nama, folder satu per satu, alat, lalu tawaran untuk membuka workset sekarang. Di luar terminal interaktif, nama atau anggota yang hilang adalah kesalahan. Nama yang sudah tersimpan selalu menjadi kesalahan. Hapus terlebih dahulu.

Argumen

Argumen	Apa itu
name	Nama workset. Kebab-case: huruf kecil, angka, tanda hubung tunggal. Wajib di luar terminal interaktif.

Opsi

Flag	Efek
--member <member>	Folder anggota sebagai <path> atau <name>=<path>, dapat diulang. Yang pertama adalah primer. Path harus berupa folder yang ada, dan label defaultnya adalah nama folder itu sendiri.
--tool <id>	Alat pilihan untuk membuka workset ini. Id bawaan: code (VS Code), cursor (Cursor). claude dan codex dinonaktifkan sementara.
--json	Mencetak workset tersimpan sebagai JSON.

Keluaran

Saved workset 'checkout' (2 members) to your machine.
Open it any time with: openspec workset open checkout

openspec workset list

Menampilkan workset tersimpan beserta anggotanya, diurutkan berdasarkan nama.

openspec workset list   # alias: ls

Opsi

Flag	Efek
--json	Mencetak workset sebagai JSON.

Keluaran

Satu blok per workset: nama, alatnya bila ada, lalu satu baris name path per anggota. Jika tidak ada yang tersimpan, list mencetak No worksets saved. Create one with: openspec workset create.

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

Dengan --json:

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

openspec workset open

Membuka workset tersimpan di alat Anda. Alat editor (code, cursor) mendapatkan file .code-workspace yang dihasilkan. Jendela terbuka dan perintah kembali. Alat agen CLI (claude, codex) akan mengambil alih terminal ini dengan semua anggota terlampir. Keduanya dinonaktifkan sementara selama alur tersebut dikerjakan ulang, jadi untuk saat ini workset dibuka di IDE.

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

Argumen

Argumen	Apa itu
name	Workset yang akan dibuka.

Opsi

Flag	Efek
--tool <id>	Buka dengan alat ini hanya sekali ini.

Tanpa --tool dan tanpa alat tersimpan, open akan meminta Anda memilih alat yang terinstal. Di luar terminal interaktif, perintah akan keluar dengan kode 1.

• Folder anggota yang tidak lagi ada dilewati dengan peringatan. Ketika primer hilang, anggota berikutnya yang masih ada menjadi primer untuk pembukaan ini. Ketika tidak ada folder anggota yang ada, pembukaan gagal.
• --json ditolak: open menyerahkan terminal ke alat dan tidak memiliki mode JSON.
• Ketika peluncuran gagal, kesalahan diakhiri dengan rute manual: path file workspace dan daftar anggota.

Kode keluar

• Mencerminkan alat: perintah keluar dengan kode keluar alat itu sendiri, dan sinyal menjadi 128+n (130 setelah Ctrl-C).
• 1: workset tidak dikenal, tidak ada folder anggota yang tersedia, atau tidak ada alat yang dapat digunakan.

openspec workset remove

Menghapus workset tersimpan dan file .code-workspace yang dihasilkannya. Folder anggota tidak pernah disentuh.

openspec workset remove checkout --yes

Di terminal interaktif, remove menampilkan workset dan meminta konfirmasi. Dengan --json, atau di luar terminal, perintah memerlukan --yes dan keluar dengan kode 1 tanpanya.

Opsi

Flag	Efek
--yes	Mengonfirmasi penghapusan secara non-interaktif.
--json	Mencetak penghapusan sebagai JSON.

Keluaran

Removed workset 'checkout'. Member folders were not touched.

openspec version

Melaporkan versi OpenSpec yang berjalan dan bagaimana salinan ini diinstal.

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

Tanpa --check, perintah ini lokal dan tidak menghubungi registry. Perintah ini berfungsi di luar proyek OpenSpec. Flag openspec --version yang ada tetap menjadi bentuk terpendek dan hanya mencetak nomor versi polos.

Opsi

Flag	Efek
--json	Mencetak satu dokumen JSON berversi alih-alih teks.
--check	Memeriksa registry yang dikonfigurasi untuk rilis yang lebih baru.

Keluaran

Untuk instal npm global:

OpenSpec 1.13.2 (npm, global)

Lingkup instal adalah global, project, temporary untuk runner sementara seperti npx, source untuk checkout, atau standalone untuk instal standalone. OpenSpec menghilangkan detail yang tidak dapat diidentifikasi alih-alih menebak.

--json menyimpan detail yang tidak diketahui sebagai nilai null eksplisit:

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

Dengan --check, pembaruan yang tersedia menambahkan versi terbaru dan perintah ketika OpenSpec dapat mengidentifikasi perintah yang aman untuk instal tersebut:

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

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

Nilai status pembaruan:

Status	Keterangan
available	Registry mengembalikan versi aman yang lebih baru dari versi yang berjalan.
current	Pemeriksaan selesai dan tidak menemukan versi yang lebih baru.
disabled	Pengaturan privasi atau pemeriksaan pembaruan yang ada memblokir akses registry. latest bernilai null.
offline	Registry tidak tersedia atau mengembalikan respons yang tidak dapat digunakan. latest bernilai null.

Untuk instal standalone, perintah pembaruan adalah openspec install.

DO_NOT_TRACK, opt-out telemetri, OPENSPEC_NO_UPDATE_CHECK, deteksi CI, dan override registry non-HTTPS yang ditolak menonaktifkan pemeriksaan. Pemeriksaan yang dinonaktifkan dan offline tetap keluar dengan kode 0 karena ketersediaan pembaruan bersifat saran. Perintah ini tidak pernah meningkatkan OpenSpec; canSelfUpgrade hanya melaporkan apakah jalur openspec update yang ada dapat secara aman meningkatkan salinan ini.

Kode keluar

• 0: laporan lokal dicetak, termasuk pemeriksaan pembaruan yang dinonaktifkan atau offline.
• 1: sintaks perintah tidak valid, seperti opsi --upgrade yang tidak didukung.

openspec install

Menginstal openspec standalone. Jalankan perintah ini dari instalasi npm atau Homebrew untuk berpindah, atau dari instalasi standalone untuk memperbaruinya di tempat.

openspec install          # rilis terbaru
openspec install 1.15.0   # rilis tertentu

Perintah ini menjalankan skrip instalasi, yang memilih rilis terbaru yang seluruh filenya telah dilampirkan serta file yang sesuai untuk mesin Anda, lalu memverifikasinya terhadap SHA256SUMS rilis tersebut:

• Dari package manager: menginstal ke ~/.local/bin (Windows: %LOCALAPPDATA%\Programs\openspec) dan menampilkan perintah untuk menghapus salinan lama, misalnya npm uninstall -g @fission-ai/openspec. Perintah ini sendiri tidak pernah menghapus salinan tersebut.
• Dari instalasi standalone: menggantikan file yang sedang berjalan tepat di tempatnya, dengan nama yang sama.

Setelah itu, perintah ini menampilkan salinan openspec mana yang kini dijalankan, karena salinan dari package manager yang berada lebih awal di PATH Anda akan terus terpakai sampai Anda menghapusnya.

Argumen

Argumen	Deskripsi
version	Rilis yang akan diinstal, misalnya 1.15.0. Opsional; secara bawaan menggunakan yang terbaru.

OPENSPEC_INSTALL_DIR dan OPENSPEC_INSTALL_NAME dapat digunakan untuk memilih folder atau nama file lain.

Kode keluar

• 0: berhasil diinstal.
• 1: versi yang diberikan bukan versi rilis, atau proses unduh atau instalasi gagal. Salinan Anda saat ini dibiarkan apa adanya.

openspec feedback

Mengirimkan umpan balik tentang OpenSpec.

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

CLI mengajukan pesan Anda sebagai issue GitHub di repo Fission-AI/OpenSpec melalui CLI gh Anda. Judulnya menjadi Feedback: <message>. Isi issue menggunakan judul bagian dari formulir bug: pesan Anda di bawah What happened, teks --body Anda di bawah Details, serta bagian Minimal steps to reproduce yang meminta Anda menambahkan langkah-langkahnya, karena CLI tidak dapat mengisinya. Footer menambahkan versi CLI, platform, dan timestamp. Issue tersebut mendapat label feedback. Jika repo tidak mendefinisikan label tersebut, CLI mencoba lagi tanpa label itu dan memberitahukannya.

Argumen

Argumen	Deskripsi
message	Ringkasan satu baris. Menjadi judul issue. Wajib.

Opsi

Flag	Efek
--body <text>	Deskripsi yang lebih panjang, ditambahkan ke body issue.

Output

Jika berhasil:

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

Tanpa gh yang terinstal, atau jika gh belum login, tidak ada yang dikirimkan. CLI menampilkan umpan balik Anda yang sudah diformat di antara penanda --- FORMATTED FEEDBACK ---, lalu sebuah tautan yang membuka formulir laporan bug dengan bagian judul, what happened (pesan dan teks --body Anda), versi CLI, dan lingkungan (platform dan versi Node) yang sudah terisi. Anda melengkapi sisa formulir tersebut di browser. Pada jalur belum-login, ditambahkan To auto-submit in the future: gh auth login.

Kode keluar

• 0: issue dibuat, atau fallback pengiriman manual dijalankan (tidak ada gh, atau gh belum login).
• 1: tidak ada pesan yang diberikan.
• Kode milik gh sendiri: gh gagal setelah autentikasi (jaringan, rate limit, issues dinonaktifkan). CLI menampilkan ulang umpan balik Anda dan URL pengiriman manual terlebih dahulu.

openspec completion

Menginstal atau menghasilkan shell completion.

openspec completion install        # deteksi shell Anda, instal, atur konfigurasi
openspec completion generate zsh   # cetak skrip ke stdout

Shell yang didukung: zsh, bash, fish, powershell. Setiap subcommand menerima argumen shell opsional. Jika dihilangkan, CLI akan mendeteksi shell Anda dari lingkungan.

Subcommand	Fungsi
generate [shell]	Mencetak skrip completion ke stdout.
install [shell]	Menulis skrip dan mengonfigurasi file startup shell Anda.
uninstall [shell]	Menghapus skrip dan blok konfigurasi.

Jika diinstal dengan Nix, completion sudah terpasang sejak awal: paket flake menyertakan skrip Bash, Fish, dan Zsh di lokasi standar, sehingga install tidak diperlukan (Instalasi).

openspec completion generate

Mencetak skrip dan tidak menulis apa pun.

#compdef openspec

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

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

openspec completion install

Menulis skrip dan mengedit konfigurasi shell Anda. Perubahan konfigurasi diletakkan di antara penanda # OPENSPEC:START dan # OPENSPEC:END. Skrip yang sudah ada dicadangkan terlebih dahulu (salinan .backup-<timestamp>).

Shell	Lokasi skrip	Konfigurasi yang diedit
zsh	~/.zsh/completions/_openspec	$ZDOTDIR/.zshrc jika ZDOTDIR berupa path absolut, jika tidak ~/.zshrc
bash	~/.local/share/bash-completion/completions/openspec	~/.bashrc
fish	~/.config/fish/completions/openspec.fish	Tidak ada: fish memuatnya secara otomatis.
powershell	OpenSpecCompletion.ps1 di sebelah profile Anda	$PROFILE

Dengan Oh My Zsh terinstal, skrip ditempatkan di $ZSH_CUSTOM/completions/_openspec sebagai gantinya (bawaan ~/.oh-my-zsh/custom/completions/_openspec).

ZDOTDIR yang relatif atau diawali ~ akan diabaikan, dan ~/.zshrc yang diedit sebagai gantinya. Menjalankan install lagi saat skrip sudah versi terkini tetap akan menambahkan blok ke .zshrc yang dibaca oleh zsh.

Opsi

Flag	Efek
--verbose	Juga mencetak path instalasi, path cadangan jika ada, dan file konfigurasi mana yang diedit.

Output

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Menghapus skrip dan blok konfigurasi yang ditandai. Perintah ini meminta konfirmasi sebelum menyentuh konfigurasi Anda (bawaan: Tidak).

Untuk zsh, perintah ini membersihkan .zshrc yang diedit oleh install, dan juga ~/.zshrc ketika instalasi lama meninggalkan blok di sana dalam kondisi ZDOTDIR. Jika ada blok yang tidak dapat dihapus, uninstall akan menyebutkan nama filenya dan keluar dengan kode 1.

Opsi

Flag	Efek
-y, --yes	Melewati prompt konfirmasi.

Output

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

Kode keluar

• 0: skrip berhasil dibuat, diinstal, atau dihapus. Uninstall yang dibatalkan juga keluar dengan kode 0.
• 1: shell tidak didukung atau tidak terdeteksi, atau salah satu langkah install atau uninstall gagal.

openspec change

Bentuk kata benda dari show, list, dan validate yang sudah tidak digunakan (deprecated). Setiap kali dijalankan, perintah ini memberi peringatan dan mengarahkan ke perintah verb-first, lalu tetap berjalan:

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

Deprecated	Gunakan sebagai gantinya
openspec change show <name>	openspec show <name>
openspec change list	openspec list
openspec change validate <name>	openspec validate <name> (semua change: openspec validate --changes)

Flag-flag didokumentasikan di bagian perintah verb-first.

openspec spec

Bentuk kata benda dari show, list, dan validate yang sudah tidak digunakan (deprecated). Setiap kali dijalankan, perintah ini memberi peringatan dan mengarahkan ke perintah verb-first, lalu tetap berjalan:

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

Deprecated	Gunakan sebagai gantinya
openspec spec show <id>	openspec show <id>
openspec spec list	openspec list --specs
openspec spec validate <id>	openspec validate <id> (semua spec: openspec validate --specs)

Flag-flag didokumentasikan di bagian perintah verb-first.