Command Line (CLI)

Social Archiver can be driven from a terminal — useful for scripting, automation, and coding agents. There are three surfaces:

social-archiver CLI — a self-contained binary that talks to the Social Archiver service directly. It needs no Node.js, no desktop app, and no GUI running. This is the one most people want.
Obsidian plugin CLI — drives a running Obsidian vault through the obsidian binary. Use this when the goal is Markdown notes written into a specific vault.
Agent skills — installable skill bundles that teach coding agents (Claude Code, Codex, OpenCode, and others) how to drive either CLI safely.

Beta

The social-archiver CLI is in beta (0.1.x). Commands and JSON fields can still change between releases — pin a version in automation, and check the release notes before upgrading.

Which one should I use?

Use the social-archiver CLI for scripting, automation, and agents. Use the Obsidian plugin CLI when you specifically want notes in an open vault. Both return the same JSON envelope.

`social-archiver` CLI

A single self-contained executable plus a small credential helper. Nothing else is required at runtime.

Install

WindowsmacOSLinuxnpm

powershell

# Microsoft Store (or search "Social Archiver CLI" in the Store app)
winget install --id 9PLC2NC0G11J --source msstore

# Open a NEW terminal afterwards, then:
social-archiver --version

bash

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

# …or the checksum-verified installer (no sudo, installs to ~/.local/bin)
curl -fsSL \
  https://github.com/hyungyunlim/obsidian-social-archiver-releases/releases/download/cli-v0.1.5/install.sh |
  sh

bash

# Checksum-verified installer (no sudo, installs to ~/.local/bin)
curl -fsSL \
  https://github.com/hyungyunlim/obsidian-social-archiver-releases/releases/download/cli-v0.1.5/install.sh |
  sh

bash

# Any platform with Node.js 20+ — the launcher installs the same native binary
npm install --global social-archiver

# …or run one command without installing
npx -y [email protected] --version

On Windows the Store package installs social-archiver.exe as an App Execution Alias, which terminals only pick up when they start — open a new one after installing. There is no Windows desktop app; the Store is the supported Windows route.

On macOS and Linux the installer verifies the release checksum, never replaces a command owned by Homebrew or another installer, and does not edit your shell startup files. If ~/.local/bin is not on your PATH, it prints the line to add.

Already using the desktop app?

The macOS desktop app bundles the same CLI. Install it from Settings → Command line → Install 'social-archiver' command and skip the download entirely. The optional short sa alias lives in the same settings section.

If the desktop app is installed and signed in, the CLI borrows its OS-protected account record automatically — no separate login needed. Otherwise:

bash

# Interactive: prints a code + QR to approve on your phone or a signed-in app
social-archiver login

# CI / headless: pipe a token in so it never lands in the process list
printf '%s' "$SOCIAL_ARCHIVER_TOKEN" | social-archiver login --token-stdin

# Or pass it per-run as an environment variable
export SOCIAL_ARCHIVER_TOKEN="<token>"

# Remove the stored credential (leaves the desktop session alone)
social-archiver logout

Credentials are stored by the OS — Keychain on macOS, Credential Manager on Windows, Secret Service on Linux. Headless Linux without Secret Service falls back to a 0600 file and reports that it did. With no token at all, commands still run but report authenticated: false, and account-gated calls fail closed.

Commands

Every command returns a JSON envelope — { "ok": true, "data": … } or { "ok": false, "error": … }. Pass --format text for compact human-readable output, and --help on any command for its flags.

Command	What it does
`status`	Check sign-in state and which features are available
`archive`	Archive a social or web URL (returns a `jobId` to poll)
`job`	Check the status of an archive or transcription job
`search`	Search your archives on the server (returns snippets)
`export`	Pull archives down as local Markdown you can grep and read
`tag` / `note`	Classify an exported file, or attach a note to it
`push`	Push frontmatter edits from exported files back to the server
`places`	Review, confirm, or detach extracted place candidates
`bookmark`	Move posts between Inbox and Archived (bulk)
`subscribe`	Subscribe to a public profile or feed — Premium only
`subscriptions`	List, pause, resume, run, or delete existing subscriptions
`post` / `share`	Post a local Markdown file, or create a public share link
`tags`	List your tags
`author-notes`	Seed server author profiles from recent archives
`ai-comment`	Queue an AI Comment job (add `--run` to run it inline)
`executor`	Run queued AI jobs locally with a provider CLI (`--watch` to keep running)
`transcribe`	Transcribe a video/audio archive (`--run` inline, `--doctor` to check local tools)

New in 0.1.5

Windows support through the Microsoft Store, the places review command, and places/product details in export output.

Two ways to find things

search and export answer different questions, and picking the right one saves a lot of calls:

search runs on the server across your whole archive and returns snippets. Best for "do I have anything about X?"
export materializes archives as local Markdown once, after which grep, rg, or an agent can read them with zero further server calls. Best for analysis, bulk review, and anything repeated.

bash

# Server-side, snippets back
social-archiver search --q "quantum computing" --limit 10

# Local corpus — one call, then search it as many times as you like
social-archiver export --dir ./workspace --limit 200
grep -ril "quantum" ./workspace

Places and products in exported files

Exported files carry the structured details Social Archiver extracted, not just the post text. When an archive has an attached place or a product snapshot, its frontmatter includes them:

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
---

Both blocks are omitted when the archive has neither, so grep -l '^places:' ./workspace cleanly selects everything with a location. The same values also appear on the metadata line as **Place:** and **Price:** for plain-text scans.

Place candidates are proposed by extraction and only become attached locations once confirmed — places is where you do that:

bash

# Review the pending queue; each candidate comes with the evidence it came from
social-archiver places --limit 20

# Confirm the ones that are right
social-archiver places attach --archive EpCJKin6yj --candidate c1,c2

# Remove a place from every archive it was attached to (posts are never deleted)
social-archiver places detach --place-key kakaomap:965452574

Examples

bash

# Check readiness
social-archiver status

# Archive a URL, then poll the job to completion
social-archiver archive --url="https://www.instagram.com/p/example/"
social-archiver job --id="<jobId>"

# Move posts out of the Inbox into Archived
social-archiver bookmark --ids id1,id2

# Subscribe to a public profile, scheduled for 9am
social-archiver subscribe --url="https://x.com/alice" --hour 9

# Manage the subscriptions you already have
social-archiver subscriptions                          # list (id, platform, enabled)
social-archiver subscriptions pause --id <id>          # stop it running; keeps the cursor
social-archiver subscriptions run --id <id>            # run now, returns a runId
social-archiver subscriptions runs --id <id> --limit 5 # what ran, what it cost, why it failed
social-archiver subscriptions delete --id <id> --yes   # unsubscribe; archives are kept

# Transcribe a video archive (queues a job for an executor; poll it)
social-archiver transcribe <archiveId> --mode download-and-transcribe

# …or run transcription inline (needs yt-dlp + ffmpeg + Whisper locally)
social-archiver transcribe <archiveId> --run

# Offline demo — no account, no network
social-archiver status --host=mock

Premium features

Most commands work on any plan. subscribe requires an active Premium entitlement — profile and feed subscriptions are a paid feature. Without one the server answers 402 and the CLI returns:

json

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

The gate is on the account, not the URL, so trying a different profile will not help. Upgrade or restore in the mobile app with the same account, then retry.

Credits and limits

Most archives run through free direct scraping and cost 0 credits — only paid fallback and AI analysis consume them. Monthly credits are 10 (free) and 500 (pro). Trust the server's response over any local estimate.

If you hit INSUFFICIENT_CREDITS or PAYWALL_REQUIRED, upgrade or restore your subscription in the mobile app with the same account, or apply a license key. Under store policy the CLI cannot accept payment directly — surface the message and stop rather than retrying.

Obsidian Plugin CLI

The Obsidian plugin registers commands under the social-archiver namespace so you can drive it without opening modals. Unlike the standalone CLI, this talks to a running Obsidian process and writes into your vault.

Requirements

Obsidian 1.12.7+ installer, and Obsidian must be open
The Social Archiver plugin enabled in the target vault, signed in
CLI enabled in Obsidian → Settings → General → Command line interface
The obsidian binary on your PATH (verify with obsidian help)

Usage

Pass vault=<vault> first and format=json for machine-readable output:

bash

# Status
obsidian vault="Research" social-archiver format=json

# Archive a URL, then poll the job
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

Manage what you already have — these mirror the standalone CLI:

bash

# Subscriptions: list, then pause one or see why it stopped
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

# Review extracted place candidates, then confirm the right ones
obsidian vault="Research" social-archiver:places format=json
obsidian vault="Research" social-archiver:places action=attach archive="<id>" candidate="c1" format=json

# Clear the Inbox in bulk
obsidian vault="Research" social-archiver:bookmark ids="id-1,id-2" format=json

Discover every command and its flags:

bash

obsidian help
obsidian help social-archiver:archive

Coding Agents (Skills)

Both CLIs ship as installable skills for coding agents — Claude Code, Codex, OpenCode, and other skill-compatible agents. The bundle contains two skills:

social-archiver-desktop-cli — drive the standalone social-archiver CLI headlessly
obsidian-social-archiver-cli — drive a running Obsidian vault

Install the published bundle:

bash

# Claude Code marketplace
/plugin marketplace add hyungyunlim/obsidian-social-archiver-skills
/plugin install social-archiver@obsidian-social-archiver-skills

# Or via npx (any skill-compatible agent)
npx skills add https://github.com/hyungyunlim/obsidian-social-archiver-skills

# Or copy manually into ~/.claude/skills, ~/.codex/skills, or ~/.opencode/skills
git clone https://github.com/hyungyunlim/obsidian-social-archiver-skills

The bundle lives at hyungyunlim/obsidian-social-archiver-skills. Each skill documents the full command catalog, the JSON response envelope, error codes, and the rules agents must follow (never echo tokens, stop on billing errors, respect rate limits).

Permission and ethics

Agents archive on your behalf. Only archive content you have permission to save — Social Archiver can only archive public posts and profiles. Private or login-walled content returns a terminal error with no bypass.

Troubleshooting

`social-archiver: command not found` on Windows

The Store package registers an App Execution Alias, and terminals only pick it up when they start. Close the terminal, open a new one, and try again. If it still fails, check Settings → Apps → Advanced app settings → App execution aliases and confirm the entry is on.

`social-archiver: command not found` on macOS or Linux

Add ~/.local/bin to your PATH and open a new terminal. If you installed through the desktop app, re-run Settings → Command line → Repair command-line tool.

`sa` runs the wrong tool

On some systems sa is a built-in accounting tool (/usr/sbin/sa). The installer never overwrites an sa you created yourself, and warns when another sa earlier on your PATH shadows it. Run social-archiver instead.

`AUTH_REQUIRED`

You are not signed in. Run social-archiver login, or set SOCIAL_ARCHIVER_TOKEN for headless use. For the Obsidian CLI, complete sign-in in plugin settings.

`social-archiver` commands missing from `obsidian help`

Enable Settings → General → Command line interface, update to the Obsidian 1.12.7+ installer, make sure the plugin is enabled in the vault, and restart Obsidian once.

`INSUFFICIENT_CREDITS` / `PAYWALL_REQUIRED`

Upgrade or restore in the mobile app with the same account, or apply a license key. The CLI cannot accept payment.

Command Line (CLI) ​

social-archiver CLI ​

Install ​

Sign in ​

Commands ​

Two ways to find things ​

Places and products in exported files ​

Examples ​

Premium features ​

Credits and limits ​

Obsidian Plugin CLI ​

Requirements ​

Usage ​

Coding Agents (Skills) ​

Troubleshooting ​

social-archiver: command not found on Windows ​

social-archiver: command not found on macOS or Linux ​

sa runs the wrong tool ​

AUTH_REQUIRED ​

social-archiver commands missing from obsidian help ​

INSUFFICIENT_CREDITS / PAYWALL_REQUIRED ​

Next Steps ​

Command Line (CLI)

`social-archiver` CLI

Install

Sign in

Commands

Two ways to find things

Places and products in exported files

Examples

Premium features

Credits and limits

Obsidian Plugin CLI

Requirements

Usage

Coding Agents (Skills)

Troubleshooting

`social-archiver: command not found` on Windows

`social-archiver: command not found` on macOS or Linux

`sa` runs the wrong tool

`AUTH_REQUIRED`

`social-archiver` commands missing from `obsidian help`

`INSUFFICIENT_CREDITS` / `PAYWALL_REQUIRED`

Next Steps