커맨드 라인 (CLI)

Social Archiver는 터미널에서 실행할 수 있습니다. 스크립트, 자동화, 코딩 에이전트에 유용합니다. 세 가지 방식이 있습니다:

social-archiver CLI — Social Archiver 서버와 직접 통신하는 단독 실행 바이너리입니다. Node.js도, 데스크톱 앱도, 실행 중인 GUI도 필요 없습니다. 대부분의 경우 이것을 쓰면 됩니다.
Obsidian 플러그인 CLI — obsidian 바이너리를 통해 실행 중인 Obsidian 보관함을 조작합니다. 특정 보관함에 Markdown 노트를 남기는 것이 목적일 때 사용합니다.
에이전트 스킬 — 코딩 에이전트(Claude Code, Codex, OpenCode 등)에게 두 CLI를 안전하게 다루는 법을 알려주는 설치형 스킬 번들입니다.

베타

social-archiver CLI는 베타(0.1.x)입니다. 릴리스 사이에 명령과 JSON 필드가 바뀔 수 있으니, 자동화에서는 버전을 고정하고 업그레이드 전 릴리스 노트를 확인하세요.

어떤 것을 써야 하나요?

스크립트·자동화·에이전트에는 social-archiver CLI를, 열려 있는 보관함에 노트를 남기고 싶을 때는 Obsidian 플러그인 CLI를 사용하세요. 두 방식 모두 동일한 JSON 응답 형식을 반환합니다.

`social-archiver` CLI

단독 실행 파일 하나와 작은 자격 증명 헬퍼로 구성됩니다. 실행에 다른 것은 필요하지 않습니다.

설치

WindowsmacOSLinuxnpm

powershell

# Microsoft Store (또는 스토어 앱에서 "Social Archiver CLI" 검색)
winget install --id 9PLC2NC0G11J --source msstore

# 설치 후 새 터미널을 연 다음 실행하세요:
social-archiver --version

bash

# Homebrew
brew install hyungyunlim/tap/social-archiver-cli

# …또는 체크섬을 검증하는 설치 스크립트 (sudo 불필요, ~/.local/bin에 설치)
curl -fsSL \
  https://github.com/hyungyunlim/obsidian-social-archiver-releases/releases/download/cli-v0.1.5/install.sh |
  sh

bash

# 체크섬을 검증하는 설치 스크립트 (sudo 불필요, ~/.local/bin에 설치)
curl -fsSL \
  https://github.com/hyungyunlim/obsidian-social-archiver-releases/releases/download/cli-v0.1.5/install.sh |
  sh

bash

# Node.js 20+가 있는 모든 플랫폼 — 런처가 동일한 네이티브 바이너리를 설치합니다
npm install --global social-archiver

# …또는 설치 없이 한 번만 실행
npx -y [email protected] --version

Windows에서는 스토어 패키지가 social-archiver.exe를 앱 실행 별칭으로 등록하는데, 이미 열려 있는 터미널은 이를 인식하지 못합니다. 설치 후 새 터미널을 여세요. Windows용 데스크톱 앱은 없으며, 스토어가 정식 설치 경로입니다.

macOS와 Linux에서는 설치 스크립트가 릴리스 체크섬을 검증하고, Homebrew나 다른 설치 도구가 관리하는 명령을 덮어쓰지 않으며, 셸 시작 파일을 수정하지 않습니다. ~/.local/bin이 PATH에 없으면 추가할 줄을 안내합니다.

데스크톱 앱을 이미 쓰고 있다면

macOS 데스크톱 앱에 같은 CLI가 포함되어 있습니다. 설정 → 커맨드 라인 → 'social-archiver' 명령 설치에서 바로 설치하면 별도 다운로드가 필요 없습니다. 짧은 sa 별칭도 같은 설정에서 선택할 수 있습니다.

# 대화형: 휴대폰이나 로그인된 앱에서 승인할 코드와 QR을 표시합니다
social-archiver login

# CI·헤드리스: 토큰을 파이프로 전달해 프로세스 목록에 남지 않게 합니다
printf '%s' "$SOCIAL_ARCHIVER_TOKEN" | social-archiver login --token-stdin

# 또는 실행할 때마다 환경 변수로 전달
export SOCIAL_ARCHIVER_TOKEN="<token>"

# 저장된 자격 증명 삭제 (데스크톱 세션은 그대로 유지됩니다)
social-archiver logout

자격 증명은 OS가 보관합니다. macOS는 키체인, Windows는 자격 증명 관리자, Linux는 Secret Service를 사용합니다. Secret Service가 없는 헤드리스 Linux에서는 0600 권한 파일로 대체하고 그 사실을 알려줍니다. 토큰이 전혀 없어도 명령은 실행되지만 authenticated: false로 보고하며, 계정이 필요한 호출은 실패합니다.

명령어

모든 명령은 JSON 응답을 반환합니다 — { "ok": true, "data": … } 또는 { "ok": false, "error": … }. 사람이 읽기 좋은 간결한 출력은 --format text를, 각 명령의 플래그는 --help를 사용하세요.

명령어	설명
`status`	로그인 상태와 사용 가능한 기능 확인
`archive`	소셜·웹 URL 아카이브 (폴링용 `jobId` 반환)
`job`	아카이브·트랜스크립션 작업 상태 확인
`search`	서버에서 아카이브 검색 (스니펫 반환)
`export`	아카이브를 로컬 Markdown으로 내려받아 grep·읽기 가능하게
`tag` / `note`	내보낸 파일을 분류하거나 노트 추가
`push`	내보낸 파일의 프론트매터 수정 사항을 서버로 반영
`places`	추출된 장소 후보 검토·확정·해제
`bookmark`	Inbox와 Archived 사이로 포스트 이동 (일괄)
`subscribe`	공개 프로필이나 피드 구독 — Premium 전용
`subscriptions`	기존 구독 조회·일시중지·재개·즉시 실행·삭제
`post` / `share`	로컬 Markdown 게시, 또는 공개 공유 링크 생성
`tags`	태그 목록 조회
`author-notes`	최근 아카이브에서 서버 작성자 프로필 생성
`ai-comment`	AI 코멘트 작업 큐에 추가 (`--run`으로 즉시 실행)
`executor`	큐에 쌓인 AI 작업을 로컬 provider CLI로 실행 (`--watch`로 상주)
`transcribe`	비디오·오디오 아카이브 트랜스크립션 (`--run` 인라인, `--doctor` 로컬 도구 점검)

0.1.5 신규

Microsoft Store를 통한 Windows 지원, places 검토 명령, 그리고 export 결과에 포함되는 장소·상품 정보.

찾는 방법 두 가지

search와 export는 서로 다른 질문에 답합니다. 알맞은 쪽을 고르면 호출 수를 크게 줄일 수 있습니다:

search — 서버에서 전체 아카이브를 검색해 스니펫을 돌려줍니다. "X에 대한 게 있었나?"에 적합합니다.
export — 아카이브를 로컬 Markdown으로 한 번 내려받고 나면, 이후 grep·rg나 에이전트가 서버 호출 없이 얼마든지 읽을 수 있습니다. 분석, 대량 검토, 반복 작업에 적합합니다.

bash

# 서버 검색, 스니펫 반환
social-archiver search --q "quantum computing" --limit 10

# 로컬 코퍼스 — 한 번 내려받고 이후 원하는 만큼 검색
social-archiver export --dir ./workspace --limit 200
grep -ril "quantum" ./workspace

내보낸 파일 속 장소와 상품 정보

내보낸 파일에는 본문뿐 아니라 Social Archiver가 추출한 구조화된 정보가 함께 담깁니다. 장소가 연결되어 있거나 상품 정보가 있는 아카이브는 프론트매터에 다음이 포함됩니다:

yaml

---
archiveId: "EpCJKin6yj"
platform: threads
places:
  - name: 모녀가리비
    address: 강원특별자치도 속초시 대포항희망길 53
    lat: 38.1733071627822
    lng: 128.605777284753
    source: kakaomap
    category: 음식점 > 한식 > 해물,생선 > 조개
product:
  name: Vital Seamless Leggings
  price: 25
  currency: USD
  availability: InStock
  brand: Gymshark
  rating: 4.5
---

해당 정보가 없는 아카이브에서는 블록 자체가 생략되므로, grep -l '^places:' ./workspace로 장소가 있는 아카이브만 정확히 골라낼 수 있습니다. 같은 값이 본문 메타 줄에도 **Place:**, **Price:**로 표시되어 평문 검색으로도 잡힙니다.

장소 후보는 추출 단계에서 제안된 것이고, 확정해야 실제로 연결됩니다. 그 확정을 하는 곳이 places입니다:

bash

# 대기 중인 후보 검토 — 각 후보는 추출 근거와 함께 표시됩니다
social-archiver places --limit 20

# 맞는 후보만 확정
social-archiver places attach --archive EpCJKin6yj --candidate c1,c2

# 연결된 모든 아카이브에서 장소 제거 (포스트는 삭제되지 않습니다)
social-archiver places detach --place-key kakaomap:965452574

예시

bash

# 준비 상태 확인
social-archiver status

# URL을 아카이브한 뒤 작업 완료까지 폴링
social-archiver archive --url="https://www.instagram.com/p/example/"
social-archiver job --id="<jobId>"

# Inbox에서 Archived로 포스트 이동
social-archiver bookmark --ids id1,id2

# 공개 프로필 구독, 오전 9시로 예약
social-archiver subscribe --url="https://x.com/alice" --hour 9

# 이미 만든 구독 관리
social-archiver subscriptions                          # 목록 (id·플랫폼·활성 여부)
social-archiver subscriptions pause --id <id>          # 일시중지 (커서는 유지됩니다)
social-archiver subscriptions run --id <id>            # 즉시 실행, runId 반환
social-archiver subscriptions runs --id <id> --limit 5 # 실행 이력·크레딧·실패 원인
social-archiver subscriptions delete --id <id> --yes   # 구독 해지 (아카이브는 보존)

# 비디오 아카이브 트랜스크립션 (executor용 작업을 큐에 추가하고 폴링)
social-archiver transcribe <archiveId> --mode download-and-transcribe

# …또는 인라인 실행 (로컬에 yt-dlp + ffmpeg + Whisper 필요)
social-archiver transcribe <archiveId> --run

# 오프라인 데모 — 계정도 네트워크도 불필요
social-archiver status --host=mock

유료 기능

대부분의 명령은 모든 플랜에서 동작합니다. 다만 subscribe는 Premium 이용권이 활성화되어 있어야 합니다 — 프로필·피드 구독은 유료 기능입니다. 이용권이 없으면 서버가 402로 응답하고 CLI는 다음을 반환합니다:

json

{ "ok": false, "error": { "code": "PAYWALL_REQUIRED", "retryable": false } }

제한은 URL이 아니라 계정에 걸리므로 다른 프로필을 시도해도 결과는 같습니다. 같은 계정으로 모바일 앱에서 업그레이드하거나 복원한 뒤 다시 실행하세요.

크레딧과 한도

대부분의 아카이브는 무료 직접 스크래핑으로 처리되어 0 크레딧입니다. 유료 폴백과 AI 분석만 크레딧을 사용합니다. 월 크레딧은 10 (무료), **500 (프로)**입니다. 로컬 추정치보다 서버 응답을 신뢰하세요.

INSUFFICIENT_CREDITS나 PAYWALL_REQUIRED가 발생하면 같은 계정으로 모바일 앱에서 업그레이드·복원하거나 라이선스 키를 적용하세요. 스토어 정책상 CLI는 직접 결제를 받을 수 없으므로, 재시도하지 말고 메시지를 그대로 전달한 뒤 중단해야 합니다.

Obsidian 플러그인 CLI

Obsidian 플러그인은 social-archiver 네임스페이스로 명령을 등록하므로 모달을 열지 않고도 조작할 수 있습니다. 단독 CLI와 달리 실행 중인 Obsidian 프로세스와 통신하며 보관함에 파일을 씁니다.

요구사항

Obsidian 1.12.7+ 설치 프로그램, 그리고 Obsidian이 실행 중이어야 함
대상 보관함에서 Social Archiver 플러그인이 활성화되고 로그인되어 있을 것
Obsidian → 설정 → 일반 → 커맨드 라인 인터페이스에서 CLI 활성화
obsidian 바이너리가 PATH에 있을 것 (obsidian help로 확인)

사용법

vault=<보관함>을 먼저 전달하고, 기계가 읽을 출력에는 format=json을 사용하세요:

bash

# 상태
obsidian vault="Research" social-archiver format=json

# URL을 아카이브한 뒤 작업 폴링
obsidian vault="Research" social-archiver:archive \
  url="https://www.instagram.com/p/example/" mode=queue format=json

obsidian vault="Research" social-archiver:job id="<jobId>" format=json

이미 만들어 둔 것 관리 — 단독 CLI와 동일한 기능입니다:

bash

# 구독: 목록을 보고, 일시중지하거나 왜 멈췄는지 확인
obsidian vault="Research" social-archiver:subscriptions format=json
obsidian vault="Research" social-archiver:subscriptions action=runs id="<id>" format=json
obsidian vault="Research" social-archiver:subscriptions action=pause id="<id>" format=json

# 추출된 장소 후보를 검토하고 맞는 것만 확정
obsidian vault="Research" social-archiver:places format=json
obsidian vault="Research" social-archiver:places action=attach archive="<id>" candidate="c1" format=json

# Inbox 일괄 정리
obsidian vault="Research" social-archiver:bookmark ids="id-1,id-2" format=json

모든 명령과 플래그 확인:

bash

obsidian help
obsidian help social-archiver:archive

코딩 에이전트 (스킬)

두 CLI 모두 코딩 에이전트용 스킬로 배포됩니다 — Claude Code, Codex, OpenCode 및 스킬 호환 에이전트. 번들에는 두 가지 스킬이 들어 있습니다:

social-archiver-desktop-cli — 단독 social-archiver CLI를 헤드리스로 조작
obsidian-social-archiver-cli — 실행 중인 Obsidian 보관함을 조작

배포된 번들 설치:

bash

# Claude Code 마켓플레이스
/plugin marketplace add hyungyunlim/obsidian-social-archiver-skills
/plugin install social-archiver@obsidian-social-archiver-skills

# 또는 npx로 (모든 스킬 호환 에이전트)
npx skills add https://github.com/hyungyunlim/obsidian-social-archiver-skills

# 또는 ~/.claude/skills, ~/.codex/skills, ~/.opencode/skills에 수동 복사
git clone https://github.com/hyungyunlim/obsidian-social-archiver-skills

번들은 hyungyunlim/obsidian-social-archiver-skills에 있습니다. 각 스킬은 전체 명령 카탈로그, JSON 응답 형식, 오류 코드, 그리고 에이전트가 지켜야 할 규칙(토큰을 출력하지 않기, 결제 오류에서 중단하기, 요청 한도 준수하기)을 문서화합니다.

권한과 윤리

에이전트는 사용자를 대신해 아카이브합니다. 저장할 권한이 있는 콘텐츠만 아카이브하세요. Social Archiver는 공개 게시물과 프로필만 아카이브할 수 있습니다. 비공개나 로그인이 필요한 콘텐츠는 우회 없이 종료 오류를 반환합니다.

문제 해결

Windows에서 `social-archiver: command not found`

스토어 패키지는 앱 실행 별칭을 등록하는데, 터미널은 시작할 때만 이를 인식합니다. 터미널을 닫고 새로 연 뒤 다시 시도하세요. 그래도 안 되면 설정 → 앱 → 고급 앱 설정 → 앱 실행 별칭에서 항목이 켜져 있는지 확인하세요.

macOS·Linux에서 `social-archiver: command not found`

~/.local/bin을 PATH에 추가하고 새 터미널을 여세요. 데스크톱 앱으로 설치했다면 설정 → 커맨드 라인 → 커맨드 라인 도구 복구를 다시 실행하세요.

`sa`가 다른 도구를 실행함

일부 시스템에서 sa는 기본 제공 계정 관리 도구(/usr/sbin/sa)입니다. 설치 스크립트는 사용자가 직접 만든 sa를 덮어쓰지 않으며, PATH 앞쪽의 다른 sa가 가리고 있으면 알려줍니다. 이 경우 social-archiver를 사용하세요.

`AUTH_REQUIRED`

로그인되어 있지 않습니다. social-archiver login을 실행하거나, 헤드리스 환경에서는 SOCIAL_ARCHIVER_TOKEN을 설정하세요. Obsidian CLI는 플러그인 설정에서 로그인을 완료하세요.

`obsidian help`에 `social-archiver` 명령이 없음

설정 → 일반 → 커맨드 라인 인터페이스를 활성화하고, Obsidian 1.12.7+ 설치 프로그램으로 업데이트한 뒤, 보관함에서 플러그인이 활성화되어 있는지 확인하고 Obsidian을 한 번 재시작하세요.

`INSUFFICIENT_CREDITS` / `PAYWALL_REQUIRED`

같은 계정으로 모바일 앱에서 업그레이드·복원하거나 라이선스 키를 적용하세요. CLI는 결제를 받을 수 없습니다.

커맨드 라인 (CLI) ​

social-archiver CLI ​

설치 ​

로그인 ​

명령어 ​

찾는 방법 두 가지 ​

내보낸 파일 속 장소와 상품 정보 ​

예시 ​

유료 기능 ​

크레딧과 한도 ​

Obsidian 플러그인 CLI ​

요구사항 ​

사용법 ​

코딩 에이전트 (스킬) ​

문제 해결 ​

Windows에서 social-archiver: command not found ​

macOS·Linux에서 social-archiver: command not found ​

sa가 다른 도구를 실행함 ​

AUTH_REQUIRED ​

obsidian help에 social-archiver 명령이 없음 ​

INSUFFICIENT_CREDITS / PAYWALL_REQUIRED ​

다음 단계 ​

커맨드 라인 (CLI)

`social-archiver` CLI

설치

로그인

명령어

찾는 방법 두 가지

내보낸 파일 속 장소와 상품 정보

예시

유료 기능

크레딧과 한도

Obsidian 플러그인 CLI

요구사항

사용법

코딩 에이전트 (스킬)

문제 해결

Windows에서 `social-archiver: command not found`

macOS·Linux에서 `social-archiver: command not found`

`sa`가 다른 도구를 실행함

`AUTH_REQUIRED`

`obsidian help`에 `social-archiver` 명령이 없음

`INSUFFICIENT_CREDITS` / `PAYWALL_REQUIRED`

다음 단계