Obsidian CLI 사용법: 터미널에서 내 볼트를 다루는 법

터미널에서 살다시피 하는 개발자라면 한 번쯤 생각해봤을 거예요. “Obsidian 볼트를 커맨드라인에서 다룰 수 없을까?”

노트를 쓰려면 매번 Obsidian 앱으로 전환해야 하고, 자동화하고 싶어도 마땅한 방법이 없었으니까요. 커뮤니티 도구가 이 빈자리를 채워왔지만 2026년 2월 Obsidian 1.12 버전에서 공식 CLI가 등장했습니다. “Obsidian에서 할 수 있는 건 뭐든 커맨드라인으로도 할 수 있다”는 기치를 내세우며요.

이 글에서는 Obsidian CLI의 설치부터 자주 쓰는 명령어와 셸 스크립트 자동화, AI 에이전트 연동까지 훑어보겠습니다.

어떻게 동작하나요?

시작하기 전에 하나 알아둘 점이 있어요. Obsidian CLI는 독립적인 헤드리스 도구가 아닙니다. Obsidian 데스크톱 앱에 대한 일종의 리모컨이에요.

CLI가 명령을 보내면 실행 중인 Obsidian 앱이 처리하고 결과를 돌려주는 구조입니다. 앱이 꺼져 있으면 첫 명령 실행 시 자동으로 Obsidian을 띄워주니까 직접 켤 필요는 없어요. 다만 완전히 앱 없이 동작하는 도구는 아니라는 걸 기억해두세요.

설치하기

CLI는 Obsidian 1.12부터 내장되어 있어서 따로 패키지를 설치할 필요가 없습니다. 앱 안에서 활성화만 하면 돼요.

Obsidian을 1.12 이상으로 업데이트합니다
Settings → General → Command line interface로 이동합니다
“Command line interface” 토글을 켭니다
“Register CLI”를 클릭하고 안내를 따릅니다
터미널을 재시작합니다

등록이 완료되면 시스템 PATH에 obsidian 명령이 추가됩니다. 운영체제별로 위치가 다릅니다. macOS에서는 /usr/local/bin/obsidian에 심볼릭 링크가 생기고(관리자 권한 필요) Linux에서는 ~/.local/bin/obsidian에 바이너리가 복사돼요. Windows는 Obsidian.exe와 함께 터미널 리다이렉터인 Obsidian.com이 설치됩니다.

잘 등록됐는지 확인해볼게요.

$ obsidian --version

버전 번호가 출력되면 준비 완료입니다.

명령어 기본 문법

Obsidian CLI의 문법은 보통 CLI 도구와 좀 다릅니다. --key value 대신 key=value 형태로 파라미터를 쓰고 플래그도 대부분 단어 그대로 적어요.

$ obsidian <명령> [파라미터...] [플래그...]

볼트가 여러 개라면 vault 파라미터로 대상을 지정합니다. 볼트가 하나뿐이면 생략해도 괜찮아요.

$ obsidian daily vault="내 볼트"

처음엔 낯설 수 있는데 타이핑할 양이 적어서 금방 익숙해져요.

데일리 노트

아마 가장 자주 쓰게 될 명령은 daily일 거예요. 오늘의 데일리 노트를 열어줍니다.

$ obsidian daily

노트가 아직 없으면 템플릿에 맞춰 자동으로 만들어줘요. 여기까지는 앱에서 하는 것과 크게 다르지 않죠.

진짜 편한 건 daily:append입니다. 터미널을 떠나지 않고 데일리 노트에 내용을 추가할 수 있거든요.

$ obsidian daily:append content="- [ ] PR 리뷰하기"
$ obsidian daily:append content="- [x] 오전 스탠드업 참석"

코딩하다가 갑자기 할 일이 생각나면 터미널에서 바로 쏴주면 됩니다. 앱으로 전환하고 데일리 노트 찾고 스크롤 내리고… 이런 과정이 사라져요.

볼트 검색하기

볼트에 노트가 수백 개 쌓이면 검색은 필수겠죠. search 명령으로 전체 볼트를 쿼리할 수 있습니다.

$ obsidian search query="React 상태 관리"

Obsidian 앱 내부의 검색 엔진을 그대로 사용하기 때문에 앱에서 검색하는 것과 결과가 동일합니다. path 파라미터를 추가하면 특정 폴더로 범위를 좁힐 수 있어요.

$ obsidian search query="useEffect" path="TIL"

파일 조회와 읽기

최근에 수정한 파일 5개를 확인하고 싶다면 files 명령을 쓰면 됩니다.

$ obsidian files sort=modified limit=5

특정 노트의 내용을 터미널에서 바로 읽을 수도 있어요.

$ obsidian read path="프로젝트/회의록/2026-04-17"

--copy 플래그를 붙이면 결과가 클립보드에 복사됩니다. 노트 내용을 다른 곳에 붙여넣어야 할 때 유용해요.

$ obsidian read path="스니펫/Docker Compose 템플릿" --copy

참고로 --copy는 CLI에서 몇 안 되는 -- 접두어 플래그예요. 나머지 대부분은 key=value 형태라는 점 다시 한번 기억해두세요.

태스크 관리

볼트 전체에 흩어져 있는 체크리스트 항목을 한 번에 모아볼 수 있습니다.

$ obsidian tasks

데일리 노트의 태스크만 보고 싶으면 daily를 붙이면 돼요.

$ obsidian tasks daily

여러 노트에 체크리스트를 분산해놓는 스타일이라면 이 명령이 꽤 쓸모 있을 거예요. “오늘 뭘 해야 하지?”를 터미널 한 줄로 확인할 수 있으니까요.

태그 분석

볼트의 태그 사용 빈도를 확인하는 것도 간단합니다.

$ obsidian tags counts

어떤 태그를 많이 쓰고 있는지, 정리해야 할 태그는 없는지 파악할 때 좋아요. 노트가 수천 개 넘어가면 태그 체계가 슬슬 복잡해지는데 이 명령으로 주기적으로 점검할 수 있습니다.

JSON 출력과 파이프라인

CLI의 진짜 힘은 다른 도구와 조합할 때 나옵니다. format=json 파라미터를 붙이면 결과를 JSON으로 받을 수 있어요.

$ obsidian files sort=modified limit=3 format=json

JSON 출력이 가능하니 jq로 필터링하거나 다른 스크립트에 파이프로 넘기는 게 자연스럽습니다.

$ obsidian search query="TODO" format=json | jq '.[].path'

끊어져 있는 링크를 찾는 unresolved 명령도 있어요.

$ obsidian unresolved

[[존재하지 않는 노트]]처럼 아직 만들지 않은 노트를 가리키는 링크를 찾아줍니다. 볼트 정리할 때 활용하면 좋겠죠.

셸 스크립트로 자동화하기

CLI가 생기면서 그동안 어려웠던 자동화가 쉬워졌어요. 몇 가지 실용적인 예시를 살펴볼게요.

매일 아침 데일리 노트에 오늘의 루틴을 채워주는 스크립트입니다.

morning-routine.sh

#!/bin/bash

obsidian daily:append content="## 🌅 오늘의 루틴"
obsidian daily:append content="- [ ] 어제 미완료 태스크 확인"
obsidian daily:append content="- [ ] 오전 코드 리뷰"
obsidian daily:append content="- [ ] TIL 작성"

이걸 cron에 걸어두면 매일 같은 시간에 자동으로 데일리 노트가 채워집니다.

$ crontab -e

crontab

0 8 * * 1-5 /path/to/morning-routine.sh

주간 요약 노트를 자동으로 만드는 것도 가능해요.

weekly-summary.sh

#!/bin/bash

WEEK=$(date +%Y-W%V)
obsidian create path="주간 요약/${WEEK}" \
  content="# ${WEEK} 주간 요약\n\n## 이번 주 완료한 태스크\n\n## 다음 주 계획"

앱 화면 없이 순수하게 셸 스크립트만으로 볼트를 조작할 수 있다는 게 핵심입니다.

AI 에이전트와 연동하기

Obsidian CLI가 특히 주목받는 이유 중 하나는 AI 에이전트에게 볼트 접근 권한을 줄 수 있다는 점이에요.

AI를 위한 CLI 설계에서 다뤘듯이 잘 만들어진 CLI는 AI 에이전트의 도구로 쓰기에 안성맞춤입니다. Obsidian CLI도 마찬가지예요. format=json으로 구조화된 출력을 받을 수 있고 명령어 체계가 일관적이라 에이전트가 파악하기 쉽습니다.

예를 들어 코딩 에이전트에게 Obsidian 볼트의 기술 노트를 참고하게 할 수 있어요.

$ obsidian search query="React 서버 컴포넌트" format=json
$ obsidian read path="TIL/2026-03-15"

에이전트가 이 명령을 실행해서 과거에 정리한 노트를 읽고 그 맥락을 바탕으로 더 정확한 답변을 만들어내는 식이죠. 개인 지식 베이스가 AI의 컨텍스트로 연결되는 거예요.

MCP(Model Context Protocol) 서버를 만들어서 Obsidian CLI를 도구로 등록하면 더 체계적인 연동도 가능합니다. 실제로 커뮤니티에서 이미 이런 통합을 시도하고 있어요.

TUI 모드

원격 서버에서 SSH로 접속해서 작업하는 경우도 있잖아요. GUI 없이도 Obsidian을 쓸 수 있으면 좋겠다 싶을 때 TUI(Terminal User Interface) 모드가 도움이 됩니다.

TUI 모드를 실행하면 터미널 안에서 인터랙티브한 인터페이스가 열리고 명령어 자동 완성도 지원해요. 명령어가 잘 기억나지 않을 때 탭 키로 후보를 확인하면서 사용할 수 있어서 처음 익힐 때도 유용합니다.

Headless Sync

서버 환경에서 Obsidian Sync를 돌려야 하는 경우도 있어요. 예를 들어 NAS에 볼트를 동기화해두거나 CI 파이프라인에서 볼트 내용을 참조해야 할 때요.

Headless Sync는 GUI 없이 Obsidian Sync만 실행하는 기능입니다. 엔드투엔드 암호화가 그대로 적용되고 동기화 속도도 빠릅니다. Obsidian Sync 구독이 필요하긴 하지만 서버에서 볼트를 최신 상태로 유지하고 싶다면 괜찮은 선택이에요.

플러그인 개발 워크플로우

Obsidian 플러그인이나 테마를 만드는 개발자에게도 CLI는 꽤 편리합니다.

코드를 수정하고 Obsidian에서 플러그인을 리로드하려면 원래 앱 안에서 “Reload app without saving” 같은 명령을 실행해야 했거든요. CLI가 있으면 에디터에서 코드를 고친 뒤 터미널에서 바로 리로드할 수 있습니다.

JavaScript를 실행하거나 스크린샷을 캡처하는 명령도 있어서 플러그인 테스트 자동화가 훨씬 수월해졌어요. Chrome DevTools Protocol을 통한 디버깅까지 지원하니까 개발 워크플로우가 한결 매끄러워집니다.

마치며

Obsidian CLI는 그동안 앱 화면에 갇혀 있던 볼트를 터미널 세계로 꺼내주는 도구입니다. 데일리 노트에 할 일을 추가하고 볼트를 검색하고 태스크를 확인하는 작업을 키보드에서 손을 떼지 않고 할 수 있게 되었어요.

JSON 출력이나 셸 스크립트 연동, AI 에이전트 통합까지 가능해지면서 Obsidian의 활용 범위가 크게 넓어졌습니다. “노트 앱”이라는 틀을 넘어서 개발 워크플로우에 자연스럽게 녹아들 수 있는 셈이죠.

Obsidian 자체에 아직 익숙하지 않다면 먼저 기본적인 볼트 구성과 양방향 링크부터 시작해보세요. 그다음에 CLI를 얹으면 터미널과 노트 앱 사이를 자유롭게 오가는 워크플로우를 구축할 수 있을 거예요.

공식 문서는 Obsidian CLI Help에서 확인할 수 있습니다.

This work is licensed under CC BY 4.0