옵시디언 노트 6,333개, AI 에이전트에 CLI 붙였더니 진짜 달라진 것들

여러분, 옵시디언 쓰시는 분들 이거 경험 있죠?

노트를 옮기면 [[링크]]가 깨지는 거.

저는 옵시디언에 6,333개 노트를 PARA 방식으로 쌓아두고 있어요. 매일 아침 AI 에이전트한테 “굿모닝” 하면 시장 브리핑이 나오고, “인박스 정리해줘” 하면 자동으로 파일을 분류해주는 시스템을 만들어서 쓰고 있거든요.

근데 한 가지 꽤 오래된 문제가 있었어요.

AI가 파일을 이동하면, 옵시디언 내부 링크가 깨진다는 거.

mv 명령으로 노트를 Areas에서 Archive로 옮기면, 그 노트를 [[참조]]하던 다른 노트들이 전부 빨간 링크로 바뀌어요. 6,000개 노트 중에 어디서 깨졌는지 찾는 것도 일이죠.

그러다가 2026년 2월, Obsidian이 공식 CLI를 발표했어요. 그 뉴스를 보는 순간 “이거다” 싶었습니다.

제가 만든 시스템이 뭔지 먼저 설명할게요

뜬금없이 CLI 얘기만 하면 이해가 안 될 수 있으니, 제 옵시디언 구조를 간단히 소개합니다.

PARA 방식 볼트 구조

📥 0.inbox (3개)        ← 새로 들어온 것
📌 1.Projects (209개)   ← 진행 중인 프로젝트
🛠 2.Areas (4,075개)    ← 꾸준히 관리하는 영역
📚 3.Resources (1,201개) ← 참고 자료
🗃 4.Archive (835개)     ← 끝난 것들

총 6,333개 노트입니다. 블로그 글감, 트레이딩 일지, 개발 노트, 투자 분석 등이 다 여기 있어요.

AI 에이전트 + 스킬 시스템

이 볼트를 관리하는 AI 시스템을 Claude 기반으로 만들었어요. 현재 가동 중인 건:

구분	이름	하는 일
에이전트	`morning-briefing`	“굿모닝” → 시장 + 뉴스 + 블로그 현황 브리핑
에이전트	`blog-pipeline`	“글 써줘” → 키워드 분석부터 SNS 포스트까지 원클릭
스킬	`inbox-organizer`	인박스 파일을 PARA 규칙에 맞게 자동 분류
스킬	`url-summarizer`	URL 넣으면 요약해서 인박스에 저장
스킬	`blog-idea-manager`	글감 백로그 관리 (중복 탐지, 우선순위)

스킬이 27개, 에이전트가 10개. 솔직히 좀 많죠. 근데 다 쓰고 있어요.

문제는 이 친구들이 파일을 직접 읽고 쓰는 방식이라는 거였어요.

뭐가 문제였는지 — 파일 시스템 직접 조작의 한계

AI 에이전트가 옵시디언 노트를 다루는 기존 방식은 이랬어요:

AI 에이전트 → Read/Write/Glob/Grep → .md 파일 직접 조작

마크다운 파일을 직접 읽고, 직접 쓰고, 직접 mv로 옮기는 거예요.

잘 되는 것들:

노트 내용 읽기 (Read) → 문제없음
새 노트 생성 (Write) → 문제없음
파일 검색 (Grep) → 느리지만 됨

안 되는 것들:

파일 이동 후 [[링크]] 업데이트 → 불가능
옵시디언 검색 인덱스 활용 → 불가능 (텍스트 grep만 가능)
옵시디언 앱에서 바로 열기 → 불가능

특히 inbox-organizer가 “인박스 정리해줘”로 파일 10개를 이동시키면, 나중에 보면 여기저기 [[깨진 링크]]가 빨간색으로 떠있는 거예요.

6,000개 파일에서 깨진 링크를 하나씩 찾아서 고치는 건… 솔직히 그 시간에 그냥 수동으로 정리하는 게 빠르죠.

“자동화했는데 뒷정리가 더 귀찮다” — 이게 제 시스템의 가장 큰 모순이었어요.

Obsidian CLI 소식을 보고 한 것

2026년 2월 11일, Obsidian이 공식 CLI를 발표했어요. 터미널에서 노트 생성, 검색, 태스크, 태그, 플러그인, 동기화까지 다 된다는 거예요.

근데 문제가 있었습니다.

공식 CLI는 Obsidian 1.12+ 얼리 액세스 + Catalyst 라이선스가 필요해요.

제 옵시디언은 1.11.7. 바로 못 써요.

그래서 다른 길을 찾았어요.

서드파티 CLI: obsidian-cli (Yakitrak)

Homebrew로 설치할 수 있는 Go 기반 CLI가 있더라고요. 핵심 기능:

obsidian-cli move "old/path" "new/path"  # 파일 이동 + 링크 자동 업데이트!
obsidian-cli list "0.inbox"               # 폴더 목록
obsidian-cli print "note"                 # 노트 내용 보기
obsidian-cli frontmatter "note" --print   # 프론트매터 조회/수정
obsidian-cli daily                        # 데일리 노트 열기

move 명령이 링크를 자동으로 업데이트한다. 이게 핵심이에요.

설치는 터미널에서 두 줄이면 끝:

brew tap yakitrak/yakitrak
brew install yakitrak/yakitrak/obsidian-cli

설치하고 기본 볼트 연결:

obsidian-cli set-default "내볼트이름"
# → Default vault set to: 내볼트이름
# → Default vault path set to: /Users/.../내볼트

여기까지 3분.

헬퍼 스크립트 — AI 에이전트가 CLI를 쓰게 만들기

CLI를 설치했다고 AI 에이전트가 바로 쓸 수 있는 건 아니에요.

에이전트/스킬이 Shell 명령으로 호출할 수 있는 래퍼 스크립트를 만들었어요. 이름은 obsidian-helper.sh.

10가지 명령어

# 1. 파일 안전 이동 (핵심!)
obsidian-helper.sh safe-move "0.inbox/노트" "2.Areas/blog/노트"
# → obsidian-cli move 실행 → [[링크]] 자동 업데이트
# → 실패 시 mv로 폴백 + 경고 메시지

# 2. 패턴 매칭 일괄 이동
obsidian-helper.sh batch-move "0.inbox" "3.Resources/기술" "[요약]*"
# → [요약]으로 시작하는 모든 파일을 한번에 이동

# 3. 백링크 검색 (이 노트를 참조하는 모든 노트 찾기)
obsidian-helper.sh find-backlinks "투자 원칙"
# → 🔗 Backlinks for: 투자 원칙
# →   ← Areas/finance/배당전략.md
# →   ← Areas/blog/투자원칙정리.md
# → 📊 Total: 5 files

# 4. 인박스 현황
obsidian-helper.sh list-inbox
# → 📥 3 files | 🟢 Inbox is healthy

# 5. 볼트 통계 (PARA 균형도까지)
obsidian-helper.sh vault-stats
# → Total: 6,333 | Areas: 64% (과밀!) | Resources: 19%

# 6. 옵시디언 앱에서 열기
obsidian-helper.sh open-note "path/to/note"

# 7. 데일리 노트 열기
obsidian-helper.sh open-daily

# 8. 빠른 노트 생성
obsidian-helper.sh quick-note "제목" "내용"

# 9. 프론트매터 수정
obsidian-helper.sh update-fm "path/note" "status" "done"

# 10. 고아 노트 탐지
obsidian-helper.sh orphan-notes "0.inbox"

이 스크립트 하나가 모든 스킬과 에이전트의 옵시디언 접점이 되는 거예요. 나중에 공식 CLI가 나오면 이 스크립트만 수정하면 전체가 전환되는 구조.

Before vs After — 실제로 뭐가 달라졌나

1. 인박스 정리 (inbox-organizer)

Before:

"인박스 정리해줘"
→ AI가 파일 10개를 mv로 이동
→ 이동 완료! ...근데 깨진 링크 3개 발생
→ 수동으로 링크 수정 (15분)

After:

"인박스 정리해줘"
→ AI가 safe-move로 이동
→ obsidian-cli가 [[링크]] 자동 업데이트
→ 깨진 링크 0개. 끝.

절약 시간: 파일 이동 건당 약 5~15분. 주간 정리 때 10~30개 파일을 옮기니까, 주당 1~2시간 절약.

2. 모닝 브리핑 (morning-briefing)

Before:

"굿모닝"
→ 브리핑 생성 → 파일 저장
→ 보려면 직접 옵시디언 열고 폴더 찾아가기

After:

"굿모닝"
→ 브리핑 생성 → 파일 저장
→ obsidian-helper.sh open-note → 옵시디언 앱에서 바로 열림
→ + list-inbox로 인박스 현황도 한줄로 확인

사소하지만 매일 반복되는 10초의 불편함이 사라졌어요.

3. 볼트 분석 (–analyze 모드)

Before:

"볼트 체크해줘"
→ rg(ripgrep)으로 6,333개 파일 전체 검색
→ iCloud 볼륨이라 15초+ 소요 (타임아웃 발생)
→ 분석 실패하거나 부정확

After:

"볼트 체크해줘"
→ PARA 폴더별 타겟 검색 (iCloud 최적화)
→ 0.3초만에 백링크 검색 완료
→ vault-stats로 PARA 균형도 즉시 확인

검색 속도: 15초+ → 0.3초. 약 50배 빨라졌어요.

물론 이건 CLI 자체의 성능이라기보다, iCloud 볼륨에서 전체 검색 대신 PARA 폴더별 타겟 검색으로 최적화한 효과가 큽니다. 팁으로 알아두세요 — iCloud에 옵시디언 볼트 두신 분들, 전체 검색은 피하세요.

수치로 정리하면

항목	Before	After	개선
파일 이동 시 링크 깨짐	발생	0건	100% 해결
백링크 검색 속도	15초+	0.3초	50배 향상
인박스 정리 후 수동 보정	15분/회	0분	완전 자동
볼트 통계 확인	수동 계산	즉시 (vault-stats)	새 기능
브리핑 후 앱 열기	수동	자동 (open-note)	새 기능

초보자를 위한 활용 가이드 — 당장 따라할 수 있는 것

“나는 AI 에이전트 시스템 같은 거 없는데…” 하시는 분들도 CLI만으로 충분히 쓸모 있어요.

STEP 1: 설치 (2분)

# Mac/Linux
brew tap yakitrak/yakitrak
brew install yakitrak/yakitrak/obsidian-cli

# 볼트 연결
obsidian-cli set-default "내볼트이름"

볼트 이름을 모르겠으면, 옵시디언 앱 왼쪽 하단에 있어요. 또는 ~/Library/Application Support/obsidian/obsidian.json 파일을 열면 경로가 나옵니다.

STEP 2: 바로 쓸 수 있는 명령어 5개

1) 폴더 목록 보기

obsidian-cli list "0.inbox"
# → 인박스에 뭐가 있는지 터미널에서 확인

2) 노트 내용 보기

obsidian-cli print "0.inbox/오늘메모"
# → cat 대신 이걸 쓰면 볼트 기준으로 검색

3) 파일 이동 (링크 보존!)

obsidian-cli move "0.inbox/AI정리" "Resources/기술/AI정리"
# → 이동하면서 [[AI정리]]를 참조하던 모든 노트의 링크가 자동 수정됨

이게 가장 중요한 명령어예요. mv 대신 이걸 쓰세요. 진짜로.

4) 프론트매터 확인/수정

obsidian-cli frontmatter "내노트" --print
# → YAML 프론트매터 내용 출력

obsidian-cli frontmatter "내노트" --edit --key "status" --value "done"
# → status 값을 done으로 변경

5) 데일리 노트 열기

obsidian-cli daily
# → 오늘의 데일리 노트를 옵시디언 앱에서 열어줌

STEP 3: 쉘 alias로 단축키 만들기

~/.zshrc에 추가하면 매일 쓰기 편해요:

# 인박스 확인
alias obi="obsidian-cli list 0.inbox"

# 데일리 노트 열기
alias obd="obsidian-cli daily"

# 노트 이동 (링크 보존)
alias obm="obsidian-cli move"

# 프론트매터 보기
alias obf="obsidian-cli frontmatter"

이제 터미널에서 obi만 치면 인박스가 나오고, obd만 치면 데일리 노트가 열려요.

STEP 4: 자동화 스크립트 (중급)

매주 일요일에 인박스를 자동 정리하는 스크립트 예시:

#!/bin/bash
# weekly-cleanup.sh — 매주 일요일 실행

echo "📥 인박스 현황:"
obsidian-cli list "0.inbox"

echo ""
echo "📊 볼트 통계:"
# PARA 폴더별 파일 수 세기
for folder in "0.inbox" "1.Projects" "2.Areas" "3.Resources" "4.Archive"; do
  count=$(obsidian-cli list "$folder" 2>/dev/null | wc -l | tr -d ' ')
  echo "  $folder: ${count}개"
done

crontab -e에 이렇게 등록하면 매주 자동 실행:

0 20 * * 0 /path/to/weekly-cleanup.sh >> ~/obsidian-cleanup.log 2>&1

솔직한 마음 — 한계도 있어요

서드파티 CLI의 한계

obsidian-cli(Yakitrak)는 오픈소스 커뮤니티 도구예요. 옵시디언 공식 검색 인덱스나 그래프 데이터에는 접근 못 해요. 할 수 있는 건:

파일 이동 + 링크 업데이트 (정규식 기반)
폴더 목록, 노트 읽기
프론트매터 수정
데일리 노트 열기

할 수 없는 건:

옵시디언 검색 인덱스 쿼리 (전문 검색)
태스크 관리 (체크박스 네이티브 조작)
플러그인 제어 (Dataview 갱신 등)
동기화 트리거

공식 CLI(1.12+)가 나오면 이것들이 전부 가능해져요. 그래서 헬퍼 스크립트를 중간 레이어로 만든 거예요. 공식 CLI로 갈아끼우면 스킬/에이전트 코드는 하나도 안 건드려도 됩니다.

iCloud 볼트의 속도 문제

옵시디언 볼트를 iCloud에 두고 쓰시는 분들, 전체 검색이 느릴 수 있어요. 6,000개 파일 기준으로:

전체 볼트 rg 검색: 15초+ (타임아웃)
특정 폴더 타겟 검색: 0.3초

해결법: PARA 폴더별로 나눠서 검색하세요. 저도 이걸로 해결했어요.

앞으로 내가 할 것들

단기 (이번 주)

url-summarizer 스킬에 quick-note 연동 — URL 요약이 인박스에 CLI로 바로 생성
blog-idea-manager에 update-fm 연동 — 글감 상태를 프론트매터로 관리 (status: idea → writing → done)

중기 (공식 CLI 출시 시)

Obsidian 1.12 설치 후 공식 CLI 전환
obsidian search 연동 — 인덱스 기반 검색으로 볼트 분석 속도 한 단계 더 향상
obsidian tasks 연동 — 태스크 관리 자동화
obsidian sync 연동 — 배치 작업 후 동기화 트리거

장기

모든 스킬/에이전트의 파일 조작을 CLI 레이어를 통해서만 하도록 표준화
볼트 건강도 자동 모니터링 (깨진 링크 0개 유지)

마무리 — 도구를 더 추가하지 말고, 있는 도구를 연결하라

저번 시스템 리포트에서 적었던 교훈이 있어요.

“도구를 더 추가하지 말고, 있는 도구를 연결하라.”

이번에 한 건 딱 그거예요. 옵시디언은 원래 있었고, AI 에이전트도 원래 있었고, CLI라는 다리를 하나 놓은 것뿐이에요.

그런데 그 다리 하나가 “자동화했는데 뒷정리가 더 귀찮다”는 모순을 해결해줬어요.

옵시디언 쓰시는 분들, 특히 노트가 1,000개 넘어가시는 분들. CLI 한번 써보세요. obsidian-cli move 하나만으로도 삶의 질이 달라집니다.

진짜로요.