이 글은 Obsidian CLI 시리즈의 두 번째 글입니다.
- Obsidian CLI 입문: 터미널에서 노트를 다루는 새로운 방법
- Obsidian CLI 비교: 공식 CLI vs URI vs 직접 파일 조작 ← 현재 글
- Obsidian CLI 자동화: 스크립트와 워크플로우 실전 가이드
세 가지 접근법
Obsidian을 터미널에서 제어하는 방법은 크게 세 가지입니다.
- 공식 CLI: Obsidian v1.12부터 내장된 커맨드라인 도구
- URI scheme:
obsidian://프로토콜로 앱에 명령을 전달 - 직접 파일 조작: 볼트가 마크다운 디렉토리라는 점을 이용
각각 동작 방식이 다르고, 잘하는 것과 못하는 것이 다릅니다.
공식 CLI
1편에서 자세히 다뤘습니다. 핵심만 정리하면 다음과 같습니다.
동작 방식
obsidian 명령어 → 로컬 소켓 → Obsidian 프로세스 → 볼트 조작
Obsidian 내부 API를 직접 호출합니다. 파일을 이동하면 위키링크가 자동 업데이트되고, 속성 변경은 인덱스에 즉시 반영됩니다.
강점은 기능이 온전하다는 데 있습니다. 데일리 노트, 태스크, 검색, 태그, 템플릿 등 Obsidian 기능을 그대로 쓸 수 있고, 변경이 캐시와 그래프에 즉시 반영되며, 파일을 옮기거나 이름을 바꿔도 위키링크가 자동으로 따라 업데이트됩니다. Templater나 Dataview 같은 플러그인과도 호환됩니다.
대신 앱에 묶입니다. Obsidian 데스크톱 앱이 켜져 있어야 하고, 그래서 SSH로 접속한 원격 서버에서는 쓸 수 없습니다. 기능 자체가 v1.12 이상에서만 제공되므로 이전 버전 사용자는 업데이트가 필요합니다.
대표 명령어
obsidian daily:append content="메모 내용"
obsidian search query="키워드"
obsidian create name="노트명" template="템플릿"
obsidian tags counts
Obsidian URI Scheme
obsidian://로 시작하는 URL을 통해 Obsidian에 명령을 전달하는 방법입니다.
동작 방식
open "obsidian://..." → OS URL 핸들러 → Obsidian 앱 → 동작 실행
macOS에서는 open 명령어, Linux에서는 xdg-open을 사용합니다.
기본 URI
# 특정 노트 열기
open "obsidian://open?vault=MyVault&file=Projects/blog"
# 새 노트 생성
open "obsidian://new?vault=MyVault&name=Meeting/standup&content=회의%20메모"
# 검색
open "obsidian://search?vault=MyVault&query=TODO"
URL이므로 특수문자는 퍼센트 인코딩이 필요합니다. 한글도 마찬가지:
# 한글 포함 시
open "obsidian://open?vault=MyVault&file=$(python3 -c 'import urllib.parse; print(urllib.parse.quote("프로젝트/일정"))')"
Advanced URI 플러그인
obsidian-advanced-uri 플러그인을 설치하면 URI의 기능이 크게 확장됩니다.
# 데일리 노트에 클립보드 내용 추가
open "obsidian://adv-uri?vault=MyVault&daily=true&clipboard=true&mode=append"
# 특정 헤딩 아래에 내용 추가
open "obsidian://adv-uri?vault=MyVault&filepath=Projects/blog.md&heading=TODO&data=새%20항목&mode=append"
# Obsidian 커맨드 실행
open "obsidian://adv-uri?vault=MyVault&commandid=editor:toggle-bold"
URI 방식의 매력은 진입 장벽이 낮다는 데 있습니다. CLI를 따로 활성화하지 않아도 앱만 설치돼 있으면 동작하고, 브라우저나 Alfred, Raycast, Shortcuts 같은 외부 앱에서 호출할 수 있으며, macOS, Windows, Linux를 모두 지원합니다.
한계도 뚜렷합니다. 기본 URI로는 열기, 생성, 검색 정도만 가능하고, 한글이나 특수문자가 들어가면 URL 인코딩이 번거로워집니다. 무엇보다 명령을 보내기만 할 뿐 결과를 터미널로 받아올 수 없고, 고급 기능은 Advanced URI 플러그인에 의존합니다.
직접 파일 조작 (Vault as Code)
Obsidian 볼트의 본질은 마크다운 파일이 들어 있는 디렉토리입니다. 따라서 표준 유닉스 도구로 직접 조작할 수 있습니다.
사용 예시
# 볼트 구조 확인
ls ~/Documents/MyVault/
# 키워드 검색
grep -r "TODO" ~/Documents/MyVault/ --include="*.md"
# 특정 태그가 달린 파일 찾기
grep -rl "#project" ~/Documents/MyVault/ --include="*.md"
# 노트 생성
cat << 'EOF' > ~/Documents/MyVault/TIL/obsidian-cli.md
---
tags: [til, obsidian]
---
# Obsidian CLI
오늘 배운 것
EOF
# 일괄 태그 변경
find ~/Documents/MyVault -name "*.md" -exec sed -i '' 's/#old-tag/#new-tag/g' {} +
fzf와 조합
# fzf로 노트 선택해서 Neovim으로 열기
find ~/Documents/MyVault -name "*.md" | fzf --preview 'head -20 {}' | xargs nvim
이 방식의 장점은 앱에서 완전히 자유롭다는 것입니다. Obsidian이 설치돼 있지 않아도, SSH로 접속한 원격 서버에서도 동작합니다. grep, sed, awk, find 같은 유닉스 도구를 전부 끌어다 쓸 수 있어 유연성이 가장 크고, 수백 개 파일을 일괄 수정하는 대량 처리도 간편합니다.
문제는 Obsidian을 거치지 않는다는 데서 그대로 나옵니다. 변경 사항은 앱을 다시 열거나 리로드해야 인덱스에 반영되고, 파일을 옮기거나 이름을 바꾸면 위키링크가 자동으로 따라오지 않습니다. Templater나 Dataview 같은 플러그인 기능도 적용되지 않으며, 프론트매터 YAML 포맷은 직접 맞춰야 합니다.
종합 비교
| 기능 | 공식 CLI | URI Scheme | 직접 파일 조작 |
|---|---|---|---|
| 앱 실행 필요 | 필수 | 필수 | 불필요 |
| 원격 서버 사용 | — | — | 지원 |
| 검색 결과 반환 | 터미널 출력 | — | grep 등 |
| 위키링크 자동 업데이트 | 지원 | — | — |
| 인덱스 즉시 반영 | 지원 | 지원 | 지연 |
| 플러그인 연동 | 지원 | 일부 | — |
| 템플릿 지원 | 지원 | Advanced URI | 수동 |
| 대량 일괄 처리 | 루프 필요 | — | 지원 |
| 외부 앱 연동 | — | 지원 | — |
| 설정 난이도 | 낮음 | 낮음 | 없음 |
이럴 때는 이것을
- 터미널에서 빠르게 노트를 쓰고 싶다 → 공식 CLI
- 브라우저나 Alfred에서 Obsidian을 열고 싶다 → URI scheme
- 수백 개 파일의 태그를 일괄 수정하고 싶다 → 직접 파일 조작
- 서버에서 마크다운 파일을 관리하고 싶다 → 직접 파일 조작
- 데일리 노트를 자동으로 만들고 싶다 → 공식 CLI
- Shortcuts/Raycast에서 Obsidian 연동 → URI scheme
조합해서 쓰기
실제로는 하나만 쓰기보다 상황에 따라 조합하는 편이 낫습니다.
예시 워크플로우는 다음과 같습니다.
# 1. 공식 CLI로 데일리 노트 작성 (인덱스 반영 + 템플릿 적용)
obsidian daily:append content="## 작업 로그"
# 2. grep으로 볼트 전체에서 미완료 태스크 카운트 (대량 검색에 강함)
grep -rc "\- \[ \]" ~/Documents/MyVault/ --include="*.md" | sort -t: -k2 -rn | head -5
# 3. URI로 특정 노트를 Obsidian GUI에서 열기 (그래프 뷰 등 GUI 기능 활용)
open "obsidian://open?vault=MyVault&file=Projects/dashboard"
각 방법의 강점을 살려서 쓰면 됩니다. CLI로 안 되는 대량 처리는 직접 파일 조작으로, 터미널에서 안 되는 GUI 기능은 URI로 보완합니다.
마치며
세 방법은 맞고 틀리고의 문제가 아니라 각각 잘하는 것이 다르고, 상황에 따라 최적의 도구가 달라집니다.
일상적인 노트 작성에는 공식 CLI가 가장 편하고, 대량 처리에는 직접 파일 조작이, 외부 앱 연동에는 URI scheme이 낫습니다.
다음 글에서는 이 도구들을 활용한 실전 자동화 워크플로우를 정리해요. 셸 별칭, cron, tmux 연동, git hook까지 다룰게요.