コマンドライン（CLI）
Social Archiver はターミナルから操作でき、スクリプト、自動化、コーディングエージェントに便利です。方法は3つあります。
social-archiverCLI — Social Archiver サーバーと直接通信する自己完結型のバイナリです。Node.js もデスクトップアプリも、起動中の GUI も必要ありません。ほとんどの場合はこれを選べば十分です。- Obsidian プラグイン CLI —
obsidianバイナリを通じて起動中の Obsidian Vault を操作します。特定の Vault に Markdown ノートを書き込むことが目的の場合に使います。 - エージェントスキル — コーディングエージェント（Claude Code、Codex、OpenCode など）に、両方の CLI を安全に扱う方法を教えるインストール可能なスキルバンドルです。
ベータ
social-archiver CLI はベータ（0.1.x）です。リリース間でコマンドや JSON フィールドが変わる可能性があるため、自動化ではバージョンを固定し、アップグレード前にリリースノートを確認してください。
どれを使えばいい？
スクリプト・自動化・エージェントには social-archiver CLI を、開いている Vault にノートを残したい場合は Obsidian プラグイン CLI を使ってください。どちらも同じ JSON レスポンス形式を返します。
social-archiver CLI
自己完結型の実行ファイル1つと、小さな認証情報ヘルパーで構成されます。実行時にほかのものは必要ありません。
インストール
# Microsoft Store（またはストアアプリで「Social Archiver CLI」を検索）
winget install --id 9PLC2NC0G11J --source msstore
# インストール後に新しいターミナルを開いてから実行してください:
social-archiver --version# 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# チェックサムを検証するインストーラー（sudo 不要、~/.local/bin にインストール）
curl -fsSL \
https://github.com/hyungyunlim/obsidian-social-archiver-releases/releases/download/cli-v0.1.5/install.sh |
sh# Node.js 20+ がある任意のプラットフォーム — ランチャーが同じネイティブバイナリを導入します
npm install --global social-archiver
# …またはインストールせずに1回だけ実行
npx -y [email protected] --versionWindows ではストアパッケージが social-archiver.exe をアプリ実行エイリアスとして登録しますが、すでに開いているターミナルはこれを認識しません。インストール後に新しいターミナルを開いてください。Windows 版デスクトップアプリはなく、ストアが正式な導入経路です。
macOS と Linux ではインストーラーがリリースのチェックサムを検証し、Homebrew などほかのインストーラーが管理するコマンドを置き換えず、シェルの起動ファイルも変更しません。~/.local/bin が PATH にない場合は、追加すべき行を表示します。
すでにデスクトップアプリを使っている場合
macOS デスクトップアプリには同じ CLI が同梱されています。設定 → コマンドライン → 'social-archiver' コマンドをインストールから導入すれば、ダウンロードは不要です。短い sa エイリアスも同じ設定から選べます。
サインイン
デスクトップアプリがインストールされ、サインイン済みであれば、CLI は OS が保護しているアプリのアカウント情報を自動的に利用するため、別途ログインする必要はありません。それ以外の場合は次のとおりです。
# インタラクティブ: スマートフォンやサインイン済みアプリで承認するコードと 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 | ソーシャル・Web 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 出力に含まれる場所・商品情報。
探し方は2通り
search と export は答える問いが違います。適切なほうを選ぶと呼び出し回数を大きく減らせます。
search— サーバー側でアーカイブ全体を検索し、スニペットを返します。「X について何か保存していたか？」に向いています。export— アーカイブを一度ローカル Markdown として取得すれば、その後はgrep・rgやエージェントがサーバー呼び出しなしで何度でも読めます。分析、大量レビュー、繰り返しの作業に向いています。
# サーバー検索、スニペットが返る
social-archiver search --q "quantum computing" --limit 10
# ローカルコーパス — 一度取得すれば、あとは何度でも検索できます
social-archiver export --dir ./workspace --limit 200
grep -ril "quantum" ./workspaceエクスポートに含まれる場所と商品情報
エクスポートされたファイルには本文だけでなく、Social Archiver が抽出した構造化情報も含まれます。場所が紐付いているアーカイブや商品情報のあるアーカイブでは、フロントマターに次が入ります。
---
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 です。
# 保留中の候補をレビュー — 各候補は抽出根拠とともに表示されます
social-archiver places --limit 20
# 正しい候補だけを確定
social-archiver places attach --archive EpCJKin6yj --candidate c1,c2
# 紐付いているすべてのアーカイブから場所を外す（投稿は削除されません）
social-archiver places detach --place-key kakaomap:965452574例
# 準備状態を確認
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 の応答は次のとおりです。
{ "ok": false, "error": { "code": "PAYWALL_REQUIRED", "retryable": false } }制限は URL ではなくアカウントに対してかかるため、別のプロフィールを試しても同じ結果になります。同じアカウントでモバイルアプリからアップグレードまたは復元してから再実行してください。
クレジットと制限
ほとんどのアーカイブは無料の直接取得で処理され、0 クレジットです。有料フォールバックと AI 分析だけがクレジットを消費します。月間クレジットは 10（無料） と 500（Pro） です。ローカルの見積もりよりサーバーの応答を信頼してください。
INSUFFICIENT_CREDITS や PAYWALL_REQUIRED が出た場合は、同じアカウントでモバイルアプリからアップグレード・復元するか、ライセンスキーを適用してください。ストアポリシー上 CLI は直接決済を受け付けられないため、再試行せずメッセージをそのまま伝えて停止します。
Obsidian プラグイン CLI
Obsidian プラグインは social-archiver 名前空間でコマンドを登録するため、モーダルを開かずに操作できます。単体の CLI と違い、こちらは起動中の Obsidian プロセスと通信し、Vault にファイルを書き込みます。
要件
- Obsidian 1.12.7+ のインストーラー、かつ Obsidian が起動していること
- 対象 Vault で Social Archiver プラグインが有効かつサインイン済みであること
- Obsidian → 設定 → 一般 → コマンドラインインターフェースで CLI を有効化
obsidianバイナリが PATH にあること（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作成済みのものを管理する — 単独 CLI と同じ機能です。
# 購読: 一覧を見て、一時停止したり停止理由を確認したりする
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すべてのコマンドとフラグを確認するには:
obsidian help
obsidian help social-archiver:archiveコーディングエージェント（スキル）
どちらの CLI も、コーディングエージェント向けのスキルとして配布されています — Claude Code、Codex、OpenCode、その他スキル互換のエージェント。バンドルには2つのスキルが含まれます。
social-archiver-desktop-cli— 単体のsocial-archiverCLI をヘッドレスで操作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 レスポンス形式、エラーコード、そしてエージェントが守るべきルール（トークンを出力しない、課金エラーで停止する、レート制限を守る）が記載されています。
権限と倫理
エージェントはあなたに代わってアーカイブします。保存する権限があるコンテンツだけをアーカイブしてください。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+ のインストーラーに更新し、Vault でプラグインが有効になっていることを確認して、Obsidian を一度再起動してください。
INSUFFICIENT_CREDITS / PAYWALL_REQUIRED
同じアカウントでモバイルアプリからアップグレード・復元するか、ライセンスキーを適用してください。CLI は決済を受け付けられません。