CLI

openspec komut satırı komutları.

Komutlar

Kurulum

Komut	Ne işe yarar
openspec init	Bir projede OpenSpec'i başlatır.
openspec update	OpenSpec'in yüklü talimat dosyalarını günceller.
openspec config	Küresel yapılandırmayı görüntüler ve değiştirir.

Değişiklikler ve spesifikasyonlar

Komut	Ne işe yarar
openspec list	Değişiklikleri listeler veya --specs ile spesifikasyonları listeler.
openspec show	Bir değişikliği veya spesifikasyonu, markdown veya JSON olarak yazdırır.
openspec view	Spesifikasyonların ve değişikliklerin tek ekranda gösterilen panosunu açar.
openspec validate	Değişiklikleri ve spesifikasyonları yapısal sorunlar açısından kontrol eder.
openspec archive	Tamamlanmış bir değişikliği arşive taşır ve ana spesifikasyonları günceller.

Akışlar ve şemalar

Akış sırasında ajan bu komutların çoğunu çalıştırır.

Komut	Ne işe yarar
openspec new	Yeni bir değişiklik dizini oluşturur.
openspec status	Tek bir veya tüm etkin değişikliklerin artefakt tamamlanma durumunu gösterir.
openspec instructions	Bir artefakt oluşturulması, uygulanması veya arşivlenmesi için talimatlar verir.
openspec templates	Bir şemanın artefaktları için çözümlenmiş şablon yollarını listeler.
openspec schemas	Kullanılabilir akış şemalarını listeler.
openspec schema	Bir şemayı inceler, dallandırır veya oluşturur (deneysel).

Çoklu depo (beta)

Komut	Ne işe yarar
openspec store	Mağaza oluşturur ve yönetir: makinenize kaydedilmiş bağımsız OpenSpec depoları.
openspec doctor	Çözümlenmiş OpenSpec kökü için ilişki sağlığını raporlar.
openspec context	Çözümlenmiş OpenSpec kökü için çalışma bağlamını yazdırır.
openspec workset	Kişisel çalışma görünümleri oluşturur, korur ve açar.

Yardımcı araçlar

Komut	Ne işe yarar
openspec version	Yüklü sürümü raporlar ve isteğe bağlı olarak güncelleme kontrolü yapar.
openspec install	Node.js olmadan çalışan bağımsız openspec bileşenini yükler.
openspec feedback	OpenSpec hakkında geri bildirim gönderir.
openspec completion	Kabuk tamamlamalarını (completions) yükler veya üretir.

Kullanımı durdurulmuş

Komut	Ne işe yarar
openspec change	Değişiklikler için show, list ve validate komutlarının isim (noun) biçimidir. CLI uyarı verir ve fiil-öncelikli komutlara yönlendirir.
openspec spec	Spesifikasyonlar için show, list ve validate komutlarının isim biçimidir, aynı uyarı ile.

Her komut -h, --help argümanını alır. Sadece openspec komutu ayrıca şu argümanları da alır:

• -V, --version: CLI sürümünü yazdırır.
• --no-color: Renkli çıktıyı devre dışı bırakır.

openspec init

OpenSpec'i bir projede başlatır.

openspec init                        # geçerli dizin, etkileşimli araç seçici
openspec init --tools claude,cursor  # belirli araçları kur, sorma
openspec init --tools none           # yalnızca openspec/ yapısı, araç dosyası yok

--tools belirtilmediğinde, init etkileşimli bir terminallerde araç seçmenizi ister. Etkileşimli olmayan ortamda projede algıladığı araçları kurar. Hiç algılanamazsa 1 koduyla çıkar ve geçerli kimlikleri listeler.

Yalnızca depo store'su

openspec/config.yaml dosyasında bir store: satırı olduğunda ve depoda yerel spec veya değişiklik bulunmadığında, init'i depo kökünden çalıştırın:

# Claude Code entegrasyon dosyalarını kod deposuna yükle
openspec init --tools claude

• Entegrasyon dosyaları: kod deposuna yazılır.
• openspec/config.yaml: bayt bayt korunur.
• openspec/specs/ ve openspec/changes/: kod deposunda oluşturulmaz.

Alt dizinden init çalıştırmak 1 koduyla çıkar ve sizi depo kökünden çalıştırmaya yönlendirir. --language da 1 koduyla çıkar çünkü dil ayarları harici store'un yapılandırmasına aittir. Init'i store kökünde çalıştırın veya o yapılandırmayı doğrudan düzenleyin.

Argümanlar

Argüman	Nedir
path	Başlatılacak proje dizini. Varsayılan: geçerli dizin. Yoksa oluşturulur.

Seçenekler

Bayrak	Etki
--tools <tools>	Virgülle ayrılmış araç kimlikleri, all veya none. Seçiciyi atlar. Kimlikler Desteklenen araçlar sayfasında listelenir.
--language <language>	Yeni proje yapılandırmasına dil talimatı ekler. Deponun store: satırı harici bir store'a işaret ediyorsa reddedilir.
--force	Eski OpenSpec düzenlerinden gelen dosyaları sormadan kaldırır. Etkileşimli çalıştırmalarda önce temizliği onaylarsınız.
--profile <profile>	Bu çalıştırma için global yapılandırma profilini geçersiz kılar: core (standart iş akışı seti) veya custom (global yapılandırmada kaydedilen iş akışları).
--no-animation	Animasyonlu ekran yerine statik bir karşılama ekranı gösterir.

Çıktı

Seçilen her araç, OpenSpec'in becerilerini ve komutlarını kendi dizininde alır:

▌ OpenSpec yapısı oluşturuldu
✔ Claude Code için kurulum tamamlandı

OpenSpec Kurulumu Tamamlandı

Oluşturulan: Claude Code
6 beceri ve 6 komut .claude/ içinde
Yapılandırma: openspec/config.yaml (şema: spec-driven)

Başlangıç:
  İlk değişikliğinizi başlatın: /opsx:propose "fikriniz"

Yeni komutların etkili olması için IDE'nizi yeniden başlatın.

--tools none yalnızca openspec/config.yaml oluşturur. Zaten başlatılmış bir projede, init kurulu dosyaları yerinde yeniden yazar ve özet Refreshed: Claude Code ve Config: openspec/config.yaml (exists) şeklinde görünür.

Çıkış kodları

• 0: kurulum tamamlandı.
• 1: geçersiz --tools veya --profile değeri, araç algılanmayan ve --tools belirtilmeyen etkileşimli olmayan çalıştırma, veya geçersiz yalnızca-store çağrısı.

openspec update

OpenSpec'in kurulu talimat dosyalarını günceller.

openspec update             # dosyaları CLI'dan eski olan araçları yenile
openspec update --force     # dosyalar güncel olsa bile yeniden yaz
openspec update --dry-run   # güncellemenin ne değiştireceğini listele, hiçbir şey değiştirme

update, init'in yapılandırdığı araçları bulur ve ürettikleri dosyaları CLI'in sürümüyle karşılaştırır. Daha yeni bir OpenSpec sürümü mevcut olduğunda, önce CLI'i yükseltmeyi önerir, ardından yükseltilmiş sürümle yeniden çalıştırır. Kontrolü atlamak için OPENSPEC_NO_UPDATE_CHECK=1 ayarlayın.

Argümanlar

Argüman	Nedir
path	Güncellenecek proje dizini. Varsayılan: geçerli dizin.

Seçenekler

Bayrak	Etki
--force	Her yapılandırılmış aracın dosyalarını güncel olsalar bile yeniden yazar.
--dry-run	Güncellemenin ekleyeceği, değiştireceği veya sileceği her dosyayı raporlar ve hiçbir şey yazmaz. CLI yükseltme kontrolü yok, sorma yok. Zorunlu güncellemeyi önizlemek için --force ile birleştirin.
--json	--dry-run ile birlikte planı JSON olarak yazdırır. --dry-run olmadan 1 koduyla çıkar.

Güncellemeyi önizleme

--dry-run, etkileşimli olmayan bir çalıştırmanın yapacağı güncellemeyi planlar: aynı kod yolu, her yazma ve silme işlemi gerçekleştirilmek yerine kaydedilir. Gerçek güncellemenin dokunacağı her dosya listelenir, şunları içerir:

• OpenSpec dosyalarını bir aracın eski dizininden taşıma (.kimi/ → .kimi-code/, .windsurf/ → .devin/, .codex/ ve .agent/ → .agents/);
• profillerden önceki bir kurulumda global yapılandırmayı kaydetme;
• GitHub Copilot bulut agent dosyalarını senkronize etme;
• --force ile, yalnızca eski artefaktlarda bulunan araçları kurmak ve bu artefaktları temizlemek, emekli edilmiş global Codex istemlerini de içerecek şekilde.

openspec update --dry-run

2 dosya değişecek:
  güncelle  .claude/skills/openspec-propose/SKILL.md  (claude)
  ekle      ~/.config/openspec/config.json  (openspec)

--dry-run --json aynı planı tek bir JSON belgesi olarak yazdırır:

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

Alan	Ne içerir
changes[].path	Proje-göreli yol. Proje dışındaki bir dosya, örneğin global bir beceri veya global yapılandırma, ana dizininizden ~/... olarak gösterilir veya ana dizin dışındaysa mutlak yol olarak gösterilir.
changes[].action	add, update veya delete. Yeni baytları eskiyle eşleşen bir dosya listelenmez.
changes[].tool	Dosyanın ait olduğu yapılandırılmış araç, örneğin claude. OpenSpec'in kendisine ve tek bir araca ait olmayan dosyalar, global yapılandırma ve eski-artefakt temizliği, openspec olarak gösterilir.
notes[]	Terminal kullanıcısının sorgulanacağı bir adım için { code, message }. legacy-tool-directories: etkileşimli bir çalıştırmanın önce sorduğu bir taşıma; changes bunu yapılmış olarak listeler. legacy-artifacts: OpenSpec'in eski düzeninden gelen dosyalar bulundu, örneğin openspec-proposal.md slash komutları veya AGENTS.md içindeki OpenSpec işaret bloğu. --force olmadan etkileşimli olmayan güncelleme onlara dokunmaz, bu yüzden changes de dokunmaz; --dry-run --force temizliklerini listeler. Normal bir yenileme için boştur.
failures[]	Gerçek güncellemenin başarısız olacağı her araç için { tool, error }, yapamayacağı bir yazma dahil: dosya gereken yerde dizin, dizin gereken yerde dosya veya yazma izni olmayan bir dosya veya klasör. O araç için changes, gerçek güncellemenin durduğu yerde durur; diğer araçlar yine de planlanır. Diskin yazma sırasında bildirdiği başarısızlıklar, örneğin alan dışı kalma, öngörülemez.

Planlamadan önceki bir başarısızlık, örneğin OpenSpec dizini yoksa, yine tam olarak bir JSON belgesi yazdırır: boş plan artı severity, code (update_error) ve message içeren bir status dizisi. Çıkış kodu 1'dir.

Çıktı

Her aracın dosyaları CLI sürümüyle eşleştiğinde:

✓ Tüm 1 araç güncel (v1.7.0)
  Araçlar: claude

Dosyaları yine de yenilemek için --force kullanın.

Bir aracın dosyaları eski bir CLI'dan geldiğinde (veya --force ile, bunun yerine Force updating 1 tool(s): claude yazdırır):

1 araç güncelleniyor: claude (1.6.0 → 1.7.0)

✔ Claude Code güncellendi

✓ Güncellendi: Claude Code (v1.7.0)
Araçlar: Claude Code

Değişikliklerin etkili olması için IDE'nizi yeniden başlatın.

OpenSpec olmayan bir dizinde, update reddeder:

✖ Hata: OpenSpec dizini bulunamadı. Önce 'openspec init' çalıştırın.

Çıkış kodları

• 0: dosyalar güncellendi veya her şey zaten güncel.
• 1: yolda OpenSpec dizini yok veya güncelleme başarısız oldu.

openspec config

Global yapılandırmayı görüntüler ve değiştirir.

openspec config list                  # mevcut ayarları gör
openspec config set delivery skills   # tek bir değeri değiştir
openspec config profile               # etkileşimli iş akışı seçici

Alt komut	Ne yapar
path	Yapılandırma dosyası konumunu yazdırır.
list	Mevcut tüm ayarları gösterir.
get <key>	Tek bir değeri, ham ve scriptileştirilebilir şekilde yazdırır.
set <key> <value>	Bir değer ayarlar, tipini dönüştürür.
unset <key>	Varsayılanın uygulanması için bir anahtarı kaldırır.
reset	Tüm yapılandırmayı varsayılanlara sıfırlar.
edit	Yapılandırma dosyasını $EDITOR içinde açar.
profile [preset]	Teslim modunu ve iş akışlarını yapılandırır.

Yapılandırma makineniz için globaldir ve config path işaret ettiği yerde JSON olarak saklanır: ayarlanmışsa $XDG_CONFIG_HOME/openspec/config.json, aksi takdirde ~/.config/openspec/config.json (macOS, Linux) veya %APPDATA%\openspec\config.json (Windows). Her alt komut --scope <scope> kabul eder, ancak bugün yalnızca global çalışır. Başka herhangi bir kapsam 1 koduyla çıkar ve Error: Project-local config is not yet implemented mesajını verir.

openspec config path

openspec config path

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

openspec config list

openspec config list          # okunabilir ayarlar ve profil özeti
openspec config list --json   # ham yapılandırma JSON olarak

Seçenekler

Bayrak	Etki
--json	Yapılandırma nesnesini JSON olarak yazdırır.

Çıktı

Her ayar, ardından değerleri açık veya varsayılan olarak işaretleyen bir profil özeti:

featureFlags: {}
profile: core
delivery: both

Profil ayarları:
  profile: core (varsayılan)
  delivery: both (varsayılan)
  workflows: propose, explore, apply, update, sync, archive (core profilinden)

openspec config get

openspec config get delivery

Argümanlar

Argüman	Nedir
key	Okunacak anahtar. Noktalar iç içe değerlere ulaşır (featureFlags.workspaces).

Çıktı

Scriptler için hazır, yalın değer. Nesneler sıkıştırılmış JSON olarak yazdırılır:

both

Çıkış kodları

• 0: değer yazdırıldı.
• 1: anahtarın değeri yok, hiçbir şey yazdırılmadı.

openspec config set

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

Argümanlar

Argüman	Nedir
key	Yazılacak anahtar, iç içe değerler için noktalı.
value	Yeni değer. true/false boolean'a, sayısal string'ler sayıya dönüşür.

Seçenekler

Bayrak	Etki
--string	Değeri string olarak saklar, tip dönüştürmeyi atlar.
--allow-unknown	Şemanın bilmediği anahtarlara izin verir.

Çıktı

Set featureFlags.workspaces = true

Bilinmeyen anahtarlar ve geçersiz değerler hiçbir şey kaydedilmeden 1 koduyla başarısız olur:

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

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

Yapılandırma dosyası mevcut ancak bir JSON nesnesi tutmuyorsa, ister geçerli JSON olmadığından ister kökü null veya dizi gibi başka bir şey olduğundan, config set, config unset ve config profile 1 koduyla çıkar ve dosyayı değiştirmeden bırakır. openspec config edit ile düzeltin veya openspec config reset --all ile değiştirin:

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

Düzeltilene kadar telemetri ve güncelleme kontrolü kapalı kalır.

openspec config unset

openspec config unset delivery

Varsayılanın yeniden uygulanması için anahtarı kaldırır. Yerleşik varsayılanları olan anahtarlar her zaman ayarlı sayılır, bu yüzden hiç ayarlamamış olsanız bile başarı bildirir:

Unset delivery (reverted to default)

Hiçbir değeri olmayan bir anahtar Key "featureFlags.nothere" was not set yazdırır. Her iki durum da 0 koduyla çıkar. Ayrıştırılamayan bir yapılandırma dosyası, config set olduğu gibi 1 koduyla çıkar.

openspec config reset

openspec config reset --all      # onay ister
openspec config reset --all -y   # sormaz

Seçenekler

Bayrak	Etki
--all	Gerekli. Her şeyi sıfırlar.
-y, --yes	Onay sormasını atlar.

Çıktı

Configuration reset to defaults

--all olmadan 1 koduyla çıkar ve kullanım satırını yazdırır.

Çıkış kodları

• 0: sıfırlama yapıldı veya sormada hayır yanıtını verdiniz.
• 1: --all eksik.
• 130: sorma Ctrl-C ile iptal edildi.

openspec config edit

openspec config edit

Yapılandırma dosyasını $EDITOR içinde açar ($VISUAL'e düşer), eksikse önce varsayılanlarla oluşturur. Düzenleyici kapandığında dosya doğrulanır. Geçersiz JSON veya geçersiz yapılandırma 1 koduyla çıkar.

Düzenleyici değeri argümanlar ve tırnak içine alınmış yollar taşıyabilir, örneğin code --wait veya "/Applications/Sublime Text.app/Contents/SharedSupport/bin/subl" -w. Kabuk olmadan kelimeye ayrılır, bu yüzden $VAR, ~ ve ; harfi harfine iletilir. Başlatılamayan veya sıfır dışında bir kodla çıkan bir düzenleyici tek satırlık bir hata yazdırır ve 1 koduyla çıkar.

Yapılandırılmış düzenleyici yoksa 1 koduyla çıkar:

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

openspec config profile

openspec config profile        # etkileşimli seçici (terminal gerekir)
openspec config profile core   # core preset'ini doğrudan uygula

Argümanlar

Argüman	Nedir
preset	İsteğe bağlı preset adı. Yalnızca core mevcuttur. Core iş akışlarını seçer ve teslim ayarınızı korur.

Preset olmadan, etkileşimli bir seçici mevcut teslim ve iş akışlarınızı gösterir, her ikisini veya birini değiştirmenize izin verir (teslim: both, yalnızca skills veya yalnızca commands; iş akışları: onay kutusu listesi), farkı yazdırır ve OpenSpec projesi içinde sizin için openspec update çalıştırmayı önerir. Terminal dışında 1 koduyla çıkar:

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

Çıktı

Değişen yapılandırma projeler onları güncelleyene kadar ulaşmaz:

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

Çıkış kodları

• 0: profil kaydedildi veya mevcut ayarlarınızı korudunuz.
• 1: bilinmeyen preset, terminal yok veya önerilen openspec update başarısız oldu.
• 130: seçici Ctrl-C ile iptal edildi.

openspec list

Değişiklikleri veya --specs ile spec'leri listeler.

openspec list                    # etkin değişiklikler, en son değiştirilen önce
openspec list --archived         # arşivlenmiş değişiklikler
openspec list --all              # etkin ve arşivlenmiş değişiklikler
openspec list --specs            # gereksinim sayılarıyla spec'ler
openspec list --json             # makine tarafından okunabilir, çözümlenen kökü içerir

Satırlar, çözümlenen kök altındaki openspec/changes/ ve openspec/specs/ dizinlerinden gelir. Varsayılan değişiklik listesi openspec/changes/archive/ dizinini atlar.

Seçenekler

Bayrak	Etki
--specs	Değişiklikler yerine spec'leri listeler.
--changes	Değişiklikleri listeler. Bu varsayılandır.
--archived	Yalnızca arşivlenmiş değişiklikleri listeler. --specs ile birlikte kullanılamaz.
--all	Etkin ve arşivlenmiş değişiklikleri listeler. --specs ile birlikte kullanılamaz. --archived seçeneğine göre önceliklidir.
--sort <order>	recent (en son değiştirilen önce) veya name. Varsayılan: recent. Spec'ler her zaman ada göre sıralanır.
--json	Tablo yerine JSON yazdırır.
--store <id>	Geçerli proje yerine OpenSpec kökü olarak kayıtlı bir store kullanır.

Çıktı

Her değişiklik için bir satır: ad, görev durumu, son değiştirilme. Durum sütununda No tasks, 2/5 tasks veya ✓ Complete yazar.

Changes:
  add-rate-limit     No tasks      just now

--all, etkin ve arşivlenmiş değişiklikleri ayrı başlıklar altında gruplar. Her grup seçilen sıralama düzenini kullanır:

Changes:
  add-rate-limit     No tasks      just now

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

Specs:
  api     requirements 1

--json, görev sayılarını ve no-tasks, in-progress veya complete değerlerinden birine sahip bir status alanı ekler:

{
  "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"
  }
}

--archived veya --all ile her değişiklik nesnesi bir archived boolean değeri içerir. Birleştirilmiş dizi seçilen sıralama düzenini kullanır. Arşivlenmiş bir değişiklik, izlenen görev dosyasında işaretlenmemiş görevler olduğunda hâlâ in-progress durumuna sahip olabilir. Bu bayraklardan hiçbiri olmadan JSON yapısı değişmeden kalır.

Boş bir liste No active changes found., No archived changes found., No changes found. veya No specs found. yazdırır ve yine de 0 koduyla çıkar.

Bir değişiklik, doğrudan openspec/changes/ altındaki bir dizindir. Spec'lerden farklı olarak değişiklikler bir ad alanı klasörünün içine yerleştirilemez. Yalnızca bir değişikliği saran changes/mobile/ gibi bir klasör (changes/mobile/refresh-token/), not a change durumuyla listelenir ve ardından iç içe dizinlerin adlarını belirten bir uyarı gelir. --json, bu girdiyi bir nested dizisiyle işaretler ve üst düzey bir warnings dizisi ekler. show, status, validate ve archive, aynı mesajla klasörü reddeder. Bunu düzeltmek için değişikliği yukarı taşıyın ve ad alanını adına dahil edin:

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

Çıkış kodları

• 0: liste yazdırıldı, boş olsa bile.
• 1: OpenSpec kökü bulunamadı (bir projenin dışında, --store yok).

openspec show

Bir değişikliği veya spec'i markdown ya da JSON olarak yazdırır.

openspec show add-rate-limit              # değişiklik: proposal.md yazdırır
openspec show add-rate-limit --diff       # değişiklik: gereksinim delta farklarını ekler
openspec show api                         # spec: spec.md yazdırır
openspec show api --json --no-scenarios   # senaryo metni olmadan spec JSON

Ad verilmezse show, değişiklik mi spec mi olduğunu sorar, ardından seçilecek öğeleri listeler. Etkileşimli bir terminalin dışında 1 koduyla çıkar ve bunun yerine doğrudan biçimleri yazdırır.

Argümanlar

Argüman	Ne olduğu
item-name	Gösterilecek değişiklik veya spec, klasör adıyla (add-rate-limit, api).

Seçenekler

Bayrak	Etki
--json	Ham markdown yerine yapılandırılmış JSON yazdırır.
--type <change|spec>	Bir değişiklik ile bir spec aynı adı paylaştığında türü seçer.
--no-interactive	Hiçbir zaman soru sormaz: eksik ad bir hataya dönüşür.
--deltas-only	JSON, değişiklik: çıktıyı delta'larla sınırlar. Değişiklik JSON'u zaten yalnızca delta içerdiğinden çıktı düz --json ile aynıdır.
--requirements-only	--deltas-only için kullanımdan kaldırılmış takma ad. stderr'e uyarı verir.
--diff	Değişiklik: gereksinim başına delta farklarını ekler. Spec'ler için bir uyarıyla yok sayılır.
--requirements	JSON, spec: gereksinim metnini korur, scenarios dizilerini boşaltır.
--no-scenarios	JSON, spec: --requirements ile aynı çıktı.
-r, --requirement <id>	JSON, spec: 1 tabanlı konuma göre tek bir gereksinim çıkarır. --requirements ile birlikte kullanılamaz.
--store <id>	Geçerli proje yerine OpenSpec kökü olarak kayıtlı bir store kullanır.

Çözümlenen türe uygulanmayan bayraklar, stderr üzerinde bir uyarı verilerek yok sayılır.

Çıktı

Metin modu ham bir aktarımdır: bir değişiklik proposal.md, bir spec spec.md dosyasını yazdırır.

# Add rate limiting

Why

Unauthenticated clients can exhaust the API.

What Changes

• Add per-client rate limiting to the public API.

Bir değişiklik için `--diff` önce öneriyi yazdırır, ardından bir `Specifications Changed (diffs)` bölümü gösterir. ADDED gereksinimleri tam metinleriyle birlikte gösterilir. REMOVED gereksinimleri, yazılmış Reason ve Migration bölümlerini korur. RENAMED gereksinimleri FROM ve TO bilgilerini gösterir. MODIFIED gereksinimleri, eşleşen ana gereksinime göre bir unified diff gösterir.

Bir MODIFIED başlığı yalnızca büyük/küçük harf veya boşluk esnetildikten sonra eşleşiyorsa, çıktı hem diff'i hem de arşiv eşleşmesinin birebir olduğu yönünde bir uyarı içerir. Ana spesifikasyon veya gereksinim eksikse, çıktı uyarı verir ve tam delta bloğunu yazdırır. Metinsel farkı olmayan bir MODIFIED bloğu `(no textual changes)` yazdırır.

`--json` ile bir değişiklik delta biçiminde verilir:

```json
{
  "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"
  }
}

Her gereksinim, Requirement: başlığından sonra gelen başlık metni olan name alanını taşır. Archive, MODIFIED, REMOVED ve RENAMED girdilerini bu isimle eşleştirir. Her senaryo, Scenario: başlığından sonra gelen başlık metni olan name alanını taşır. Her iki başlıkta yer alan sondaki # dizisi ismin bir parçası değildir.

--json --diff bu üst düzey yapıyı korur. MODIFIED bir delta, bir diff dizisi, bir warning dizisi veya her ikisini de kazanır. Diğer işlemler değişmez. Boş bir diff dizisi, ana blok ile delta bloğunun metinsel olarak özdeş olduğu anlamına gelir.

--json ile bir spesifikasyon, gereksinimlerini senaryolarıyla birlikte listeler. Gereksinimler ve senaryolar, değişiklik JSON'undakiyle aynı name alanlarını taşır:

{
  "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"
  }
}

Bilinmeyen bir isim için yakın eşleşmeler önerilir: Unknown item 'does-not-exist'. Did you mean: add-rate-limit, api?. Hem bir değişiklikle hem de bir spesifikasyonla eşleşen bir isim hata verir ve --type belirtilmesini ister.

Çıkış kodları

• 0: öğe yazdırıldı.
• 1: bilinmeyen veya belirsiz isim, terminal dışında isim verilmemesi, aralık dışı bir -r indeksi, --requirements ile -r birlikte kullanılması ya da --diff için bir delta veya ana spesifikasyonun okunamaması.

openspec view

Spesifikasyonların ve değişikliklerin tek ekranlık bir panelini yazdırır.

openspec view   # tek ekranda proje özeti

view, paneli bir kez yazdırır ve çıkar. Hiçbir tuş girişi okumaz. Değişiklikler görev ilerlemesine göre gruplanır: Draft (henüz görev yok), Active (görevler sürüyor; ilerleme çubuğu ve yüzde ile), Completed (tüm görevler işaretlenmiş). Spesifikasyonlar, gereksinim sayılarıyla listelenir; en çok gereksinimi olan başta gelir.

Seçenekler

Bayrak	Etki
--store <id>	Mevcut proje yerine kayıtlı bir store'u OpenSpec kökü olarak kullanır.

Çıktı

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

Görevleri devam eden bir değişiklik olduğunda bir Task Progress özet satırı görünür.

Her aktif değişiklik ayrıca görev ilerleme çubuğunun altında kendi şemasını ve artifact durumlarını gösterir:

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

İşaret	Artifact durumu
✓	Çıktısı mevcuttur. Var olan bir tasks artifact'ı, kontrol listesi bitmemiş olsa bile tamamlanmış sayılır.
→	Oluşturulmaya hazırdır.
İşaret yok	Eksik bir bağımlılık nedeniyle engellenmiştir.
(skipped)	Değişiklik bunu atlar.

Bir iş akışı yüklenemezse, view bir uyarı yazdırır ve o değişikliğin görev ilerlemesini görünür tutar. İş akışını ayrıca incelemek için openspec status --change <name> komutunu çalıştırın. openspec view --store <id> komutundan sonra, status'a aynı --store <id> değerini geçirin.

Çıkış kodları

• 0: panel yazdırıldı.
• 1: OpenSpec kökü bulunamadı (proje dışında, --store yok).

openspec validate

Değişiklikleri ve spesifikasyonları yapısal sorunlar açısından denetler.

openspec validate add-rate-limit   # ada göre tek bir değişiklik veya spesifikasyon
openspec validate --all            # tüm değişiklikler ve spesifikasyonlar

Ne isim ne de toplu bayrak verildiğinde, validate öğe seçmenizi ister. Etkileşimli bir terminalin dışında 1 koduyla çıkar ve bunun yerine toplu bayrakları yazdırır.

Argümanlar

Argüman	Açıklama
item-name	Doğrulanacak değişiklik veya spesifikasyon; klasör adına göre (add-rate-limit, api).

Seçenekler

Bayrak	Etki
--all	Tüm değişiklikleri ve spesifikasyonları doğrular.
--changes	Tüm değişiklikleri doğrular.
--specs	Tüm spesifikasyonları doğrular.
--archived	Arşivlenmiş değişikliklerde görev tamamlanmasını denetler; uygulanmış spesifikasyon deltalaraını doğrulamaz.
--strict	Uyarıları başarısızlık sayar.
--type <change|spec>	Bir değişiklik ile bir spesifikasyon aynı ismi paylaştığında türü seçer.
--json	Metin yerine yapılandırılmış bir rapor yazdırır.
--report <mode>	Toplu çıktı: full (varsayılan) veya findings. Açık bir toplu kapsam gerektirir.
--concurrency <n>	Toplu çalıştırmalarda eşzamanlı doğrulama üst sınırı. Varsayılan: OPENSPEC_CONCURRENCY, aksi halde 6.
--no-interactive	Asla soru sormaz: eksik veya belirsiz isim hata olur.
--store <id>	Mevcut proje yerine kayıtlı bir store'u OpenSpec kökü olarak kullanır.

Çıktı

Toplu çalıştırmalar her öğe için bir durum satırı yazdırır, ardından varsa bulguları gösterir ve toplamlarla biter:

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

Görev onay kutusu bulguları

İlerleme yalnızca onay kutularını sayar, başka hiçbir şeyi saymaz; bu yüzden düz madde işaretleriyle yazılmış bir görev dosyası sıfır görev gibi okunur: openspec list ve openspec status iş bildirmez, openspec archive ise eksik olarak işaretlenecek bir şey bulamaz. Validate, onay kutusu olmadan iş listeleyen her izlenen görev dosyası için bir WARNING bildirir:

⚠ [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".

Uyarı yalnızca değişikliğin izlenen kümesinin tamamında hiç onay kutusu bulunmadığında tetiklenir. Gerçek bir kontrol listesinin yanındaki tek bir düzyazı dosyası bildirilmez; yazım aşamasındaki bir değişiklik de tek bir onay kutusu oluşur oluşmaz ilerleme gösterir. --strict uyarıyı bir başarısızlığa dönüştürür. Satır numarası --json raporunda yer alır.

Fenced bloklar, HTML yorumları, YAML front matter ve girintili kod taranmaz; böylece yapıştırılmış bir terminal örneği asla görev listesi sanılmaz.

Arşiv birleştirme bulguları

Değişiklikler için validate, mevcut ana spesifikasyonlara karşı dosya yazmadan archive'ın birleştirme oluşturucusunu çalıştırır. Eksik bir MODIFIED hedefi veya çakışan bir ADDED gereksinimi gibi birleştirme çakışmalarını INFO olarak bildirir:

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

Bu bulgular, doğrulama geçse bile hem metin hem de JSON çıktısında görünür. INFO, --strict altında dahi çıkış kodunu asla değiştirmez: eksik bir hedef, henüz arşivlenmemiş kardeş bir değişikliğe ait olabilir. Ana spesifikasyonlara zaten senkronize edilmiş deltalara, archive'ın mevcut birleştirme kuralları uygulanır.

Bu denetim, archive'ın sonraki birleştirilmiş spesifikasyon doğrulamasını veya retirement denetimlerini çalıştırmaz. Temiz bir rapor, archive işleminin başarılı olacağını garanti etmez.

Birleştirme ön denetimi (preflight) başlatılamazsa, bir INFO bulgusu nedenini açıklar. Mevcut doğrulama bulguları ve çıkış kodu değişmeden kalır.

Başarısız olan bir öğe her sorunu ve çözümünü listeler:

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 çalıştırma için tek bir rapor yazdırır:

{
  "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"
  }
}

issues girdileri ERROR, WARNING veya INFO değerinde bir level taşır.

Çıkış kodları

• 0: doğrulanan tüm öğeler başarılı oldu; boş bir toplu kapsam dâhil.
• 1: bir öğe başarısız oldu, rapor isteği geçersiz, openspec/config.yaml okunamıyor veya geçerli bir YAML değil ya da çalıştırma başarısız oldu (örneğin bilinmeyen bir isim veya OpenSpec kökü yokluğu). Okunamayan veya ayrıştırılamayan bir yapılandırma, hiçbir öğe denetlenmeden çalıştırmayı durdurur; --json ile bu, unreadable_config veya unparseable_config koduna sahip tek bir status girdisi olarak bildirilir.

--report full|findings

Açık bir toplu doğrulama kapsamı için çıktıyı seçer:

• full: tüm öğeler. Varsayılan budur. Açıkça verilmiş --report full, rapor meta verisi eklemeden mevcut çıktı biçimini korur.
• findings: yalnızca sorunu olan öğeler; uyarı veya bilgi taşıyan başarılı öğeler dâhil. Yine de her öğe doğrulanır. Toplamlar, strict mod davranışı ve çıkış kodları değişmez.

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

Kapsamlar

Bayraklar	Findings report.scope
--all	all
--changes	changes
--specs	specs
--changes --specs, ya da bu bayraklardan herhangi biriyle --all	all
--archived	archived

Her iki açık rapor modu da konumsal bir öğe adını, eksik bir toplu kapsamı ya da arşiv ve aktif kapsamların bir arada kullanılmasını reddeder.

Findings metin çıktısı

İnsan çıktısı: stdout, Scope: <scope> (<count> items) yazar, ardından toplamları gösterir. Sorun taşıyan öğe yoksa:

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

Sorun taşıyan öğe etiketleri, önem düzeyi etiketleri, yollar ve mesajlar stderr'e yazdırılır. Aktif kapsam başarısızlıkları, toplamlardan sonraki Details: yeniden çalıştırma ipucunu korur. Mevcut kök banner'ı ve ilerleme çıktısı rapordan önce gelebilir.

Findings JSON çıktısı

--report findings --json tek bir belge yazdırır. Bu örnekte iki sorunsuz öğe vardır:

{
  "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 ve report.version: validation-findings yapısını ve 1.0 sürümünü tanımlar. Üst düzeyde version veya items bulunmaz.
• report.returnedItems ve report.totalItems: sırasıyla döndürülen kayıtların ve doğrulanan tüm öğelerin sayısını belirtir.
• itemFindings: issues dizisi boş olmayan, eksiksiz öğe kayıtları. ERROR, WARNING ve INFO sorunlarını içerir. Her kayıt id, type, valid, issues ve durationMs alanlarını korur. Arşivlenmiş öğeler type: "change" kullanır.
• summary: tüm çalıştırmanın toplamları ve türe göre sayıları; döndürülen alt kümenin sayıları değil. Boş bir kapsam sıfır toplamla sonuçlanır ve 0 ile çıkar.
• root: tam rapordakiyle aynı seçili kök meta verisi.

Kayıt korunumu: Döndürülen öğeler tam rapordaki sıralarını ve öğe ya da sorunlardaki ek (additive) alanlarını korur. Filtreleme, isteğe bağlı line ve column alanları dâhil olmak üzere mesajları veya konumları yeniden yazmaz.

Komut başarısızlıkları: Kök seçimi veya öğe keşfi başarısızlıkları mevcut status tanılamasını korur ve 1 ile çıkar. Tamamlanmış bir findings raporu ya da başarılı sayılan boş bir rapor döndürmezler.

Geçersiz rapor istekleri

Her iki açık rapor modu da şu istekleri kök seçiminden veya öğe keşfinden önce reddeder:

• Desteklenmeyen bir rapor değeri; boş dize dâhil.
• Toplu bayrak bulunsa bile konumsal bir öğe adı.
• Açık bir toplu kapsam verilmemesi.
• --archived ile --all, --changes veya --specs birlikte kullanımı.

JSON modunda reddedilen bir istek, yalnızca tek öğeli bir status dizisiyle 1 koduyla çıkar. Belgede root veya rapor yükü bulunmaz:

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."
    }
  ]
}

İnsan modu hatayı stderr'e yazdırır. Değer verilmeyen çıplak bir --report, --json kullanılsa dahi stderr'de bir Commander sözdizimi hatasıdır; bu tanı zarfını kullanmaz.

Tam raporu harici olarak filtreleme

Özel bir JSON görünümü için tam raporu jq veya PowerShell ile filtreleyin. Bu betik örnekleri doğrulama çıkış kodunu korur ve komut hata belgelerine dokunmaz.

jq ile Bash'te:

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"

PowerShell'de:

$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

Bu özel görünümler tam raporun anahtarlarını korur ancak sorunsuz öğeleri çıkarır. Ne eksiksiz bir full-v1 raporu ne de sürümlendirilmiş --report findings yapısıdırlar.

openspec archive

Tamamlanmış bir değişikliği arşive taşır ve ana spesifikasyonları günceller.

openspec archive add-rate-limit -y                # tek bir değişikliği arşivler, deltalarını birleştirir
openspec archive add-rate-limit -y --skip-specs   # spesifikasyonlara dokunmadan arşivler

İsim verilmediğinde, archive sizden bir değişiklik seçmenizi ister. Etkileşimli bir terminal dışında çalıştırıldığında 1 çıkış koduyla sonlanır ve bunun yerine yeniden çalıştırma komutunu yazdırır.

Argümanlar

Argüman	Açıklama
change-name	Arşivlenecek değişiklik, klasör adına göre (add-rate-limit).

Seçenekler

Bayrak	Etki
-y, --yes	Tüm onaylara evet yanıtı verir: spesifikasyon güncellemeleri, tamamlanmamış görevler, atlanan doğrulama.
--skip-specs	Ana spesifikasyonlara dokunmadan arşivler (altyapı, araç ya da yalnızca dokümantasyon değişiklikleri).
--no-validate	Doğrulamayı atlar. Archive önce onayınızı ister; -y bunu sizin adınıza yanıtlar.
--json	Metin yerine yapılandırılmış bir sonuç yazdırır. Spesifikasyon güncellemelerini onaylamak için --yes gerekir.
--store <id>	Geçerli proje yerine kayıtlı bir store'u OpenSpec kökü olarak kullanır.

Çıktı

Başarılı bir çalıştırma görev durumunu raporlar, spesifikasyon güncellemelerinin önizlemesini gösterir, bunları uygular ve arşiv klasörünün adını belirtir:

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'.

Değişiklik klasörü, adının önüne bugünün tarihi eklenerek bütün halinde openspec/changes/archive/2026-08-11-add-rate-limit/ dizinine taşınır. Her delta kendi ana spesifikasyonuyla birleştirilir: yukarıdaki ADDED gereksinimi openspec/specs/api/spec.md dosyasına eklendi. -y kullanılmadığında, archive güncellemeden önce önizlemeyi gösterir ve onay sorar. Reddetmeniz durumunda değişiklik yine de arşivlenir ancak spesifikasyonlara dokunulmaz.

--json --yes ile:

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

Archive önce değişikliği doğrular ve başarısız olanı reddeder:

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.

Tamamlanmamış görevler uyarı verir ancak engellemez. Etkileşimli modda archive devam edilip edilmeyeceğini sorar; -y ise kendi başına devam eder:

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

Çıkış kodları

• 0: Değişiklik, spesifikasyon güncellemeleri olsun ya da olmasın, arşivlendi.
• 1: Doğrulama başarısız oldu, değişiklik adı bilinmiyor ya da bir onay gerekti ancak hiçbir yanıt okunamadı.

openspec new

Yeni bir değişiklik dizini oluşturur.

openspec new change add-caching                                # yalnızca meta veri
openspec new change add-search --goal "Users can search docs"  # bir hedef kaydeder

new komutunun tek bir alt komutu vardır: new change <name>. İçinde tek bir .openspec.yaml meta veri dosyası bulunan openspec/changes/<name>/ dizinini oluşturur:

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

Artefaktlar (öneri, spesifikasyonlar, tasarım, görevler) burada iskelet olarak oluşturulmaz. Bunları daha sonra siz yazarsınız ve openspec status hangisinin sıra olduğunu söyler.

Argümanlar

Argüman	Açıklama
name	Değişiklik için klasör adı (add-caching).

Seçenekler

Bayrak	Etki
--description <text>	Değişiklik dizininde bu metinle bir README.md de oluşturur.
--goal <text>	.openspec.yaml içine bir goal: satırı kaydeder.
--schema <name>	Değişiklik için iş akışı şeması. Varsayılan: spec-driven, paketle gelen tek şema.
--json	Oluşturulan değişikliği metin yerine JSON olarak yazdırır.
--store <id>	Geçerli proje yerine kayıtlı bir store'u OpenSpec kökü olarak kullanır.

Çıktı

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

openspec/ dizini bulunamadığında, new change bulunduğunuz konumda bir tane oluşturur ve bunu size bildirir:

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.

Bu bildirim, diğer insan okunabilir çıktının yanında stdout'a yazılır ve --json kullanıldığında asla görünmez.

--json ile, openspec/ dizinine halihazırda sahip bir projede:

{
  "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"
  }
}

openspec/ dizini bulunamadığında ve new change tarafından bir tane oluşturulduğunda, JSON aynı yapıya sahip olur. root.path komutu çalıştırdığınız dizini gösterir ve root.source değeri implicit olarak görünür:

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

Çıkış kodları

• 0: Değişiklik oluşturuldu.
• 1: Değişiklik zaten mevcut ya da şema bilinmiyor.

openspec status

Bir değişiklik veya her etkin değişiklik için artefakt tamamlama durumunu raporlar.

openspec status --change add-rate-limit          # checklist view
openspec status --change add-rate-limit --json   # structured report
openspec status --all                            # every active change
openspec status --all --json                     # one batch report

Etkin değişiklikler varsa, --change veya --all flag'lerinden tam olarak birini kullanın. Hiçbiri kullanılmazsa, status 1 çıkarak mevcut değişiklikleri listeler, sadece bir tane olsa bile:

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

Proje etkin değişiklik yoksa, status No active changes. Create one with: openspec new change <name> yazdırır ve herhangi bir flag kullanılmadan da 0 çıkar. --all --json ile aynı boş durum { "changes": [], "message": "No active changes.", "root": ... } olarak gösterilir.

Seçenekler

Flag	Effect
--change <id>	Raporlanacak değişiklik, klasör adı ile belirtilir.
--all	Her etkin değişikliği isme göre sıralı raporlar. --change ile birleştirilemez.
--schema <name>	openspec/config.yaml dosyasından otomatik algılanan şemayı geçersiz kılar. Bilinmeyen bir şema adı hatadır.
--json	Metin yerine yapılandırılmış bir rapor yazdırır.
--store <id>	Geçerli proje yerine kayıtlı bir mağazayı OpenSpec kökü olarak kullanır.

Çıkış

Şema artefaktlarının bir kontrol listesi: [x] tamamlandı, [ ] yazma bekliyor, [-] bağımlı olduğu artefaktlar varsa engellendi.

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

Next: satırı, değişikliği ileri taşıyan bir komutu belirtir, bu yüzden openspec status bir oturumu yeniden başlatırken bir değişikliği seçmek için yeterlidir. Planlama tamamlanmadığında bir sonraki hazır artefaktın adını verir, ve tüm planlama artefaktları varsa openspec instructions apply komutunu belirtir:

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

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

Çözülen kök bir mağazaysa --store <id> taşır ve JSON nextSteps cümleleriyle aynı komutu adlandırır.

--json her artefakt için bağımlılıklar, çözülmüş dosya yolları ve önerilen bir sonraki adım ekler. Kısaltıldı:

{
  "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"
      ]
    }
  ]
}

--all --json ile changes, her bir değişiklik için aynı durum nesnesini içerir, her değişiklik için bir root olmadan. Seçilen kök zarfın bir kez gösterilir. Bu yukarıda gösterilen her değişiklik için alanları kısaltır:

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

Bir değişiklik yüklenemezse, toplu raporlama devam eder. Bu değişiklik için girişte changeName ve bir status tanısı bulunur, diğer girişler ise available olmaya devam eder. Komut 1 çıkar, JSON modunda da dahil, thus CI eksik bir raporu successful olarak kabul etmez. JSON çıktısı hala parse edilebilir bir belgedir.

Çıkış kodları

• 0: her istenen durum yazdırılır; boş bir --all raporu da 0 çıkar.
• 1: istenen bir değişiklik yüklenemedi, --change veya --all eksik, iki flag birleştirildi, değişiklik yok ya da şema geçersiz.

openspec instructions

Bir artefakt oluşturmak, uygulamak veya arşivlemek için talimatlar yazdırır. Aracınız bu komutu, sonraki adımdaki talimat metnini almak için iş akışı sırasında çalıştırır.

openspec instructions proposal --change add-rate-limit   # how to write one artifact
openspec instructions apply --change add-rate-limit      # how to implement the change
openspec instructions archive --change add-rate-limit    # inputs for archiving

Argümanlar

Argüman	Ne olduğu
artifact	Şemadan (spec-driven içinde proposal, specs, design, tasks) bir artefakt kimliği, veya rezerve kelimeler apply ve archive.

Seçenekler

Flag	Effect
--change <id>	Hangi değişiklik için talimat oluşturulacağı. Gerekli.
--schema <name>	Şemayı geçersiz kılar. Aksi halde config.yaml dosyasından otomatik algılanır.
--json	Metin yerine yapılandırılmış bir nesne yazdırır.
--store <id>	Geçerli proje yerine kayıtlı bir mağazayı OpenSpec kökü olarak kullanır.

Çıkış

Artefakt formu bir talimat bloku yazdırır: görev, yazılacak dosya, nasıl yazılacağı, artefaktın şablonu ve tamamlandığında ne açılır.

<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 bağlam dosyaları, görev ilerlemesi ve çalışma talimatını yazdırır:

## 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.

Gerekli artefaktlar eksikse, apply ### ⚠️ Blocked mesajı verir ve eksik artefaktların adlarını listeler. archive, değişiklik adını plus proje bağlamı ve operasyon rehberini (config'den) yazdırır. Hiçbiri yapılandırılmamışsa, bunu belirtir ve başka bir şey yazmaz.

--json ile her form bir nesne döndürür. Artefakt formu şu şekilde başlar:

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

ve outputPath, existingOutputPaths, tam instruction ve template dizileri, dependencies, unlocks, ve root ile devam eder. apply formu contextFiles, progress, tasks, taskTrackingConfigured, state (blocked, ready, all_done), ve instruction taşır.

Her bir tasks:girdisi id, description, done, sourcePath, ve line taşır. sourcePath, görevi sağlayan dosyanın mutlak yoludur. line, o dosyada görev kutucuğunun bir tabanlı satır numarasıdır.

taskTrackingConfigured her zaman bir booleans: şema apply.tracks null olmayan bir değer ayarlandığında true, eşleşen dosya yoksa bile, aksi halde false. Eşleşen bir takip dosyası okunamazsa, unavailableTrackingFiles mutlak path'ini ve hata reason'u içerir. Bu alan tüm eşleşen dosyalar okunabilirse atlanır. Okunabilir dosyalar hala tasks ve progress'e katkı sağlar, ancak tüm eşleşen dosyalar okunana kadar state all_done olamaz.

Çıkış kodları

• 0: talimatlar yazdırıldı.
• 1: bilinmeyen artefakt, bilinmeyen değişiklik, bilinmeyen şema, veya --change eksik. Her hata geçerli değerleri listeler.

openspec templates

Bir şemanın yapıtları için çözümlenmiş şablon yollarını yazdırır.

openspec templates          # varsayılan şema: spec-driven
openspec templates --json   # yapıt kimliklerinin yollara eşlemesi

Seçenekler

Bayrak	Etki
--schema <name>	Çözümlenecek şema. Varsayılan: spec-driven.
--json	Yapıt kimliklerini şablon yollarına eşleyen bir JSON haritası yazdırır.

Çıktı

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 adları, şemanın çözümlendiği yerlerdir: project (projenizdeki openspec/schemas/), user (genel bir geçersiz kılma) veya package (CLI'ye gömülü). Proje, kullanıcıya göre; kullanıcı, pakete göre önceliklidir.

{
  "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"
  }
}

Çıkış kodları

• 0: yollar yazdırıldı.
• 1: bilinmeyen şema. Hata, mevcut şemaları listeler.

openspec schemas

Mevcut iş akışı şemalarını listeler.

openspec schemas          # adlar, açıklamalar, yapıt sırası
openspec schemas --json   # makine tarafından okunabilir, ajan kullanımı için

Seçenekler

Bayrak	Etki
--json	JSON olarak çıktı verir (ajan kullanımı için).

Çıktı

Available schemas:

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

Projenizdeki şemalar (project) olarak, genel geçersiz kılmalar ise (user override) olarak etiketlenir.

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

Çıkış kodları

• 0: şemalar listelendi.
• 1: şema listesi okunamadı.

openspec şeması

Bir şemayı inceler, çatallar veya oluşturur (deneysel). Her alt komut önce stderr'e Note: Schema commands are experimental and may change. yazdırır.

openspec schema which spec-driven          # bir şemanın nereden çözümlendiğini gösterir
openspec schema fork spec-driven my-flow   # bir şemayı projeye kopyalar
openspec schema init my-schema             # sıfırdan bir şema oluşturur

Alt Komut	Ne yapar
which	Bir şemanın nereden çözümlendiğini gösterir.
validate	Bir şemanın yapısını ve şablonlarını denetler.
fork	Mevcut bir şemayı özelleştirmek için projeye kopyalar.
init	Proje yerelinde yeni bir şema oluşturur.

Şemalar üç konumdan çözümlenir. İlk eşleşme kazanır:

Kaynak	Konum
project	Geçerli projedeki openspec/schemas/ dizini.
user	~/.local/share/openspec/schemas/ (XDG_DATA_HOME ve Windows %LOCALAPPDATA% dikkate alınır).
package	CLI ile birlikte gelen şemalar. spec-driven burada bulunur.

openspec schema which

CLI'nin hangi şema kopyasını kullanacağını gösterir.

openspec schema which spec-driven
openspec schema which --all        # kaynağa göre gruplanmış tüm şemalar

Bağımsız Değişkenler

Bağımsız Değişken	Ne olduğu
name	Aranacak şema. --all ayarlanmadıkça zorunludur. İkisi de yoksa which 1 ile çıkar.

Seçenekler

Bayrak	Etkisi
--all	Her şemayı çözümleme kaynağıyla birlikte listeler.
--json	Çözümlemeyi JSON olarak yazdırır.

Çıktı

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

Daha yüksek öncelikli bir kopya başka birini gizlediğinde, Shadows: bölümü gizlenen kopyaları listeler. --json ile:

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

Bilinmeyen bir ad 1 ile çıkar ve mevcut şemaları listeler.

openspec schema validate

Bir şemanın yapısını ve şablonlarını denetler.

openspec schema validate spec-driven   # herhangi bir kaynaktan tek şema
openspec schema validate               # proje yerelindeki her şema

schema.yaml dosyasının var olduğunu ve ayrıştırılabildiğini, yapının şema biçimiyle eşleştiğini, her yapının şablon dosyasının şemanın templates/ dizini içinde bulunduğunu ve bağımlılık grafiğinde döngü veya bilinmeyen referans olmadığını ( apply.requires dahil) doğrular. Bir apply.tracks değeri, herhangi bir yapının generates değerine tam olarak eşit değilse bir warning: satırı yazdırır ancak doğrulamayı başarısız kılmaz; çünkü OpenSpec bu durumda o dosyanın hangi yapının ilerlemesine ait olduğunu söyleyemez.

Seçenekler

Bayrak	Etkisi
--json	Metin yerine yapılandırılmış bir rapor yazdırır.
--verbose	Her doğrulama adımını yazdırır.

Çıktı

✓ Schema 'spec-driven' is valid

Ad verilmediğinde, her proje şeması Validation Results: başlığı altında bir satır alır. Başarısız bir şema sorunlarını listeler ve çalışma 1 ile çıkar:

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

openspec schema fork

Mevcut bir şemayı özelleştirebilmeniz için projeye kopyalar.

openspec schema fork spec-driven my-flow

Bağımsız Değişkenler

Bağımsız Değişken	Ne olduğu
source	Herhangi bir kaynak konumdan kopyalanacak şema.
name	Kopyanın adı. Kebab-case (my-workflow). Varsayılan: <source>-custom.

Seçenekler

Bayrak	Etkisi
--force	Mevcut bir hedef şemanın üzerine yazar.
--json	Sonucu JSON olarak yazdırır.

Çıktı

✔ 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

Çatal openspec/schemas/ dizinine yerleşir ve schema.yaml içindeki name: alanı yeni ada göre yeniden yazılır:

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

Mevcut bir hedef, --force iletmediğiniz sürece bir hatadır. Kaynağın adını koruyan bir çatal, orijinali gölgeler.

openspec schema init

Başlangıç şablonlarıyla yeni bir proje yereli şeması oluşturur.

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

Etkileşimli bir terminalde --description ve --artifacts verilmediğinde, init bir açıklama, bir yapıt kontrol listesi ve şemanın proje varsayılanı yapılıp yapılmayacağını sorar. Terminal dışında aşağıdaki varsayılanları kullanır.

Bağımsız Değişkenler

Bağımsız Değişken	Ne olduğu
name	Yeni şemanın adı. Kebab-case (my-workflow).

Seçenekler

Bayrak	Etkisi
--description <text>	Şema açıklaması. Varsayılan: Custom workflow schema for <name>.
--artifacts <list>	proposal, specs, design, tasks arasından virgülle ayrılmış yapıt kimlikleri. Varsayılan: dördü de.
--default	Mevcut openspec/config.yaml veya openspec/config.yml dosyasına schema: <name> yazar. İkisi de yoksa openspec/config.yaml oluşturur. Yeni değişiklikler bu şemayı kullanır.
--no-default	Varsayılan hakkındaki soruyu atlar.
--force	Aynı ada sahip mevcut bir şemanın üzerine yazar.
--json	Sonucu JSON olarak yazdırır.

Şema oluşturma ve --default yapılandırma güncellemesi tek bir işlemdir. OpenSpec yapılandırmayı doğrulayamaz veya yazamazsa, hem yapılandırmayı hem de mevcut şemayı değiştirmeden bırakır.

Çıktı

✔ Created schema 'my-schema'

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

Artifacts: proposal, tasks

Disk üzerindeki düzen:

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

schema.yaml, seçilen yapıtları bağımlılıklarıyla birbirine bağlar. tasks dahil edildiğinde, tasks.md dosyasını izleyen bir apply aşaması da alır. Şemayı openspec new --schema my-schema ile kullanın.

openspec store

Mağazaları oluşturur ve yönetir: makinenize kayıtlı bağımsız OpenSpec depoları.

openspec store setup team-context --path ~/openspec/team-context   # oluşturur ve kaydeder
openspec store register ~/stores/design-system                     # mevcut bir kopyayı kaydeder
openspec store list                                                # kayıtlı olanları görür

Kayıtlar makine başına bir kayıt defterinde tutulur: ~/.local/share/openspec/stores/registry.yaml veya XDG_DATA_HOME ayarlandığında $XDG_DATA_HOME/openspec/stores/registry.yaml. Her alt komut, metin yerine yapılandırılmış bir rapor yazdırmak için --json alır. Eksik veya bilinmeyen bir alt komutla openspec store çalıştırmak 1 ile çıkar ve alt komutları listeler.

Alt Komut	Ne yapar
setup [id]	Bir mağaza klasörü oluşturur ve kaydeder.
register [path]	Mevcut bir mağaza klasörünü kaydeder.
unregister <id>	Kaydı unutur. Klasör diskte kalır.
remove <id>	Kaydı unutur ve klasörü siler.
list (takma ad ls)	Kayıtlı mağazaları listeler.
doctor [id]	Kayıtlı mağazalar için kayıt, meta veri ve Git durumunu denetler.

openspec store setup

Bir mağaza klasörü oluşturur ve kaydeder.

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

Etkileşimli bir terminalde setup, eksik ad ve konum için sorar ve herhangi bir şey oluşturmadan önce onaylar. Terminal dışında, eksik bir ad veya --path 1 ile çıkar ve iletilecek bayrağı gösterir. Kayıtlı bir mağaza için setup'ı yeniden çalıştırmak Registry: already registered bildirir.

--path başka bir Git deposunun içindeyse setup, store_setup_inside_git_repo ile 1 çıkar; çünkü mağazayı orada başlatmak bir depoyu diğerinin içine yerleştirir. --no-init-git hiçbir depo oluşturmaz, bu yüzden bu kontrolü atlar. Ev dizininiz kendisi bir Git deposuysa (örneğin bir dotfiles deposu), bir mağazayı ~/openspec/<id> konumunda tutmak için bunu kullanın.

Bağımsız Değişkenler

Bağımsız Değişken	Ne olduğu
id	Mağaza adı. --store seçeneğine ileteceğiniz kimlik olur.

Seçenekler

Bayrak	Etkisi
--path <path>	Mağazanın yaşayacağı klasör (~ genişletilir).
--init-git	İlk commit ile bir Git deposu başlatır. Varsayılan.
--no-init-git	Tüm Git işlemlerini atlar: init yok, ilk commit yok.
--remote <url>	store.yaml içinde kaydedilen resmi klon kaynağı.

Çıktı

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, neyin oluşturulduğunu ve nereye kaydedildiğini bildirir:

{
  "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

Mevcut bir mağaza klasörünü kaydeder, örneğin klonladığınız bir ekip arkadaşının mağazasını.

openspec store register ~/stores/design-system

Klasör sağlıklı bir openspec/ kökü içermelidir. .openspec-store/store.yaml mevcutsa, register kayıtlı kimliği yeniden kullanır. Yoksa, register bu meta veriyi oluşturmadan önce sorar. Etkileşimli bir terminal dışında, bunun yerine --yes iletin. Bir makine, mağaza kimliği başına tek bir kopya kaydedebilir. Aynı kimlik altında ikinci bir yol veya ikinci bir kimlik altında aynı yol 1 ile çıkar.

Bağımsız Değişkenler

Bağımsız Değişken	Ne olduğu
path	Kaydedilecek mağaza klasörü (~ genişletilir). Zorunlu.

Seçenekler

Bayrak	Etkisi
--id <id>	Mağaza kimliği. Varsayılan olarak meta veri veya klasör adı.
--yes	Sağlıklı bir OpenSpec kökü için mağaza kimliği meta verisini oluşturmayı onaylar.

Çıktı

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

--json, store setup --json ile aynı belge yapısını yazdırır.

openspec store unregister

Kaydı unutur. Klasör diskte kalır.

openspec store unregister design-system

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

openspec store remove

Kaydı unutur ve klasörü siler.

openspec store remove design-system --yes

Etkileşimli olarak remove, silmeden önce sorar. --json ile veya etkileşimli bir terminal dışında, silme --yes gerektirir:

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

Klasör eşleşen mağaza meta verisinden yoksun olduğunda veya başka bir kayıtlı mağaza içerdiğinde (örneğin bir Git alt modülü olarak satılan bir mağaza) remove 1 ile çıkar ve hiçbir şey silmez. Bu durumda hata store_remove_contains_registered_store olur: önce openspec store unregister <nested-id> çalıştırın veya dosyaları silmeden mağazayı unutmak için openspec store unregister <id> çalıştırın.

Seçenekler

Bayrak	Etkisi
--yes	Yerel mağaza klasörü silmeyi onaylar.

Çıktı

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

openspec store list

Kayıtlı mağazaları listeler. ls bir takma addır.

openspec store list

OpenSpec stores (2)

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

Hiçbir şey kayıtlı değilken, list No stores registered. yazdırır ve sırada çalıştırılacak setup ve register komutlarını gösterir.

openspec store doctor

Kayıtlı mağazalar için kayıt, meta veri ve Git durumunu denetler.

openspec store doctor                # kayıtlı her mağaza
openspec store doctor team-context  # tek mağaza

Çıktı

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

Çıkış kodları

• 0: rapor yazdırıldı, bir mağaza sorun bildirse bile.
• 1: rapor çalıştırılamadı (örneğin bilinmeyen bir mağaza kimliği).

openspec doctor

Çözümlenen OpenSpec kökü için ilişki sağlığını raporlar.

openspec doctor                       # nearest openspec/ root above your cwd
openspec doctor --store team-context  # a registered store as the root

Doctor salt okunurdur: asla klonlamaz, eşitlemez veya onarmaz. Kökün sağlıklı olup olmadığını ve openspec/config.yaml içinde bildirilen her referansın bu makinede çözümlenip çözümlenmediğini raporlar. Cwd'nizin üzerinde hiçbir kök yoksa ve --store verilmemişse, 1 ile çıkar ve kayıtlı depolarınızı adlandırır.

Seçenekler

Bayrak	Etki
--store <id>	Kayıtlı bir depoyu mevcut proje yerine OpenSpec kökü olarak kullan.
--json	Sağlık raporunu JSON olarak yazdır.

Çıktı

Doctor

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

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

--store ile kök depodur ve rapor bir depo satırı ekler:

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": []
}

Çıkış kodları

• 0: rapor yazdırıldı, sorunları listelediğinde bile.
• 1: kök çözümlenmedi (cwd'nizin üzerinde openspec/ yok ve --store verilmedi) veya bilinmeyen bir --store kimliği.

openspec context

Çözümlenen OpenSpec kökü için çalışma bağlamını yazdırır: kök artı openspec/config.yaml içinde bildirilen her referans depo, her biri bir fetch komutuyla.

openspec context                       # nearest openspec/ root above your cwd
openspec context --store team-context  # a registered store as the root
openspec context --json                # agent brief

Bu makinede çözümlenemeyen referanslar, her biri bir düzeltme ile birlikte Not available on this machine bölümüne düşer.

Seçenekler

Bayrak	Etki
--store <id>	Kayıtlı bir depoyu mevcut proje yerine OpenSpec kökü olarak kullan.
--json	Ajan özetini JSON olarak yazdır.
--code-workspace <path>	Ayrıca set için bir VS Code çalışma alanı dosyası yaz.
--force	Mevcut bir --code-workspace dosyasının üzerine yaz.

Çıktı

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

--store ile depo tüm settir:

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": []
}

Çalışma alanı dosyası yazma

--code-workspace, verdiğiniz yola bir VS Code çalışma alanı dosyası yazar: kök için bir klasör, kullanılabilir her referans depo için bir ref:<id> klasörü. Kullanılamayan referanslar atlanır ve özet satırında adlandırılır: Wrote /Users/you/projects/my-app/openspec.code-workspace (2 folders). Özet stderr'e yazdırılır, bu nedenle --json stdout'u tek bir JSON belgesi olarak kalır. Mevcut bir dosya, --force vermediğiniz sürece 1 ile çıkar.

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

Çıkış kodları

• 0: rapor yazdırıldı.
• 1: kök çözümlenmedi (cwd'nizin üzerinde openspec/ yok ve --store verilmedi) veya --code-workspace yazımı reddedildi.

openspec workset

Kişisel çalışma görünümlerini oluşturur, saklar ve açar. Bir workset, birlikte çalıştığınız klasörlerin kaydedilmiş, adlandırılmış bir listesidir.

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

Alt komut	Ne yapar
create [name]	Seçtiğiniz klasörlerden adlandırılmış bir çalışma görünümü oluşturur ve kaydeder.
list, ls	Kaydedilmiş workset'leri üyeleriyle birlikte gösterir.
open <name>	Kaydedilmiş bir workset'i aracınızda açar (düzenleyici penceresi veya agent oturumu).
remove <name>	Kaydedilmiş bir workset'i siler (üye klasörlere asla dokunulmaz).

Bir workset tamamen yereldir:

• Durumu tek bir klasörde tutulur: ~/.local/share/openspec/worksets/ (ayarlandığında $XDG_DATA_HOME/openspec/worksets/; Windows'ta %LOCALAPPDATA%\openspec\worksets\).
• Üye klasörlere hiçbir şey yazılmaz ve hiçbir şey commit edilmez veya paylaşılmaz.
• O tek klasörü silmek tüm izleri ortadan kaldırır.

openspec workset create

Klasörlerin adlandırılmış bir çalışma görünümünü kaydeder.

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

Etkileşimli bir terminalde create, bayrakların sağlamadığı her şeyi sorar: adı, klasörleri tek tek, bir aracı ve ardından workset'i şimdi açma teklifini. Etkileşimli bir terminalin dışında eksik bir ad veya üye hata verir. Zaten kaydedilmiş bir ad her zaman hatadır. Önce onu kaldırın.

Argümanlar

Argüman	Nedir
name	Workset adı. Kebab-case: küçük harfler, sayılar, tek tireler. Etkileşimli terminal dışında zorunludur.

Seçenekler

Bayrak	Etkisi
--member <member>	Üye klasörü <path> veya <name>=<path> olarak belirtir, tekrarlanabilir. İlki birincildir. Yol var olan bir klasör olmalıdır ve etiket varsayılan olarak klasörün kendi adını alır.
--tool <id>	Bu workset'i açmak için tercih edilen araç. Yerleşik kimlikler: code (VS Code), cursor (Cursor). claude ve codex geçici olarak devre dışıdır.
--json	Kaydedilen workset'i JSON olarak yazdırır.

Çıktı

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

openspec workset list

Kaydedilmiş workset'leri üyeleriyle birlikte, ada göre sıralanmış olarak gösterir.

openspec workset list   # alias: ls

Seçenekler

Bayrak	Etkisi
--json	Workset'leri JSON olarak yazdırır.

Çıktı

Her workset için bir blok: ad, varsa aracı, ardından her üye için bir name path satırı. Hiçbir şey kaydedilmemişse list şunu yazdırır: 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

--json ile:

{
  "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

Kaydedilmiş bir workset'i aracınızda açar. Düzenleyici araçları (code, cursor) oluşturulmuş bir .code-workspace dosyası alır. Bir pencere açılır ve komut geri döner. CLI agent araçları (claude, codex) her üye eklenmiş olarak bu terminali devralırdı. Bu akış yeniden düzenlenirken geçici olarak devre dışı bırakıldılar; bu nedenle workset'ler şimdilik bir IDE'de açılır.

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

Argümanlar

Argüman	Nedir
name	Açılacak workset.

Seçenekler

Bayrak	Etkisi
--tool <id>	Bu seferlik yalnızca bu araçla açar.

--tool belirtilmemişse ve kaydedilmiş bir araç yoksa, open sizden kurulu bir araç seçmenizi ister. Etkileşimli bir terminal dışında bunun yerine 1 koduyla çıkar.

• Artık var olmayan bir üye klasörü uyarıyla atlanır. Birincil eksik olduğunda, mevcut olan sonraki üye bu açma işlemi için birincil olur. Hiçbir üye klasörü yoksa açma başarısız olur.
• --json reddedilir: open terminali araca devreder ve JSON modu yoktur.
• Başlatma başarısız olduğunda hata, manuel yolu belirterek sona erer: workspace dosyasının yolu ve üye listesi.

Çıkış kodları

• Aracı yansıtır: komut, aracın kendi çıkış koduyla çıkar ve bir sinyal 128+n olur (Ctrl-C'den sonra 130).
• 1: bilinmeyen workset, kullanılabilir üye klasörü yok veya kullanılabilir araç yok.

openspec workset remove

Kaydedilmiş bir workset'i ve oluşturulmuş .code-workspace dosyasını siler. Üye klasörlere asla dokunulmaz.

openspec workset remove checkout --yes

Etkileşimli bir terminalde remove, workset'i gösterir ve onaylamanızı ister. --json ile veya bir terminal dışında --yes gerektirir ve bu olmadan 1 koduyla çıkar.

Seçenekler

Bayrak	Etkisi
--yes	Kaldırmayı etkileşimsiz olarak onaylar.
--json	Kaldırmayı JSON olarak yazdırır.

Çıktı

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

openspec version

Çalışan OpenSpec sürümünü ve bu kopyanın nasıl kurulduğunu bildirir.

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

--check olmadan bu komut yereldir ve bir registry ile iletişim kurmaz. Bir OpenSpec projesinin dışında çalışır. Mevcut openspec --version bayrağı en kısa biçim olarak kalır ve yalnızca yalın sürüm numarasını yazdırır.

Seçenekler

Bayrak	Etkisi
--json	Metin yerine sürümlenmiş tek bir JSON belgesi yazdırır.
--check	Daha yeni bir sürüm için yapılandırılmış registry'yi kontrol eder.

Çıktı

Global bir npm kurulumu için:

OpenSpec 1.13.2 (npm, global)

Kurulum kapsamı global, project, npx gibi geçici bir çalıştırıcı için temporary, bir checkout için source veya standalone kurulum için standalone olur. OpenSpec, tanımlayamadığı ayrıntıları tahmin etmek yerine atlar.

--json, bilinmeyen ayrıntıları açık null değerleri olarak korur:

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

--check ile kullanılabilir bir güncelleme, OpenSpec o kurulum için güvenli bir komut tanımlayabildiğinde en son sürümü ve bir komut ekler:

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
  }
}

Güncelleme durumu değerleri:

Durum	Anlamı
available	Registry, çalışan sürümden daha yeni ve güvenli bir sürüm döndürdü.
current	Kontrol tamamlandı ve daha yeni bir sürüm bulunamadı.
disabled	Mevcut bir gizlilik veya güncelleme kontrolü ayarı registry erişimini engelledi. latest değeri null olur.
offline	Registry kullanılamıyordu veya kullanılamaz bir yanıt döndürdü. latest değeri null olur.

Standalone kurulum için güncelleme komutu: openspec install.

DO_NOT_TRACK, telemetriden vazgeçme ayarları, OPENSPEC_NO_UPDATE_CHECK, CI algılama ve reddedilen HTTPS dışı registry geçersiz kılmaları kontrolü devre dışı bırakır. Devre dışı ve çevrimdışı kontroller yine de 0 koduyla çıkar çünkü güncelleme kullanılabilirliği bilgilendirme amaçlıdır. Bu komut OpenSpec'i hiçbir zaman yükseltmez; canSelfUpgrade yalnızca mevcut openspec update yolunun bu kopyayı güvenli şekilde yükseltip yükseltemeyeceğini bildirir.

Çıkış kodları

• 0: yerel rapor yazdırıldı (devre dışı veya çevrimdışı güncelleme kontrolleri dahil).
• 1: komut sözdizimi geçersizdi; örneğin desteklenmeyen --upgrade seçeneği.

openspec install

Bağımsız openspec'i yükler. npm veya Homebrew yüklemesinden çalıştırarak geçiş yapın veya bağımsız yüklemeden yerinde yükseltin.

openspec install          # en yeni sürüm
openspec install 1.15.0   # belirli bir sürüm

Betik, tüm dosyaları ekli olan en yeni sürümü ve makineniz için olan dosyayı seçen yükleme betiğini çalıştırır ve bunu o sürümün SHA256SUMS'ı ile karşılaştırır:

• Paket yöneticisinden: ~/.local/bin'e yükler (Windows: %LOCALAPPDATA%\Programs\openspec) ve eski kopyayı kaldıran komutu yazdırır, örneğin npm uninstall -g @fission-ai/openspec. Kendi başına o kopyayı asla kaldırmaz.
• Bağımsız yüklemeden: çalışan dosyayı bulunduğu yerde, kendi adı altında değiştirir.

Ardından openspec'in artık hangi kopyayı çalıştırdığını söyler, çünkü PATH'inizde daha önce bulunan paket yöneticisi kopyası siz kaldırana kadar çalışmaya devam eder.

Argümanlar

Argüman	Nedir
version	Yüklenecek sürüm, örneğin 1.15.0. İsteğe bağlı; varsayılan olarak en yenisini seçer.

OPENSPEC_INSTALL_DIR ve OPENSPEC_INSTALL_NAME başka bir klasör veya dosya adı seçer.

Çıkış kodları

• 0: yüklendi.
• 1: sürüm bir yayınlanmış sürüm değil veya indirme veya yükleme başarısız oldu. Mevcut kopyanız olduğu gibi bırakılır.

openspec feedback

OpenSpec hakkında geri bildirim gönderir.

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

CLI, mesajınızı gh CLI aracılığıyla Fission-AI/OpenSpec deposunda bir GitHub issue'su olarak kaydeder. Başlık Feedback: <message> olur. Gövde, hata formunun başlıklarını kullanır: mesajınız What happened altında, --body metniniz Details altında ve CLI'nin bunları dolduramaması nedeniyle adımları eklemenizi isteyen bir Minimal steps to reproduce bölümü. Bir altbilgi CLI sürümünü, platformu ve zaman damgasını ekler. Issue feedback etiketini alır. Depo bu etiketi tanımlamıyorsa, CLI etiket olmadan yeniden dener ve bunu söyler.

Argümanlar

Argüman	Nedir
message	Tek satırlık özet. Issue başlığı olur. Gerekli.

Seçenekler

Bayrak	Etki
--body <text>	Issue gövdesine eklenen daha uzun açıklama.

Çıktı

Başarılı olduğunda:

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

gh yüklü olmadığında veya gh ile oturum açılmadığında, hiçbir şey gönderilmez. CLI, biçimlendirilmiş geri bildiriminizi --- FORMATTED FEEDBACK --- işaretleri arasında yazdırır, ardından başlığı, ne oldu (mesajınız ve --body metni), CLI sürümü ve ortamı (platform ve Node sürümü) doldurulmuş olarak hata raporlama formunu açan bir bağlantı verir. Formun geri kalanını tarayıcıda tamamlarsınız. Oturum açılmayan yol To auto-submit in the future: gh auth login ekler.

Çıkış kodları

• 0: issue oluşturuldu veya manuel gönderme yedeği çalıştı (gh yok veya gh oturum açılmadı).
• 1: mesaj verilmedi.
• gh'nin kendi kodu: gh kimlik doğrulama sonrası başarısız oldu (ağ, hız sınırı, issue'lar devre dışı). CLI önce geri bildiriminizi ve manuel gönderme URL'sini yeniden yazdırır.

openspec completion

Shell tamamlamalarını yükler veya oluşturur.

openspec completion install        # shell'inizi algılar, yükler, yapılandırmayı bağlar
openspec completion generate zsh   # betiği stdout'a yazdırır

Desteklenen shell'ler: zsh, bash, fish, powershell. Her alt komut isteğe bağlı bir shell argümanı alır. Atlayın ve CLI shell'inizi ortamdan algılar.

Alt komut	Ne yapar
generate [shell]	Tamamlama betiğini stdout'a yazdırır.
install [shell]	Betiği yazar ve shell başlangıç dosyanızı yapılandırır.
uninstall [shell]	Betiği ve yapılandırma bloğunu kaldırır.

Nix ile yüklendiğinde, tamamlamalar zaten yerindedir: flake paketi Bash, Fish ve Zsh betiklerini standart konumlarda sunar, bu yüzden install gerekli değildir (Installation).

openspec completion generate

Betiği yazdırır ve hiçbir şey yazmaz.

#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

Betiği yazar ve shell yapılandırmanızı düzenler. Yapılandırma düzenlemeleri # OPENSPEC:START ve # OPENSPEC:END işaretleri arasında yer alır. Mevcut bir betik önce yedeklenir (.backup-<timestamp> kopyası).

Shell	Betik konumu	Düzenlenen yapılandırma
zsh	~/.zsh/completions/_openspec	ZDOTDIR mutlak bir yol olduğunda $ZDOTDIR/.zshrc, aksi halde ~/.zshrc
bash	~/.local/share/bash-completion/completions/openspec	~/.bashrc
fish	~/.config/fish/completions/openspec.fish	Yok: fish otomatik yükler.
powershell	Profilinizin yanında OpenSpecCompletion.ps1	$PROFILE

Oh My Zsh yüklüyken, betik bunun yerine $ZSH_CUSTOM/completions/_openspec konumuna yerleşir (varsayılan ~/.oh-my-zsh/custom/completions/_openspec).

Göreli veya ~-önekli bir ZDOTDIR yok sayılır ve bunun yerine ~/.zshrc düzenlenir. Betik zaten güncelken install'u tekrar çalıştırmak, zsh'in okuduğu .zshrc'ye yine de bloğu ekler.

Seçenekler

Bayrak	Etki
--verbose	Ayrıca yüklü yolu, varsa yedek yolunu ve hangi yapılandırma dosyasının düzenlendiğini yazdırır.

Çıktı

✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

openspec completion uninstall

Betiği ve işaretli yapılandırma bloğunu kaldırır. Yapılandırmanıza dokunmadan önce sorar (varsayılan: Hayır).

zsh için, install'ın düzenlediği .zshrc'yi temizler ve ayrıca eski bir yükleme ZDOTDIR altında oraya bir blok bıraktığında ~/.zshrc'yi de temizler. Bir blok kaldırılamazsa, uninstall dosyayı adlandırır ve 1 ile çıkar.

Seçenekler

Bayrak	Etki
-y, --yes	Onay istemlerini atla.

Çıktı

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

Çıkış kodları

• 0: betik oluşturuldu, yüklendi veya kaldırıldı. İptal edilen bir uninstall da 0 ile çıkar.
• 1: shell desteklenmiyor veya algılanamadı, veya bir install veya uninstall adımı başarısız oldu.

openspec change

show, list ve validate'in kullanım dışı isim formu. Her çalıştırma uyarır ve fiil-öncelikli komutlara işaret eder, ardından yine de çalıştırır:

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

Kullanım dışı	Bunun yerine kullanın
openspec change show <name>	openspec show <name>
openspec change list	openspec list
openspec change validate <name>	openspec validate <name> (tüm değişiklikler: openspec validate --changes)

Fiil-öncelikli bölümler flag'leri belgeler.

openspec spec

show, list ve validate'in kullanım dışı isim formu. Her çalıştırma uyarır ve fiil-öncelikli komutlara işaret eder, ardından yine de çalıştırır:

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

Kullanım dışı	Bunun yerine kullanın
openspec spec show <id>	openspec show <id>
openspec spec list	openspec list --specs
openspec spec validate <id>	openspec validate <id> (tüm spec'ler: openspec validate --specs)

Fiil-öncelikli bölümler flag'leri belgeler.