설치

머신에 openspec CLI를 설치하고, 업데이트하고, 제거하는 방법입니다.

설치

macOS 또는 Linux에서는 터미널에서 다음을 실행합니다:

curl -fsSL https://openspec.dev/cli/install.sh | sh

Windows에서는 PowerShell에서 다음을 실행합니다:

irm https://openspec.dev/cli/install.ps1 | iex

설치 프로그램이 export PATH=... 줄을 출력하면 해당 줄을 실행합니다. 그런 다음 제대로 설치되었는지 확인하세요.

AI 어시스턴트로 설치

AI 채팅에 다음을 붙여넣습니다:

Fetch https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md and follow it.

또는 터미널에서 CLI 에이전트로 파이프할 수 있습니다 (Claude Code 예시):

curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/install.md | claude

이 명령은 저장소 루트의 install.md를 가져옵니다. 이 파일은 셸 명령을 실행할 수 있는 모든 에이전트를 위해 작성된 프롬프트입니다 (일부 IDE 통합에서는 실행할 수 없습니다). 어시스턴트가 다음을 수행할 것으로 예상됩니다:

1. CLI가 이미 머신에 설치되어 있으면 설치를 건너뛰고, 원래 설치된 방식으로 업데이트를 제안합니다. npm 또는 Homebrew로 설치된 경우라면, openspec install이 스탠드얼론 설치로 전환한다는 점을 한 번만 언급하고 강요하지 않습니다. 그 외의 경우에는 위의 설치 명령을 보여주고 실행 전에 확인을 기다립니다.
2. 직접 요청하거나 설치 프로그램이 실패한 경우에만 npm을 대신 사용하며, Node 버전이 22.12.0보다 오래되면 중단합니다.
3. openspec이 PATH에 있는지 확인합니다.
4. 의도한 것으로 판단한 폴더 이름을 말하고, 현재 대화 중인 AI 도구를 제안하며, 다른 도구를 사용하는지 묻은 다음, 해당 폴더에서 openspec init을 실행합니다 (프로젝트 설정 단계).
5. init이 생성한 내용과 사용 중인 도구에서 OpenSpec을 호출할 때 필요한 정확한 명령 표기를 알려줍니다.

이 프롬프트는 권한이 필요한 작업을 수행하기 전에 멈추며, 셸 시작 파일은 절대 수정하지 않습니다. 위의 설치 명령과 아래의 패키지 관리자가 기준이 되며, 프롬프트는 이를 대신 실행해 줍니다.

이 설치 방법은 새로 나온 것으로, 사용한 모델에 따라 결과가 달라질 수 있습니다. AI의 실수를 바로잡는 것이 부담스럽지 않을 때만 사용하세요. 그렇지 않다면 아래의 표준 방법을 따르는 것을 권장합니다.

패키지 관리자

이 방법들은 OpenSpec을 Node.js 패키지로 설치하므로 Node.js 22.12.0 이상이 필요합니다 (Homebrew와 Nix는 자체적으로 포함합니다). 터미널에서 다음을 실행합니다:

node --version

v22.12.0 이상이 출력되면 npm으로 설치합니다:

npm install -g @fission-ai/openspec@latest

그렇지 않다면 nodejs.org에서 더 새로운 Node를 설치하거나 버전 관리자(nvm, fnm, asdf, volta)를 통해 설치하거나, 대신 스탠드얼론 설치를 사용하세요.

Homebrew

Homebrew는 macOS 또는 Linux에 OpenSpec과 그 Node.js 의존성을 설치합니다. 터미널에서 다음을 실행합니다:

brew install openspec

포뮬러는 homebrew-core에 게시되어 있으므로 탭을 추가할 필요가 없습니다.

Yarn

yarn global add는 Yarn Classic(1.x)에서만 지원됩니다. 최신 Yarn은 전역 설치를 제거했으므로 npm, pnpm 또는 bun을 대신 사용하세요. 전역 CLI는 프로젝트의 패키지 관리자와 동일할 필요가 없습니다.

Bun

Bun은 OpenSpec을 설치하지만 실행하지는 않으므로, 머신에 Node가 여전히 필요합니다 (패키지 관리자 참조). Node가 없으면 모든 명령이 env: node: No such file or directory 오류로 실패합니다. Bun은 모든 Node CLI를 이런 식으로 처리합니다.

Deno

Deno는 npm에서 CLI를 설치하며 명시적인 권한 플래그가 필요합니다. 터미널에서 다음을 실행합니다:

deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest

일부 명령은 다른 프로그램을 실행합니다: openspec config edit은 편집기를 엽니다. Deno는 이런 명령이 실행될 때마다 권한 프롬프트로 실행을 중단시킵니다. 매번 묻지 않으려면 설치 명령에 범위가 한정된 --allow-run=<program>을 추가하세요.

NOTE

Deno가 @latest를 확인하지 못하면 대신 버전 범위를 고정하세요: npm:@fission-ai/openspec@^1.7.0.

Nix

OpenSpec 저장소에는 Nix flake가 포함되어 있습니다. 프로필에 설치하세요. 터미널에서 다음을 실행합니다:

nix profile install github:Fission-AI/OpenSpec

또는 설치하지 않고 일회성 명령을 먼저 실행할 수 있습니다:

nix run github:Fission-AI/OpenSpec -- --version

이 방식은 PATH에 아무것도 남기지 않으므로, 이후에 확인할 설치가 없습니다.

대신 프로젝트 dev shell에 OpenSpec을 넣으려면 flake를 input으로 추가하고 기본 패키지를 사용하세요. flake.nix에 출력 목록이 나와 있습니다.

Nix 패키지는 Bash, Fish, Zsh 완성 스크립트를 표준 위치(share/bash-completion/completions, share/fish/vendor_completions.d, share/zsh/site-functions)에 포함하고 있으므로, 패키지와 함께 로드되며 openspec completion install을 실행할 필요가 없습니다.

제대로 설치되었는지 확인

어떤 방법을 사용했든, 터미널에서 다음을 실행합니다:

openspec --version

버전 번호가 출력되면 CLI가 PATH에 있는 것입니다. 설치는 머신당 한 번만 하면 됩니다.

다음으로 프로젝트를 설정하세요. 어시스턴트가 이미 init을 실행했다면, 해당 페이지에서 작성된 내용과 조정 방법을 확인할 수 있습니다.

설치 옵션

버전이나 폴더를 지정하려면 sh 앞에 변수를 설정합니다:

curl -fsSL https://openspec.dev/cli/install.sh | OPENSPEC_VERSION=v1.15.0 sh

• OPENSPEC_VERSION: 설치할 릴리스입니다. 예: v1.15.0. 기본값은 최신 릴리스입니다.
• OPENSPEC_INSTALL_DIR: 설치할 폴더입니다. 기본값은 ~/.local/bin입니다 (Windows: %LOCALAPPDATA%\Programs\openspec).

Windows에서는 먼저 변수를 설정합니다:

$env:OPENSPEC_VERSION = 'v1.15.0'
irm https://openspec.dev/cli/install.ps1 | iex

Alpine Linux에서는 설치 전에 apk add libstdc++ libgcc를 실행합니다.

직접 다운로드

각 릴리스는 컴퓨터 종류별로 하나의 파일을 제공합니다:

컴퓨터	파일
Mac, Apple silicon	openspec-darwin-arm64.tar.gz
Mac, Intel	openspec-darwin-x64.tar.gz
Linux, arm64	openspec-linux-arm64.tar.gz
Linux, x64	openspec-linux-x64.tar.gz
Alpine, arm64	openspec-linux-arm64-musl.tar.gz
Alpine, x64	openspec-linux-x64-musl.tar.gz
Windows, arm64	openspec-windows-arm64.zip
Windows, x64	openspec-windows-x64.zip

1. 최신 릴리스에서 해당 파일을 다운로드합니다. 파일은 릴리스가 게시된 후 몇 분 뒤에 첨부됩니다. 아직 목록에 없다면 기다렸다가 새로고침하거나 이전 릴리스에서 가져오세요.
2. 파일을 압축 해제합니다. 터미널에서: tar -xzf openspec-darwin-arm64.tar.gz. Windows에서는 .zip 파일을 마우스 오른쪽 버튼으로 클릭하고 모두 압축 풀기(Extract All)를 선택합니다.
3. macOS에서는 압축을 해제한 폴더에서 xattr -d com.apple.quarantine openspec을 실행합니다. 이를 실행하기 전까지는 macOS가 브라우저에서 다운로드한 파일을 차단합니다.
4. openspec을 ~/.local/bin 같은 PATH에 있는 폴더로 이동합니다. Windows에서는 openspec.exe를 %LOCALAPPDATA%\Programs\openspec 같은 사용자 PATH에 있는 폴더로 이동합니다.

다운로드 검증

파일이 OpenSpec 릴리스 워크플로우에서 빌드된 것인지 확인하려면 GitHub CLI로 다음을 실행합니다:

gh attestation verify openspec-darwin-arm64.tar.gz --repo Fission-AI/OpenSpec

워크플로우가 빌드하지 않은 파일이라면 이 명령은 실패합니다. 설치 명령은 이미 각 다운로드를 릴리스의 SHA256SUMS와 대조하므로, 이 단계는 선택 사항입니다.

npm에서 스탠드얼론 설치로 전환

전환은 선택 사항이며, npm도 계속 작동합니다. 설정과 프로젝트는 그대로 유지되고 프로그램만 바뀝니다.

1. 스탠드얼론 복사본을 설치합니다. 터미널에서 다음을 실행합니다:

openspec install

이 명령은 스탠드얼론 openspec을 설치하고 npm 또는 Homebrew 복사본을 제거하는 명령을 출력합니다.

2. 기존 복사본을 제거합니다. 기존 복사본은 보통 PATH에서 먼저 위치하므로, 제거되기 전까지는 대신 계속 실행됩니다. 1단계에서 출력된 명령을 실행합니다. 예를 들어:

npm uninstall -g @fission-ai/openspec

3. 어떤 복사본이 실행되는지 확인합니다. 새 터미널을 엽니다:

openspec version

OpenSpec <version> (standalone)이 출력되어야 합니다. 대신 패키지 관리자 이름이 표시된다면 다른 복사본이 아직 PATH에 남아 있는 것입니다. which -a openspec (Windows: where.exe openspec)으로 모든 복사본을 확인하고 나머지를 제거하세요.

어떤 프로젝트도 다시 초기화할 필요가 없습니다. 다시 되돌아가려면 파일을 삭제하고 npm 설치를 다시 실행하면 됩니다.

업데이트

터미널에서 init을 실행한 각 프로젝트에서 다음을 실행합니다:

openspec update

더 새로운 CLI가 출시되면 openspec update가 이를 알려주고 대신 설치해 줄 수 있습니다. 이 업그레이드는 머신당 한 번입니다. 명령을 실행할 때마다 프로젝트에 생성된 스킬과 명령이 새로 고쳐지며, 이들은 절대 자동으로 업데이트되지 않습니다. 최신 상태인 프로젝트는 ✓ All 2 tool(s) up to date (v1.7.0)을 출력합니다.

WARNING

스탠드얼론 설치의 경우 openspec install을 실행하여 기존 복사본을 그 자리에서 교체합니다. openspec update는 더 새로운 버전이 출시되었을 때 알려줍니다. Homebrew에서는 brew upgrade openspec을 실행합니다. Deno에서는 Deno 설치 명령을 -f 플래그와 함께 다시 실행하세요. 이 플래그가 없으면 설치된 명령을 덮어쓰지 않습니다. Nix에서는 nix profile upgrade openspec을 사용합니다.

NOTE

전역 npm 설치는 하나의 Node 설치에 속합니다. nvm으로 Node 버전을 전환하면 openspec 명령도 함께 따라오지 않으므로, 새 버전에서 다시 설치해야 합니다.

제거

OpenSpec을 제거하려면 아래 단계를 따르세요. 어떤 단계도 소스 코드에는 영향을 주지 않습니다. 이 섹션을 에이전트에게 보여주고 제거를 맡길 수도 있습니다.

1. 셸 완성을 제거합니다. 설정해 둔 경우, CLI가 아직 작동할 때 제거하세요. 터미널에서 다음을 실행합니다:

openspec completion uninstall

2. CLI를 제거합니다. 스탠드얼론 설치의 경우 ~/.local/bin/openspec을 삭제합니다 (Windows: %LOCALAPPDATA%\Programs\openspec, 그리고 사용자 PATH에서 해당 폴더 제거). npm의 경우 터미널에서 다음을 실행합니다:

npm uninstall -g @fission-ai/openspec

Homebrew: brew uninstall openspec. Deno: deno uninstall --global openspec. Nix: nix profile remove openspec. 셸에서 더 이상 openspec을 찾지 못해야 합니다.

3. 남은 파일을 삭제하거나 유지합니다.

• 생성된 에이전트 파일: 프로젝트별로 .claude/ 또는 .agents/ 같은 디렉터리 아래의 openspec-* 스킬과 opsx 명령. 지원 도구에서 각 도구의 경로를 확인할 수 있으며, MiniMax Code는 스킬을 ~/.minimax/skills에 저장합니다.
• 이전 버전의 잔여물: CLAUDE.md 또는 AGENTS.md의 마커 블록(블록만 삭제하고 파일은 유지)과 ~/.codex/prompts의 opsx-*.md 프롬프트.
• openspec/ 폴더: 삭제 전에 잠시 고민해 보세요. specs/와 changes/archive/는 시스템에 대한 기록으로, OpenSpec 없이도 잘 읽히는 일반 Markdown입니다.
• 머신별 상태: ~/.config/openspec/의 설정과 텔레메트리 id. 그리고 ~/.local/share/openspec/의 스키마 재정의, 스토어 등록 정보, 스탠드얼론 설치의 내장 스키마(binary-schemas/) (Windows: %APPDATA%\openspec, %LOCALAPPDATA%\openspec). 등록 정보는 포인터일 뿐이며, 가리키는 스토어 저장소는 그대로 유지됩니다.