コマンドライン（CLI）

Social Archiverはコマンドラインから操作でき、スクリプト、自動化、コーディングエージェントに便利です。コマンドライン操作には2つの方法があり、さらにAIコーディングエージェント向けのスキルバンドルも用意されています。

• デスクトップsa CLI — デスクトップアプリに同梱されるスタンドアロンツールです。Social Archiverサーバーを直接呼び出すため、デスクトップウィンドウを開いておく必要はありません。
• Obsidianプラグイン CLI — obsidianバイナリを通じて実行中のObsidian Vaultを操作します。アーカイブをVaultにMarkdownとして書き込みたい場合に使います。
• エージェントスキル — コーディングエージェント（Claude Code、Codex、OpenCodeなど）にどちらのCLIも安全に使う方法を教える、インストール可能なスキルバンドルです。

どちらを使えばよいですか？

アカウントに対するヘッドレスなスクリプトや自動化にはデスクトップsa CLIを使います。特定のVaultにMarkdownノートを作成することが目的で、Obsidianが開いている場合はObsidianプラグイン CLIを使います。どちらも同じJSONエンベロープを返します。

デスクトップsa CLI

デスクトップアプリには、自己完結型のコマンドラインバイナリが同梱されています。Node.jsや別途のダウンロードは不要です。

インストール

1. デスクトップアプリをインストールしてサインインします
2. Settings → Command line → Install 'sa' commandを開きます
3. 任意のターミナルから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エンベロープを返します — { "ok": true, "data": … }または{ "ok": false, "error": … }です。コンパクトで人間が読みやすい出力にするには--format textを指定します。

コマンド	機能
status	サインイン状態と利用可能な機能を確認
archive	ソーシャルまたはWebのURLをアーカイブ（ポーリング用のjobIdを返す）
job	アーカイブまたは文字起こしジョブの状態を確認
search	アーカイブ済み投稿を検索（サーバー側、スニペットを返す）
bookmark	投稿をInboxとArchivedの間で移動（一括）
subscribe	公開プロフィールまたはフィードを購読
post	ローカルのMarkdownファイルをタイムラインに投稿
share	アーカイブの公開共有リンクを作成
tags	タグを一覧表示
author-notes	最近のアーカイブからサーバーの著者プロフィールを生成
export / tag / note / push	アーカイブをローカルMarkdownに取り込み、編集して変更を反映
ai-comment	AI Commentジョブをキューに追加（--runを付けるとその場で実行）
executor	キュー済みのAIジョブをプロバイダーCLIでローカル実行（--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（pro）**です。ローカルの見積もりよりもサーバーの応答を信頼してください。

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、その他スキル互換エージェント）向けのインストール可能なスキルとして提供されています。バンドルには2つのスキルが含まれています。

• social-archiver-desktop-cli — デスクトップsa CLIをヘッドレスで操作
• 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がアーカイブできるのは公開された投稿やプロフィールのみです。非公開またはログインが必要なコンテンツは、回避手段のない終端エラーを返します。

トラブルシューティング

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は決済を受け付けられません。

次のステップ

• デスクトップアプリ
• AI Comments
• 文字起こし（音声・動画）
• 購読