Obsidian 자동화를 붙이다 보면
어느 순간
이 두 개가 한 덩어리처럼 보인다.
Headless Sync.
그리고 CLI.
둘 다
앱 안 열고 뭔가 될 것 같고,
둘 다
터미널 친화적으로 들리고,
둘 다
이제 자동화 가능
느낌을 준다.
그래서 자주 생기는 오해가 이거다.
Headless Sync도 있고 CLI도 있으니, 같은 기기에서 같은 볼트에 이것저것 동시에 돌려도 되겠네?
내 답은
꽤 단호하다.
읽기 위주의 확인 작업은 몰라도, 같은 기기에서 같은 볼트에 대한 동시 쓰기 작업은 분리하는 쪽이 훨씬 안전하다.
그리고 이건
감정 섞인 겁주기가 아니다.
공식 문서가 말하는 역할 차이와,
Sync 상태 저장 관련 버그 수정 내역,
그리고 실제 볼트를 굴려본 운영 경험을 합쳐보면
그렇게 보는 게 맞다.
먼저 공식 사실부터 보자.
Obsidian은 2026년 2월 27일
Desktop 1.12에서
공식 CLI를 소개했다.
Changelog는
CLI를
터미널에서 Obsidian을 제어해
scripting,
automation,
external tools integration에 쓰는 인터페이스라고 설명한다.
같은 날
Sync changelog는
obsidian-headless client를 통해
Obsidian Sync가
headless operation을 지원한다고 적었다.
즉,
공식 문서 기준으로도
둘은 같은 물건이 아니다.
CLI는
제어 인터페이스다.
Headless Sync는
동기화 계층이다.
여기서부터
구조를 잘못 이해하면
자동화는 금방 꼬인다.
이 글은
기능 소개가 아니라
운영 구분 글이다.
무엇을 Headless Sync에 맡기고,
무엇을 CLI에 맡기고,
같은 기기에서 무엇은 같이 돌려도 되고
무엇은 겹치면 안 되는지
실전 기준으로 정리해보자.
한 줄 답
Headless Sync는 Sync 계층이다. 앱 없이도 동기화 상태를 다루는 쪽에 가깝다.CLI는 Obsidian 제어 계층이다. 터미널에서 명령을 보내 자동화와 외부 도구 통합에 쓰는 쪽이다.- 둘은 대체제가 아니라 역할이 다르다.
- 공식 문서가
같은 기기에서 절대 동시에 쓰지 마라고 그대로 적지는 않았지만, Sync 상태 덮어쓰기 수정 내역과 역할 차이를 보면 같은 볼트에 대한 동시 쓰기 작업은 분리하는 쪽이 안전하다.
먼저 공식 문서가 말하는 사실부터 정리
2026년 2월 27일
Obsidian Desktop 1.12 changelog는
공식 CLI를 소개했다.
설명은 꽤 직접적이다.
CLI는
터미널에서 Obsidian을 제어하는
command line interface이고,
scripting,
automation,
integration with external tools에 쓰인다고 한다.
같은 changelog 흐름에서
CLI는 이후에도 계속 보강됐다.
daily:path,
rename,
search와 search:context 분리,
silent 기본 동작,
autocompletion,
Windows/macOS/Linux 관련 감지 수정 같은 것들이
짧은 주기로 붙었다.
특히 2026년 3월 18일 changelog는
installer에
새 CLI binary를 묶어
기존 Electron binary 호출보다
터미널 상호작용이 훨씬 빨라졌다고 적는다.
반면
Headless 쪽 공식 사실은
같은 2026년 2월 27일 Sync changelog에서 나온다.
여기서는
Obsidian Sync가
obsidian-headless client를 통해
headless operation을 지원한다고 설명한다.
즉,
공식 문서 문장만 나눠 읽어도
차이는 꽤 선명하다.
CLI는
control Obsidian from your terminal
이다.
Headless Sync는
Obsidian Sync now supports headless operation
이다.
같은 자동화 풍으로 보이지만,
하나는 제어다.
다른 하나는 동기화다.
이 차이를 머리에 먼저 박아야
운영이 안 꼬인다.
왜 둘을 같은 계층으로 보면 안 되나
CLI와 Headless Sync를
같은 상자에 넣어버리면
사람은 금방 이런 식으로 설계한다.
한쪽에서 Headless Sync client로 당기고,
다른 쪽에서 CLI로 파일을 열고 바꾸고,
또 다른 스크립트는 직접 filesystem에 쓰고,
마지막에 Sync가 알아서 맞추겠지.
문제는
이 설계가
겉으로는 똑똑해 보여도
상태 경계를 너무 많이 섞는다는 점이다.
내가 보는 Obsidian 자동화의 층은
대략 세 개다.
| 층 | 대표 도구 | 질문 | 주 역할 |
|---|---|---|---|
| sync layer | Headless Sync | 파일 상태를 어떻게 동기화하나 | 원격/클라우드 상태 맞춤 |
| control layer | CLI | Obsidian에 어떤 명령을 보내나 | 앱/볼트 제어, 명령 실행 |
| mutation layer | filesystem/no-focus helper | 실제 파일을 어떻게 바꾸나 | 생성, 이동, frontmatter 수정 |
이 표에서 중요한 건
하나가 다른 하나를 대체하지 않는다는 점이다.
CLI가 있다고
Sync 상태 관리가 되는 건 아니다.
Headless Sync가 있다고
노트 이동 규칙이나
frontmatter 운영 기준이 해결되는 것도 아니다.
filesystem write가 빠르다고
링크 무결성이나
상태 경쟁 문제가 자동으로 없어지는 것도 아니다.
즉,
도구가 늘어날수록
할 수 있는 일은 많아지지만,
경계도 같이 늘어난다.
공식 문서가 직접 말하는 역할 차이
공식 CLI 소개 문구는
터미널에서 Obsidian을 제어해
scripting,
automation,
external tools integration에 쓰라고 한다.
이건
명령 인터페이스 성격이 강하다.
반대로
Headless Sync 소개는
Sync 자체가 headless operation을 지원한다는 말에 가깝다.
여기서 중요한 건
문서의 주어가 다르다는 점이다.
CLI 문구의 주어는
Obsidian 제어다.
Headless Sync 문구의 주어는
Sync operation이다.
그래서 내가 실무적으로 번역한 한 줄은 이거다.
CLI는 동작을 지시하는 쪽이고, Headless Sync는 상태를 맞추는 쪽이다.
이 차이를 안 나누면
동기화 도구에 제어 책임을 떠넘기거나,
반대로 제어 도구에 상태 일관성까지 기대하게 된다.
둘 다 오래 못 간다.
그럼 무엇을 Headless Sync에 맡겨야 하나
Headless Sync는
이름 그대로
앱을 띄우지 않고
동기화 계층을 다루고 싶을 때 쓰는 게 맞다.
예를 들면 이런 쪽이다.
- 서버나 CI 성격의 머신에서 Sync 상태를 맞추는 일
- 백업/미러링 성격의 흐름
- 앱 UI를 건드리지 않고 vault 상태를 내려받거나 맞추는 일
중요한 건
Headless Sync를
노트 편집 도구
로 착각하지 않는 거다.
편집 자체보다
동기화 계층에 더 가깝게 두는 편이 안전하다.
그럼 무엇을 CLI에 맡겨야 하나
CLI는
명령을 보내는 데 강하다.
공식 changelog 흐름만 봐도
help,
rename,
daily path,
search context,
autocompletion처럼
볼트를 다루는 명령 인터페이스
가 계속 보강됐다.
즉,
CLI는
자동화 파이프라인의 control plane으로 보는 게 맞다.
예를 들면 이런 쪽이다.
- 특정 파일 경로 계산
- 검색과 컨텍스트 조회
- rename 같은 앱 친화 명령
- 외부 스크립트나 에이전트가 호출하는 제어 인터페이스
다만 여기서도
주의가 하나 있다.
CLI가 제어 인터페이스라고 해서
모든 쓰기 작업을 다 CLI 한 바구니에 넣는 게 정답은 아니다.
왜냐하면 실제 운영에서는
filesystem/no-focus 계층이
더 안전한 경우도 많기 때문이다.
우리 볼트가 no-focus를 기본으로 두는 이유
여기서부터는
공식 문서가 아니라
우리 운영 해석이다.
이 워크스페이스의 기본 규칙은
앱 포커스를 건드리지 않는
filesystem/no-focus 모드다.
파일 이동은
safe-move,
frontmatter 변경은
helper나 direct write,
노트 열기는
명시적 opt-in이 없으면 막는다.
왜 이렇게 하냐면
앱 포커스 보존과
실행 안정성을
링크 자동 업데이트보다 더 우선할 때가 있기 때문이다.
즉,
우리는 이미
CLI만 믿고 달리는 구조가 아니라,
CLI가 맞는 곳
filesystem/no-focus가 맞는 곳
를 나눠서 쓴다.
이 운영 경험이
Headless Sync vs CLI 구분에도 그대로 이어진다.
도구 하나로 만능 해결을 기대하지 않는 게
오히려 덜 망가진다.
같은 기기에서 절대 같이 돌리면 안 되는 작업은 뭐냐
이제 본론이다.
제목을 세게 쓴 이유가 여기 있다.
공식 문서가
같은 기기에서 절대 같이 돌리면 안 된다
를 그대로 말하진 않는다.
이건 내 운영 규칙이다.
하지만 완전히 공중에서 튀어나온 규칙은 아니다.
근거는 세 가지다.
첫째,
CLI와 Headless Sync는 역할 계층이 다르다.
둘째,
Obsidian Sync changelog는
앱이 최신 Sync state를 저장하기 전에 종료되면
파일이 override될 수 있었던 문제를 수정했다고 적었다.
즉,
공식 수정 내역 자체가
상태 저장 타이밍이 민감하다는 걸 보여준다.
셋째,
같은 기기에서 같은 볼트에 대해
동시에 여러 write plane을 겹치면
문제가 생겼을 때
원인 분리가 거의 안 된다.
그래서 내가 금지하는 건
대체로 이런 조합이다.
금지 1. 같은 볼트 같은 파일에 대한 동시 쓰기
Headless Sync가 상태를 당기거나 맞추는 동안
CLI나 filesystem helper가
같은 파일을 계속 수정하는 흐름이다.
이건 피하는 게 맞다.
금지 2. 같은 기기에서 sync layer와 mutation layer를 무계획하게 중첩
예를 들어
headless client가 계속 동기화 중인데,
별도 cron이 direct write를 하고,
또 다른 작업은 rename/move를 때리는 식이다.
문제 생기면
누가 마지막 writer였는지 추적이 지옥이 된다.
금지 3. 앱/CLI/headless를 동시에 write master처럼 취급
세 도구를 모두
어차피 파일 바꾸는 도구
로 보면 안 된다.
master write plane은
한 순간에 하나로 두는 편이 안전하다.
반대로 같이 돌려도 되는 조합은 뭐냐
금지 규칙만 있으면
숨막히니까
허용 규칙도 같이 보자.
허용 1. Headless Sync + 읽기 전용 분석
동기화는 동기화대로 두고,
별도 스크립트는
읽기 전용 검색,
통계 집계,
인덱싱만 하는 경우다.
write가 없으면
충돌 위험이 훨씬 작다.
허용 2. CLI + 단일 쓰기 루프
하나의 자동화가
CLI를 통해 제어하고,
동시에 다른 write plane은 잠궈두는 방식이다.
이건 비교적 관리가 쉽다.
허용 3. filesystem/no-focus helper + sync 비활성 시간대
우리 볼트처럼
no-focus helper를 중심으로
파일 이동과 frontmatter 업데이트를 하고,
Sync 성격 작업은 다른 시간대로 분리하는 방식이다.
실무에서는
이쪽이 훨씬 덜 깨졌다.
내가 추천하는 운영 모델
가장 덜 헷갈리는 모델은
도구별 전담 역할을 주는 거다.
| 역할 | 추천 도구 | 이유 |
|---|---|---|
| 볼트 상태 맞춤 | Headless Sync | sync layer 책임 |
| 앱/명령 제어 | CLI | control plane 책임 |
| 일상 파일 변경 | helper/direct write | no-focus 운영과 잘 맞음 |
이렇게 나누면
질문도 쉬워진다.
이건 sync 문제인가
제어 문제인가
파일 변경 문제인가
장애 대응이 빨라지는 이유도
여기 있다.
도구를 줄여서가 아니라
책임을 분리해서다.
공식 changelog에서 읽어야 할 진짜 포인트
많은 사람이
Obsidian changelog를 읽을 때
새 기능만 본다.
근데 운영자는
오히려 bug fix를 더 봐야 한다.
이번 흐름에서 중요한 건
CLI가 빨라졌다는 사실도 맞지만,
Sync 상태 저장 관련 override 이슈가
수정됐다는 점이다.
이건 곧
state coordination이
사소한 문제가 아니라는 뜻이다.
그래서 내가 내리는 실무 해석은 이거다.
공식 기능이 늘어날수록
같이 돌리기 쉬워졌다
보다
경계 나누기가 더 중요해졌다
로 읽는 편이 맞다.
자주 나오는 오해 5개
1. Headless Sync가 있으니 CLI는 필요 없다는 오해
아니다.
Headless Sync는 sync layer고,
CLI는 control layer다.
역할이 다르다.
2. CLI가 있으니 direct write는 없어도 된다는 오해
상황에 따라 다르다.
우리처럼 no-focus 운영을 우선하는 볼트에서는
helper/direct write가
더 예측 가능한 경우가 많다.
3. 둘 다 앱 없이 된다면 동시에 돌려도 된다는 오해
이게 제일 위험하다.
앱 없이 된다는 사실과
동시 쓰기 안전성은
같은 말이 아니다.
4. sync와 mutation은 결국 파일 하나를 만지는 거니 같은 층이라는 오해
겉으로는 같아 보여도
역할이 다르다.
같이 쓰면
원인 추적이 어려워진다.
5. 빠른 도구 하나로 통일하면 운영도 단순해진다는 오해
오히려 책임 분리가 더 중요하다.
하나로 몰수록
문제 났을 때 복구선이 흐려진다.
바로 따라 하는 체크리스트
-
내 자동화에서 sync layer와 control layer를 구분해서 그린다.
-
Headless Sync를
동기화, CLI를제어로 먼저 배치한다. -
같은 기기에서 같은 볼트에 대한 동시 write 작업이 있는지 확인한다.
-
있으면 master write plane을 하나로 줄인다.
-
앱 포커스를 건드리기 싫으면 helper/direct write와 CLI 경계를 문서화한다.
-
rename, move, frontmatter 수정 중 무엇을 어느 계층에 맡길지 정한다.
-
장애가 났을 때 누가 마지막 writer인지 추적 가능한 로그를 남긴다.
이 체크리스트만 해도
Headless Sync와 CLI를
둘 다 좋음
수준에서
어디에 써야 하는지 앎
수준으로 끌어올릴 수 있다.
한 줄 결론
Obsidian Headless Sync와 CLI는
비슷해 보여도
같은 물건이 아니다.
Headless Sync는
동기화 계층이고,
CLI는
제어 계층이다.
그리고 우리 같은 실전 운영에서는
filesystem/no-focus helper까지 더해져
변경 계층이 따로 생긴다.
그래서 같은 기기에서
같은 볼트에 대한 동시 쓰기 작업을
여러 계층에 걸쳐 겹치게 만드는 건
피하는 쪽이 훨씬 안전하다.
멋있어 보이는 건
도구를 많이 겹쳐 쓰는 설계다.
오래 가는 건
층을 나눠서 책임을 분리하는 설계다.
Obsidian 자동화도 결국
도구 싸움이 아니라
경계 설계 싸움이다.
FAQ
Headless Sync와 CLI는 둘 중 하나만 쓰면 되나
꼭 그렇진 않다.
다만 둘을 같은 계층으로 보면 안 된다.
Headless Sync는 동기화 쪽,
CLI는 제어 쪽으로 보는 편이 안전하다.
공식 문서가 같은 기기 동시 사용을 금지하나
그 문장 그대로 적지는 않는다.
이 글의 절대 같이 돌리면 안 되는 작업은
공식 역할 차이와 Sync 상태 관련 수정 내역,
그리고 local no-focus 운영 경험을 바탕으로 한
운영 규칙 해석이다.
즉,
공식 사실 위에 얹은 실무 판단이다.
같은 기기에서 같이 돌려도 되는 건 아예 없나
읽기 전용 분석이나
시간 분리된 작업은 상대적으로 안전하다.
문제는 같은 볼트,
같은 파일,
같은 시점의 동시 write다.
이건 피하는 게 낫다.
그럼 master write plane은 뭘로 두는 게 좋나
팀과 볼트 성격에 따라 다르다.
우리 워크스페이스처럼
no-focus를 기본으로 두는 환경에서는
helper/direct write 중심이 더 예측 가능한 경우가 많다.
중요한 건
무엇을 고르느냐보다
한 순간에 하나만 master로 두는 것이다.
CLI가 계속 빨라지고 좋아지는데 direct write는 왜 남겨두나
속도와 안정성은 같은 기준이 아니다.
특정 작업은 CLI가 좋고,
특정 작업은 no-focus helper가 더 맞다.
운영자는
도구 통일보다
책임 분리를 먼저 봐야 한다.