커맨드 라인 (CLI)
Social Archiver는 커맨드 라인에서 실행할 수 있어 스크립팅, 자동화, 코딩 에이전트에 유용합니다. 두 가지 커맨드 라인 표면과 함께, AI 코딩 에이전트를 위한 스킬 번들이 제공됩니다:
- 데스크톱
saCLI — 데스크톱 앱에 번들된 독립 실행형 도구입니다. Social Archiver 서버를 직접 호출하므로 데스크톱 창을 열어 둘 필요가 없습니다. - Obsidian 플러그인 CLI —
obsidian바이너리를 통해 실행 중인 Obsidian vault를 제어합니다. 아카이브를 vault에 Markdown으로 저장하고 싶을 때 사용하세요. - 에이전트 스킬 — 코딩 에이전트(Claude Code, Codex, OpenCode 등)에게 두 CLI를 안전하게 사용하는 방법을 알려 주는 설치형 스킬 번들입니다.
어떤 것을 사용해야 하나요?
계정을 대상으로 헤드리스 스크립팅과 자동화를 하려면 데스크톱 sa CLI를 사용하세요. 특정 vault에 Markdown 노트를 쓰는 것이 목표이고 Obsidian이 열려 있다면 Obsidian 플러그인 CLI를 사용하세요. 두 가지 모두 동일한 JSON envelope를 반환합니다.
데스크톱 sa CLI
데스크톱 앱은 독립적으로 동작하는 커맨드 라인 바이너리를 함께 제공합니다. Node.js나 별도 다운로드가 필요하지 않습니다.
설치
- 데스크톱 앱을 설치하고 로그인합니다
- Settings → Command line → Install 'sa' command를 엽니다
- 아무 터미널에서나
sa를 실행합니다
sa는 ~/.local/bin에 설치됩니다. 전체 이름인 social-archiver도 항상 동작하며, sa는 짧은 별칭일 뿐입니다.
sa가 이미 사용 중이라면
일부 시스템에서 sa는 내장 회계 도구(/usr/sbin/sa)입니다. 설치 프로그램은 사용자가 직접 만든 sa를 덮어쓰지 않으며, PATH 앞쪽에 있는 다른 sa가 여전히 가리고 있다면 이를 알려 줍니다 — 그 경우에는 social-archiver를 대신 실행하세요. sa를 찾을 수 없다면 ~/.local/bin을 PATH에 추가하세요.
로그인
데스크톱 앱이 설치되어 있고 로그인되어 있다면, CLI는 그 계정을 자동으로 빌려 씁니다 — 별도 로그인이 필요 없습니다. 헤드리스 머신이나 CI에서는 토큰을 명시적으로 설정하세요:
# 환경 변수 (CI)
export SOCIAL_ARCHIVER_TOKEN="<token>"
# 또는 대화형 디바이스 코드 로그인
# (휴대폰이나 로그인된 앱에서 승인할 코드 + QR 표시)
sa login
# 저장된 자격 증명 제거
sa logout토큰이 없어도 명령은 실행되지만 authenticated: false로 보고되며, 계정이 필요한 호출은 실패합니다.
명령어
모든 명령어는 기본적으로 JSON envelope를 반환합니다 — { "ok": true, "data": … } 또는 { "ok": false, "error": … }. 사람이 읽기 쉬운 간결한 출력을 원하면 --format text를 전달하세요.
| 명령어 | 하는 일 |
|---|---|
status | 로그인 상태와 사용 가능한 기능 확인 |
archive | 소셜 또는 웹 URL 아카이브 (폴링할 jobId 반환) |
job | 아카이브 또는 트랜스크립션 작업 상태 확인 |
search | 아카이브한 포스트 검색 (서버 측, 스니펫 반환) |
bookmark | Inbox와 Archived 간에 포스트 이동 (일괄) |
subscribe | 공개 프로필 또는 피드 구독 |
post | 로컬 Markdown 파일을 타임라인에 게시 |
share | 아카이브의 공개 공유 링크 생성 |
tags | 태그 목록 표시 |
author-notes | 최근 아카이브로부터 서버 작성자 프로필 시드 생성 |
export / tag / note / push | 아카이브를 로컬 Markdown으로 가져오고, 편집하고, 변경 사항을 다시 푸시 |
ai-comment | AI 댓글 작업 큐에 추가 (--run을 추가하면 인라인 실행) |
executor | 프로바이더 CLI로 큐에 쌓인 AI 작업을 로컬에서 실행 (--watch로 계속 실행 유지) |
transcribe | 비디오/오디오 아카이브 트랜스크립션 (--run으로 인라인, --doctor로 로컬 도구 확인) |
최신 릴리스에서 새로 추가됨
search, bookmark(export --archived 필터 포함), transcribe(및 transcribe --doctor), ai-comment --run, 그리고 항상 켜져 있는 헤드리스 executor --watch는 최신 데스크톱 CLI 업데이트에서 추가되었습니다.
각 명령어의 플래그를 보려면 sa <command> --help를 실행하세요.
예시
# 준비 상태 확인
sa status
# URL을 아카이브한 뒤 작업이 완료될 때까지 폴링
sa archive --url="https://www.instagram.com/p/example/"
sa job --id="<jobId>"
# 아카이브 검색
sa search --q "quantum computing" --limit 10
# Inbox에서 Archived로 포스트 이동
sa bookmark --ids id1,id2
# 공개 프로필 구독, 오전 9시로 예약
sa subscribe --url="https://x.com/alice" --hour 9
# 비디오 아카이브 트랜스크립션 (데스크톱 executor용 작업 큐에 추가; 폴링)
sa transcribe <archiveId> --mode download-and-transcribe
sa job --id="<jobId>"
# …또는 트랜스크립션을 인라인으로 실행 (로컬에 yt-dlp + ffmpeg + Whisper 설치 필요)
sa transcribe <archiveId> --run
# 오프라인 데모, 계정 불필요
sa status --host=mock크레딧과 한도
대부분의 아카이브는 무료 직접 스크래핑으로 실행되어 0 크레딧이 소모됩니다 — 유료 폴백과 AI 분석만 크레딧을 사용합니다. 월간 크레딧은 10개(무료), **500개(프로)**입니다. 로컬 추정치보다 서버 응답을 신뢰하세요.
INSUFFICIENT_CREDITS나 PAYWALL_REQUIRED가 발생하면, 같은 계정으로 모바일 앱에서 구독을 업그레이드하거나 복원하거나, 라이선스 키를 적용하세요. 스토어 정책상 CLI는 직접 결제를 받을 수 없습니다 — 메시지를 표시하고 멈추세요. 재시도하지 마세요.
Obsidian 플러그인 CLI
Obsidian 플러그인은 social-archiver 네임스페이스 아래에 명령어를 등록하므로 모달을 열지 않고도 플러그인을 제어할 수 있습니다. 데스크톱 CLI와 달리, 이것은 실행 중인 Obsidian 프로세스와 통신하며 vault에 씁니다.
요구사항
- Obsidian 1.12.7+ 설치 프로그램, 그리고 Obsidian이 열려 있어야 합니다
- 대상 vault에서 Social Archiver 플러그인이 활성화되고 로그인되어 있어야 합니다
- Obsidian → Settings → General → Command line interface에서 CLI가 활성화되어 있어야 합니다
- PATH에
obsidian바이너리가 있어야 합니다 (obsidian help로 확인)
사용법
기계가 읽을 수 있는 출력을 위해 vault=<vault>를 먼저, format=json을 함께 전달하세요:
# 상태
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모든 명령어와 플래그를 확인하려면:
obsidian help
obsidian help social-archiver:archive코딩 에이전트 (스킬)
두 CLI는 모두 코딩 에이전트 — Claude Code, Codex, OpenCode, 그 외 스킬 호환 에이전트 — 를 위한 설치형 스킬로 제공됩니다. 번들에는 두 개의 스킬이 포함되어 있습니다:
social-archiver-desktop-cli— 데스크톱saCLI를 헤드리스로 제어obsidian-social-archiver-cli— 실행 중인 Obsidian vault를 제어
게시된 번들을 설치하세요:
# 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 응답 envelope, 에러 코드, 그리고 에이전트가 따라야 할 규칙(토큰을 절대 출력하지 않기, 결제 에러 시 멈추기, 레이트 리밋 준수하기)을 문서화합니다.
권한과 윤리
에이전트는 사용자를 대신해 아카이브합니다. 저장할 권한이 있는 콘텐츠만 아카이브하세요 — Social Archiver는 공개 포스트와 프로필만 아카이브할 수 있습니다. 비공개이거나 로그인이 필요한 콘텐츠는 우회 없이 종료 에러를 반환합니다.
문제 해결
sa: command not found
~/.local/bin을 PATH에 추가하거나, 전체 이름인 social-archiver를 실행하세요. 필요하면 Settings → Command line → Install 'sa' command를 다시 실행하세요.
sa가 잘못된 도구를 실행함
PATH 앞쪽에 있는 다른 sa(예: /usr/sbin/sa)가 이를 가리고 있습니다. social-archiver를 대신 실행하세요.
AUTH_REQUIRED
로그인되어 있지 않습니다. 데스크톱 앱에 로그인하거나, 헤드리스 용도라면 SOCIAL_ARCHIVER_TOKEN을 설정하거나 sa login을 실행하세요. Obsidian CLI의 경우 플러그인 설정에서 로그인을 완료하세요.
obsidian help에 social-archiver 명령어가 없음
Settings → General → Command line interface를 활성화하고, Obsidian 1.12.7+ 설치 프로그램으로 업데이트하고, vault에서 플러그인이 활성화되어 있는지 확인한 뒤, Obsidian을 한 번 재시작하세요.
INSUFFICIENT_CREDITS / PAYWALL_REQUIRED
같은 계정으로 모바일 앱에서 업그레이드하거나 복원하거나, 라이선스 키를 적용하세요. CLI는 결제를 받을 수 없습니다.