SiYuan Note CLI 스킬
개요
SiYuan Note는 CLI(siyuan)를 통해 워크스페이스, 노트북, 문서, 블록 등을 관리할 수 있습니다.
바이너리가 PATH에 있어야 합니다(siyuan --version으로 확인).
CLI 버전: v3.8.9. 아래 표시된 명령어는 이 버전을 기준으로 합니다.
참고:
siyuan이PATH에 없으면SiYuan-Kernel을 대체 명령어 이름으로 시도하십시오.
워크플로우
모든 사용자 요청에 대해 다음 순서를 따릅니다:
1. 사용 가능한 워크스페이스 검색
siyuan workspace list를 실행하여 등록된 워크스페이스 목록을 가져옵니다(-w 플래그 불필요).
사용자가 특정 워크스페이스를 지정하지 않았다면 목록을 제시하고 선택하도록 요청하세요.
siyuan workspace list
siyuan workspace info # 현재 기본 워크스페이스 표시
2. 워크스페이스 경로 고정
사용자가 워크스페이스를 선택(또는 경로를 직접 제공)하면, 워크스페이스 경로를 저장하고 이후 모든 명령어(workspace 하위 명령어 제외)에 -w 인수로 사용합니다.
3. 요청된 명령어 실행
-w <워크스페이스-경로>를 추가하여 대상 명령어를 구성하고 실행합니다(workspace 하위 명령어 제외).
결과를 파싱할 때는 -f json을 사용하여 프로그램 출력을 활용하세요.
명령어가 실패하면 다음을 확인하십시오: (1) 워크스페이스 경로가 유효한지, (2) --id 같은 필수 플래그가 제공되었는지, (3) 설치된 CLI 버전에 하위 명령어가 존재하는지 확인합니다.
일반 패턴
블록/문서 ID 얻기
많은 명령어가 블록 또는 문서 ID(--id)를 필요로 합니다. ID는 다음을 통해 얻을 수 있습니다:
siyuan sql "SELECT id, content FROM blocks WHERE type='d'" -w <path> -f json— 문서 ID 목록siyuan document list --notebook <id> -w <path> -f json— 노트북 내 문서 목록siyuan search <keyword> -w <path> -f json— 검색 결과에서 ID 획득
파괴적 작업 — 확인, 미리보기, 승인
삭제/정리(remove, delete, clean, clear, purge), 롤백(history rollback, repo checkout, repo file rollback), 교체/덮어쓰기 작업(예: import data, 기존 파일 덮어쓰는 file write, --overwrite 템플릿 명령어)은 파괴적 작업으로 간주합니다.
- 읽기 전용 명령어로 워크스페이스, 대상 ID/경로, 영향 범위를 확인합니다. 하위 문서, 관련 데이터, 기존 콘텐츠도 영향을 받을지 확인하십시오. 명령어 이름만으로 범위를 추론하지 마십시오.
- 의도한 명령어를 먼저
--dry-run으로 실행하고 출력을 검사합니다:siyuan notebook remove --id <id> --dry-run -w <path>--dry-run을 생략하여 재시도하지 마십시오. - 사용자의 권한 또는 영향 범위가 불분명하거나, 미리보기가 요청 이상의 영향을 보여주는 경우 워크스페이스, 대상, 결과를 요약하고 명시적 승인을 요청하십시오. 대상을 추측하거나 조용히 범위를 확장하지 마십시오.
- 범위가 확인되고 승인되면, 파괴적 작업 실행 전에 대상 워크스페이스에 복구 스냅샷을 생성합니다:
siyuan repo create --memo "<파괴적 작업에 대한 간략 설명 전>" -w <path> - 확인된 효과가 사용자 요청 또는 명시적 승인과 일치할 때만
--dry-run없이 실행하며, 동일한 워크스페이스, 대상, 옵션을 유지합니다. 이 중 하나라도 변경되면 확인, 미리보기, 작업 전 스냅샷을 다시 수행하십시오.
JSON 출력 파싱
프로그램 파싱을 위해 -f json을 사용하세요. JSON 구조는 하위 명령어에 따라 다릅니다: workspace list는 배열을 반환하고, workspace info는 객체를 반환합니다. jq 같은 도구로 필터링하기 전에 명령어의 출력 구조를 확인하십시오. 모든 결과가 배열이라고 가정하지 마십시오.
워크스페이스 잠금 오류
명령어가 종료 코드 24와 함께 lock workspace [...] failed 오류를 보고하면, 해당 워크스페이스가 이미 다른 SiYuan 프로세스(예: 데스크톱 앱)에서 사용 중입니다. 다른 프로세스를 닫거나 다른 워크스페이스를 대상으로 지정하십시오.
쓰기 작업 후 스냅샷
대화 중 각 워크스페이스별로 실제 데이터 변경 사항을 별도로 추적하십시오. 실패한 명령어로 인한 부분 변경도 포함합니다. 스냅샷 생성 자체는 추가 스냅샷이 필요한 새로운 데이터 변경으로 간주되지 않습니다.
작업을 마치거나 세션을 종료하기 전에 변경 사항을 요약하고 수정된 각 워크스페이스에 대해 해당 워크스페이스 경로와 자체 변경 요약을 사용하여 데이터 스냅샷을 생성하십시오:
siyuan repo create --memo "<이 워크스페이스의 변경 사항 요약>" -w <수정된-워크스페이스-경로>
--memo는 생성/수정/삭제된 내용을 간결하게 설명해야 합니다(예: /Projects에 3개 문서 생성, README 업데이트, 오래된 노트 제거). 각 워크스페이스의 성공 여부를 확인하십시오. 스냅샷이 실패하면 저장되었다고 주장하지 말고 영향을 받은 워크스페이스와 오류를 보고하십시오. 데이터 변경이 없는 워크스페이스는 건너뛰십시오. 읽기 전용 세션은 스냅샷이 필요하지 않습니다.
이러한 스냅샷은 변경 후 상태를 보존합니다. 파괴적 작업에 필요한 작업 전 복구 스냅샷을 대체하지 않습니다.
도메인 개념
정확한 CLI 사용을 위해 다음 SiYuan 고유 개념을 이해하는 것이 필수적입니다:
블록 — 기본 단위
모든 것은 고유 ID를 가진 블록입니다. 문서는 루트 역할을 하는 문서 블록(타입 d, 즉 NodeDocument)입니다. 콘텐츠 블록(제목, 문단, 목록, 코드, 표)은 그 아래에 트리를 형성합니다.
컨테이너 블록(하위 블록을 가질 수 있음, --parent로 유효): document, blockquote, list, list-item, super-block, callout, tabs, tab-item
리프 블록(하위 블록을 가질 수 없음, --parent로 유효하지 않음): heading, paragraph, code-block, math-block, table, HTML-block, thematic-break, video, audio, widget, iframe, attribute-view, block-query-embed
tabs/tab-item은 탭 컨테이너를 위해 도입된 블록 타입입니다.search -t타입 필터 목록에tabs및tabItem으로 나타납니다.
제목 계층 구조 — --parent 대신 --previous 사용
제목(h1-h6)은 리프 블록입니다. UI에서 제목 "아래"에 나타나는 블록은 AST에서 그 다음 형제이며, 자식이 아닙니다. 제목 아래에 블록을 삽입하려면 제목의 ID(또는 현재 그 아래에 있는 마지막 블록의 ID)를 --parent가 아닌 --previous로 전달하십시오:
siyuan block insert --parent <docID> --previous <headingID> --data "text" -w <path>
중첩 목록 — list-item은 list-item을 직접 포함할 수 없음
list-item은 다른 list-item을 직접 포함할 수 없습니다. 목록을 중첩하려면 외부 list-item의 자식으로 목록(NodeList)을 생성한 다음, 내부 목록에 list-item을 추가하십시오. list-item의 부모는 항상 list여야 합니다.
hPath — 사람이 읽을 수 있는 경로
hPath는 문서 트리에 표시되는 제목 기반 경로입니다(예: /Diary/2024/June). 문서 이름을 바꾸면 ID는 변경되지 않지만 hPath는 변경됩니다.
document list및document move:--hpath는 제목 기반 경로를 받고,--path는 내부 ID 기반 경로(기본값:/)를 받습니다. 이 플래그는 서로 바꿔 사용할 수 없습니다.document create:--path는 부모 문서 경로(기본값:/)를 지정합니다. 이 명령어는--hpath를 제공하지 않습니다.list/move의 경로 플래그를 공유한다고 가정하지 말고 설치된 버전의siyuan document create --help를 확인하십시오.
block update — 추가가 아닌 교체
block update는 하나의 블록 전체 콘텐츠를 새 마크다운으로 교체합니다. 새 블록을 생성하거나 추가하지 않습니다. 기존 콘텐츠를 수정하면서 새 콘텐츠를 추가하려면 먼저 block update를 호출한 다음 별도 호출로 block append/prepend/insert를 호출하십시오. --lock-type을 전달하면 새 콘텐츠의 파싱된 블록 타입이 기존 블록 타입과 다를 때 업데이트를 거부합니다.
document move vs block move
document move는 전체 문서(모든 하위 포함)를 대상 노트북 및 부모 경로로 이동하며, 제목 기반 경로는 --hpath, 내부 경로는 --path를 사용합니다. block move는 단일 콘텐츠 블록을 새 부모 블록 아래로 재배치합니다.
데일리 노트 — dailynote vs document
데일리 노트는 노트북의 데일리 노트 저장 경로에 있는 특수 문서입니다. 일기/저널/데일리 노트 요청 시 document create 대신 dailynote create를 사용하여 오늘의 노트를 열고, dailynote append/prepend로 콘텐츠를 추가합니다.
노트북 아이콘 vs 문서 아이콘
attr set은 문서 블록의 아이콘을 변경합니다. 노트북의 아이콘은 설정할 수 없습니다. 노트북의 경우 notebook set-icon(특정 이모지) 또는 notebook random-icon(랜덤 이모지)을 사용합니다.
전역 플래그
이 플래그는 모든 하위 명령어에서 사용할 수 있습니다:
| 플래그 | 설명 |
|---|---|
-w, --workspace <path> | 워크스페이스 경로(workspace 명령어를 제외한 모든 명령어에 필수, serve의 경우 선택 사항이며 기본 워크스페이스를 기본값으로 함). |
-f, --format <table|json> | 출력 형식(기본값: table) |
-v, --log-level <string> | 로그 레벨: off, trace, debug, info, warn, error, fatal(기본값은 conf.json의 system.logLevel) |
--dry-run | 변경을 수행하지 않고 수행될 작업을 검증하고 출력 |
--home-dir <path> | 사용자 설정의 기본 디렉토리(기본값은 시스템 사용자 홈) |
참고:
-w(또는--workspace)를 제외한 모든 플래그는 선택 사항입니다. 선택적 플래그가 지정되지 않으면 CLI가 기본값을 사용합니다.
하위 명령어 참조
각 명령어의 자세한 플래그와 예시는
references/commands.md를 참조하십시오.
| 명령어 | 하위 명령어 |
|---|---|
siyuan workspace | list, info |
siyuan notebook | list, create, open, close, rename, remove, set-icon, random-icon |
siyuan document | list, get/info, create, rename, move, duplicate, remove, search |
siyuan block | get, children, insert, append, prepend, update, delete, move, stat, dom, kramdown, breadcrumb, batch-get, batch-kramdown |
siyuan sql "<stmt>" | (직접) |
siyuan search <query> | (직접, 플래그 포함) |
siyuan export | md, html, docx, sy, md-zip, preview, data |
siyuan import | md, sy, data |
siyuan dailynote | create, append, prepend |
siyuan asset | unused, clean, stat, upload |
siyuan attr | get, set, batch-get |
siyuan bookmark | list, labels, rename, remove |
siyuan tag | list, rename, remove |
siyuan history | list, get, search, rollback, clear |
siyuan ref | backlinks, mentions, refresh |
siyuan repo | list, create, diff, checkout, tag, untag, purge, search, file |
siyuan sync | pull, push, status |
siyuan database | search, get, keys, render, unused, clean, key, item |
siyuan file | list, read, write, copy, rename, delete, find, grep, stat |
siyuan inbox | list, get, convert |
siyuan outline | get |
siyuan template | search, get, create, save-as, render, remove |
siyuan system | current-time |
siyuan serve | (직접, 플래그 포함) |
siyuan completion | bash, fish, powershell, zsh |
참고:
serve는 모든 전역 플래그와 자체 플래그(--accessAuthCode,--attach-ui,--enable-pprof,--lang,--mode,--port,--readonly,--ssl,--safe-mode,--wd)를 허용합니다.-w는 필요하지 않습니다. 전체 플래그 목록은references/commands.md를 참조하십시오.