Obsidian CLI를 사용하면 터미널에서 노트를 열고, 만들고, 검색하고, 자동화할 수 있습니다. Obsidian 1.12부터 공식 지원을 시작한 이 기능을 활용하면 마우스 없이 키보드만으로 vault를 제어하고, 쉘 스크립트와 결합해 반복 작업을 완전 자동화할 수 있습니다.
이 글에서는 설치 방법부터 실전 명령어, 자동화 스크립트, 트러블슈팅까지 한 번에 정리합니다.
이 글의 대상 독자
- 터미널을 일상적으로 사용하는 개발자
- Obsidian 워크플로우를 자동화하고 싶은 분
- Obsidian 1.12 이상 + Catalyst 라이선스 보유자
- claude code, gemini cli 등 AI 코딩 에이전트 사용자
이 글은 macOS 기준으로 작성되었습니다. Windows/Linux는 설치 경로 및 쉘 설정이 다를 수 있습니다.
Obsidian CLI란?
Obsidian CLI는 Obsidian 1.12 버전부터 추가된 공식 명령줄 인터페이스(Command Line Interface)입니다. 터미널에서 obsidian 명령어 하나로 vault의 노트를 읽고, 생성하고, 검색하는 등 Obsidian의 핵심 기능을 직접 제어할 수 있습니다.
CLI로 할 수 있는 작업은 다음과 같습니다.
- 터미널에서 노트 열기, 생성, 검색, 삭제
- 데일리 노트에 즉시 내용 추가
- 태그, 백링크, 속성 조회
- 플러그인 관리
- 쉘 스크립트와 결합한 워크플로우 자동화
Early Access 기능
Obsidian CLI는 현재 얼리 액세스 단계입니다. 사용하려면 Obsidian 1.12 이상과 Catalyst 라이선스(최소 $25 일회성 결제)가 필요합니다. 향후 일반 사용자에게도 공개될 가능성이 있으나, 공식적으로 확인된 일정은 없습니다.
앱 실행 상태
Obsidian CLI는 Obsidian 앱이 실행 중일 때만 동작합니다. 앱이 꺼진 상태라면 첫 명령어 실행 시 Obsidian이 자동으로 시작됩니다.
명령어 카테고리 한눈에 보기
Obsidian CLI는 다양한 명령어를 제공합니다. 크게 아래와 같이 분류됩니다.
- 파일 관리:
filescreateopenreadmovedelete - 데일리 노트:
dailydaily:appenddaily:prependdaily:read - 검색:
searchsearch:open - 메타데이터:
tagspropertiesproperty:set - 콘텐츠:
appendprependtasks - 플러그인 / 테마:
pluginsplugin:enableplugin:disable
설치 방법
1단계: CLI 활성화
- Obsidian을 실행합니다
- 설정 → 일반 으로 이동합니다
- 하단의 명령줄 인터페이스 토글을 켭니다
- 안내에 따라 CLI를 등록합니다
Windows 사용자 추가 단계
Windows에서는 토글 활성화 후 Discord #insider-desktop-release 채널에서 Obsidian.com 파일을 별도로 받아 Obsidian.exe와 같은 폴더에 넣어야 합니다. 자세한 내용은 공식 문서를 참고하세요.
2단계: 설치 확인
터미널을 열고 아래 명령어를 입력합니다.
obsidian version
Obsidian 버전 번호가 출력되면 정상 설치된 것입니다.
기본 사용법
명령어 형식
obsidian <명령어> [옵션]
여러 vault를 사용한다면 vault=<이름> 옵션으로 대상 vault를 지정합니다.
obsidian vault=Notes files
전체 명령어 목록은 obsidian help로 확인합니다.
TUI (인터랙티브) 모드
obsidian만 입력하면 TUI(Terminal User Interface) 모드로 진입합니다. 이후 obsidian 접두어 없이 명령어를 바로 입력할 수 있습니다.
# TUI 모드 진입 obsidian # TUI 내에서 명령어 입력 (접두어 불필요) help daily search query="회의록"
| 단축키 | 기능 |
|---|---|
Tab | 명령어/파라미터 자동완성 |
↑ / ↓ | 이전 명령어 탐색 |
Ctrl+R | 히스토리 역검색 |
Ctrl+C / Ctrl+D | 종료 |
--copy 플래그
모든 명령어에 --copy를 붙이면 결과가 클립보드에 복사됩니다.
# 현재 파일 내용을 클립보드에 복사 obsidian read --copy # 검색 결과를 클립보드에 복사 obsidian search query="TODO" --copy
실전 명령어 예시
1. 노트 열기 & 읽기
# 파일 이름으로 노트 열기 obsidian open file="회의록" # 경로로 직접 열기 obsidian open path="10 Inbox/아이디어.md" # 터미널에서 노트 내용 읽기 obsidian read file="회의록"
2. 노트 생성
# 빈 노트 생성 obsidian create name="새 프로젝트 계획" # 내용과 함께 생성 obsidian create name="메모" content="오늘 할 일 정리" # 템플릿을 사용해서 생성 obsidian create name="주간 회고" template="Weekly Review" # 특정 폴더에 생성 obsidian create path="10 Inbox/아이디어.md"
3. 데일리 노트 활용
터미널 작업 중 데일리 노트에 바로 메모를 추가할 수 있어, 컨텍스트 스위칭 없이 기록이 가능합니다.
# 오늘의 데일리 노트 열기 (없으면 자동 생성) obsidian daily # 데일리 노트에 내용 추가 (기본: 파일을 열음) obsidian daily:append content="- 16:00 팀 미팅 완료" # 추가하되 파일은 열지 않기 (silent 플래그) obsidian daily:append content="- 아이디어 메모" silent # 데일리 노트 맨 앞에 추가 obsidian daily:prepend content="## 오늘의 목표" # 데일리 노트 내용 읽기 obsidian daily:read # 오늘 데일리 노트의 경로만 출력 (파일을 열지 않음) obsidian daily:path
쉘 함수 등록으로 더 빠르게
# ~/.zshrc에 추가
function memo() { obsidian daily:append content="$*"; }
이후 memo - 아이디어 떠오름 처럼 사용할 수 있습니다. alias 대신 함수로 정의하면 공백이 포함된 인수도 안정적으로 처리됩니다.
4. 검색
# vault 전체에서 텍스트 검색 obsidian search query="API 키 설정" # 특정 폴더 내에서 검색 obsidian search query="Docker" path="01 Dev" # 결과 수 제한 obsidian search query="n8n" limit=5 # 검색 결과와 주변 문맥(컨텍스트) 함께 보기 obsidian search query="API 키 설정" matches
5. 태그 & 속성 조회
# 현재 파일의 태그 목록 obsidian tags # vault의 모든 태그 목록 obsidian tags all # 사용 횟수 기준 정렬 obsidian tags all counts sort=count # 특정 파일의 속성(프론트매터) 조회 obsidian properties file="프로젝트 A" # 속성값 설정 obsidian property:set name="done" value="true" file="할 일"
6. 할 일(Task) 관리
# vault 전체의 미완료 할 일 목록 obsidian tasks all todo # 데일리 노트의 할 일만 보기 obsidian tasks daily # 특정 할 일 완료 처리 obsidian task file="할 일 목록" line=5 done
7. 파일 관리
# vault의 파일 목록 obsidian files # 특정 폴더의 파일 수 확인 obsidian files folder="10 Inbox" total # 파일 이름 변경 obsidian move file="임시 메모" to="정리된 메모.md" # 파일 이동 obsidian move file="임시 메모" to="01 Dev/임시 메모.md" # 파일을 휴지통으로 이동 (기본값) obsidian delete file="더이상 필요없는 노트" # 영구 삭제 (복구 불가) obsidian delete file="더이상 필요없는 노트" permanent
8. 플러그인 관리
# 설치된 플러그인 목록 obsidian plugins # 활성화된 커뮤니티 플러그인만 보기 obsidian plugins:enabled filter=community # 플러그인 활성화/비활성화 obsidian plugin:enable id=dataview obsidian plugin:disable id=calendar
자동화 스크립트 예시
CLI의 가장 큰 가치는 쉘 스크립트와의 결합입니다. 아래는 바로 적용 가능한 실전 예시입니다.
매일 아침 실행하는 셋업 스크립트
#!/bin/bash # morning.sh - 매일 아침 실행 # 데일리 노트 열기 obsidian daily # 어제 미완료 할 일 확인 echo "📋 미완료 할 일:" obsidian tasks all todo
Git 커밋 메시지를 데일리 노트에 자동 기록
커밋할 때마다 데일리 노트에 기록을 남기는 예시입니다.
#!/bin/bash
# .git/hooks/post-commit 에 저장하고 실행 권한 부여
LAST_COMMIT=$(git log -1 --pretty=format:"%s")
obsidian daily:append content="- 🔨 커밋: ${LAST_COMMIT}"
트러블슈팅
한글(CJK) 내용 입력 시 CLI가 멈추는 문제 (v1.12.2에서 수정됨)
버그 수정 완료 (v1.12.2)
이 버그는 v1.12.2에서 수정되었습니다. create, append, prepend, daily:append 등 content 파라미터를 사용하는 모든 명령어에서 한글 입력이 정상 동작합니다.
이전에는 content 파라미터에 한글, 중국어, 일본어 등 멀티바이트 문자를 넣으면 CLI가 무한 대기 상태에 빠지는 버그가 있었습니다. (공식 포럼 스레드)
# v1.12.2 이후 모두 정상 동작 obsidian create path="Test.md" content="안녕하세요" obsidian append path="메모.md" content="한글 내용 추가" obsidian prepend path="메모.md" content="맨 앞에 추가" obsidian daily:append content="오늘의 메모"
Obsidian Terminal 플러그인에서 command not found 발생
iTerm2나 Terminal.app에서는 obsidian 명령어가 잘 동작하는데, Obsidian Terminal 플러그인 내 터미널에서는 command not found가 발생할 수 있습니다.
원인: CLI 설치 시 PATH가 ~/.zprofile에만 추가되기 때문입니다.
| 설정 파일 | Login Shell | Non-Login Shell |
|---|---|---|
~/.zprofile | O | X |
~/.zshrc | O | O |
Obsidian Terminal 플러그인은 non-login shell로 실행되므로 ~/.zprofile을 읽지 않습니다.
해결 방법: ~/.zshrc에 PATH를 추가합니다.
echo 'export PATH="$PATH:/Applications/Obsidian.app/Contents/MacOS"' >> ~/.zshrc
변경 후 터미널을 새로 열고 확인합니다.
which obsidian # /Applications/Obsidian.app/Contents/MacOS/obsidian 이 출력되면 정상
AI 에이전트와 함께 사용하기
Obsidian CEO kepano가 만든 obsidian-skills 저장소를 활용하면, Claude Code 등 AI 에이전트가 Obsidian CLI를 이해하고 자율적으로 활용할 수 있습니다.
obsidian-cli 스킬을 설치하면, Claude Code에게 자연어로 지시하는 것만으로 적절한 CLI 명령어를 선택해 vault를 조작합니다.
설치 방법은 obsidian-skills 저장소를 참고하세요.
사용 예시
“오늘 데일리 노트에 회의 내용 추가해줘”
“프로젝트 관련 노트 전부 검색해서 목록 보여줘”
“새 노트 만들고 아이디어 정리해줘”
obsidian-skills에는 obsidian-cli 외에도 Obsidian Flavored Markdown 작성(obsidian-markdown), Bases 파일 편집(obsidian-bases), Canvas 파일 편집(json-canvas) 스킬도 포함되어 있습니다.
마무리
Obsidian CLI는 터미널 중심 워크플로우를 가진 사용자나 반복 작업을 자동화하고 싶은 개발자에게 유용한 기능입니다.
- 키보드 중심 워크플로우: 터미널에서 벗어나지 않고 노트 작성
- 자동화: 쉘 스크립트와 결합한 반복 작업 자동화
- 통합: 다른 CLI 도구들과의 파이프라인 연결
전체 명령어 목록은 obsidian help로 확인하거나, Obsidian 공식 CLI 문서를 참고하세요.
함께 보면 좋은 글
Obsidian 자동화, 워크플로우 설계, 플러그인 활용 사례 등은 아래 글들에서 계속 정리하고 있습니다.
- Obsidian Cannoli 플러그인으로 여러 LLM 모델 쉽게 비교하는 방법 #1
- OpenAI Agent Builder와 n8n Instance-level MCP 연동 가이드
- Synology Nas에 Git Server와 Gitea 설치