Obsidian CLI 비교: 공식 CLI vs URI vs 직접 파일 조작

이 글은 Obsidian CLI 시리즈의 두 번째 글이다.

1. Obsidian CLI 입문: 터미널에서 노트를 다루는 새로운 방법
2. Obsidian CLI 비교: 공식 CLI vs URI vs 직접 파일 조작 ← 현재 글
3. Obsidian CLI 자동화: 스크립트와 워크플로우 실전 가이드

세 가지 접근법

Obsidian을 터미널에서 제어하는 방법은 크게 세 가지다:

1. 공식 CLI — Obsidian v1.12부터 내장된 커맨드라인 도구
2. URI scheme — obsidian:// 프로토콜로 앱에 명령을 전달
3. 직접 파일 조작 — 볼트가 마크다운 디렉토리라는 점을 이용

각각 동작 방식이 다르고, 잘하는 것과 못하는 것이 다르다.

공식 CLI

1편에서 자세히 다뤘다. 핵심만 정리하면:

동작 방식

obsidian 명령어 → 로컬 소켓 → Obsidian 프로세스 → 볼트 조작

Obsidian 내부 API를 직접 호출한다. 파일을 이동하면 위키링크가 자동 업데이트되고, 속성 변경은 인덱스에 즉시 반영된다.

장점

• 완전한 기능 지원 — 데일리 노트, 태스크, 검색, 태그, 템플릿 등 Obsidian 기능을 그대로 사용
• 인덱스 즉시 반영 — 변경 사항이 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"

장점

• 앱 설치만 되면 동작 — 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
• 브라우저나 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까지.