Obsidian Headless Sync Guide White

Obsidian Headless Sync

GUI 없는 환경(서버, NAS, CI/CD)에서 볼트를 동기화하세요

Open Beta

Sync 플러그인 vs Headless Sync

Obsidian 데스크톱 앱을 이미 쓰고 있다면 Sync 플러그인이 모든 기능을 제공합니다. Headless는 GUI 없는 환경을 위한 별도 도구입니다.

Sync 플러그인 (데스크톱 앱)
버전 히스토리
선택적 동기화
충돌 해결 UI
모든 Sync 기능 제공

Headless Sync (CLI)

단순 파일 동기화만 수행
플러그인 기능 없음
서버, NAS, CI/CD 전용
E2E 암호화 동일 지원

Headless가 유용한 시나리오

💾

서버 자동 백업

서버에서 크론잡으로 볼트를 자동 백업합니다.

🖥️

앱 미설치 기기에서 접근

Obsidian이 설치되지 않은 기기에서 볼트 파일에 접근합니다.

⚙️

CI/CD 빌드

CI/CD 파이프라인에서 볼트 콘텐츠를 가져와 빌드합니다.

데스크톱 앱 사용자라면 — 기존 Sync 플러그인을 그대로 쓰세요. Headless로 대체하면 Sync 플러그인 기능을 잃게 됩니다. 데스크톱 앱 싱크를 끄지 마세요!

주의사항

⚠ 시작 전 반드시 확인하세요

시작 전 반드시 데이터를 백업하세요.
같은 기기에서 데스크톱 앱 Sync와 Headless Sync를 동시에 사용하지 마세요. 데이터 충돌 위험이 있습니다.
Obsidian Sync 유료 구독이 필요합니다.

Quick Start

Node.js 22 이상이 필요합니다. 설치부터 동기화까지 4단계면 충분합니다.

설치

$ npm install -g obsidian-headless

볼트 설정

# 리모트 볼트 목록 확인
$ ob sync-list-remote

# 볼트 연결
$ cd ~/vaults/my-vault
$ ob sync-setup --vault "My Vault"

동기화

# 1회 동기화
$ ob sync

# 지속 동기화 (변경사항 감시)
$ ob sync --continuous

명령어 레퍼런스

ob login

Obsidian 계정으로 로그인합니다. 이미 로그인된 경우 계정 정보를 표시합니다.

ob login [--email <email>] [--password <password>] [--mfa <code>]

모든 옵션은 생략 시 대화형으로 입력받습니다. 2FA가 활성화된 경우 자동으로 요청합니다.

ob logout

로그아웃하고 저장된 인증 정보를 삭제합니다.

ob sync-list-remote

계정에서 사용 가능한 모든 리모트 볼트를 표시합니다. 공유 볼트도 포함됩니다.

ob sync-list-local

로컬에 설정된 볼트 목록과 경로를 표시합니다.

ob sync-create-remote

새 리모트 볼트를 생성합니다.

ob sync-create-remote --name "Vault Name" \
  [--encryption <standard|e2ee>] \
  [--password <password>] \
  [--region <region>]

옵션	설명
`--name`	볼트 이름 (필수)
`--encryption`	`standard` (관리형 암호화) 또는 `e2ee` (종단간 암호화)
`--password`	E2E 암호화 비밀번호 (생략 시 입력 프롬프트)
`--region`	서버 리전 (미지정 시 자동)

ob sync-setup

로컬 볼트와 리모트 볼트 간 동기화를 설정합니다.

ob sync-setup --vault <id-or-name> \
  [--path <local-path>] \
  [--password <password>] \
  [--device-name <name>] \
  [--config-dir <name>]

옵션	설명
`--vault`	리모트 볼트 ID 또는 이름 (필수)
`--path`	로컬 디렉터리 (기본: 현재 디렉터리)
`--password`	E2E 암호화 비밀번호 (생략 시 입력 프롬프트)
`--device-name`	버전 히스토리에 표시할 기기 이름
`--config-dir`	설정 디렉터리 이름 (기본: `.obsidian`)

ob sync

설정된 볼트의 동기화를 실행합니다.

ob sync [--path <local-path>] [--continuous]

옵션	설명
`--path`	로컬 볼트 경로 (기본: 현재 디렉터리)
`--continuous`	지속 동기화 모드 (변경사항 감시)

ob sync-status

볼트의 동기화 상태와 설정을 표시합니다.

ob sync-status [--path <local-path>]

ob sync-unlink

볼트의 동기화 연결을 해제하고 저장된 인증 정보를 삭제합니다.

ob sync-unlink [--path <local-path>]

동기화 설정

옵션 없이 실행하면 현재 설정을 표시합니다.

ob sync-config [--path <local-path>] [options]

옵션	설명
`--conflict-strategy`	`merge` 또는 `conflict`
`--file-types`	동기화할 첨부파일 유형 `image`, `audio`, `video`, `pdf`, `unsupported` 콤마로 구분, 비우면 모두 제외
`--configs`	동기화할 설정 카테고리 `app`, `appearance`, `appearance-data`, `hotkey`, `core-plugin`, `core-plugin-data`, `community-plugin`, `community-plugin-data` 콤마로 구분, 비우면 설정 동기화 비활성화
`--excluded-folders`	제외할 폴더 (콤마로 구분, 비우면 초기화)
`--device-name`	버전 히스토리에 표시할 기기 이름
`--config-dir`	설정 디렉터리 이름 (기본: `.obsidian`)

Native Modules

macOS/Windows에서 파일 생성 시간(birthtime)을 보존하는 네이티브 애드온이 포함되어 있습니다. N-API v3 기반으로 Node.js 버전 간 호환성이 보장됩니다.

지원 플랫폼

플랫폼	아키텍처	birthtime 보존
Windows	x64, arm64, ia32	✅
macOS	x64, arm64	✅
Linux	-	❌ (동기화는 정상 작동)