Command Line (CLI)

Social Archiver can be driven from the command line — useful for scripting, automation, and coding agents. There are two command-line surfaces, plus skill bundles for AI coding agents:

• Desktop sa CLI — a standalone tool bundled with the desktop app. It calls the Social Archiver server directly, so the desktop window does not need to be open.
• Obsidian plugin CLI — drives a running Obsidian vault through the obsidian binary. Use this when you want archives written into your vault as Markdown.
• Agent skills — installable skill bundles that teach coding agents (Claude Code, Codex, OpenCode, and others) how to use either CLI safely.

Which one should I use?

Use the desktop sa CLI for headless scripting and automation against your account. Use the Obsidian plugin CLI when the goal is Markdown notes in a specific vault and Obsidian is open. Both return the same JSON envelope.

Desktop sa CLI

The desktop app ships a self-contained command-line binary. No Node.js or separate download is required.

Install

1. Install the desktop app and sign in
2. Open Settings → Command line → Install 'sa' command
3. Run sa from any terminal

sa installs to ~/.local/bin. The full name social-archiver always works too; sa is just a short alias.

If sa is already taken

On some systems sa is a built-in accounting tool (/usr/sbin/sa). The installer never overwrites a sa you created yourself, and tells you if another sa earlier on your PATH still shadows it — in that case, run social-archiver instead. Add ~/.local/bin to your PATH if sa is not found.

Sign-in

If the desktop app is installed and signed in, the CLI borrows its account automatically — no separate login needed. For a headless machine or CI, set a token explicitly:

# Environment variable (CI)
export SOCIAL_ARCHIVER_TOKEN="<token>"

# Or an interactive device-code login
# (shows a code + QR to approve on your phone or a signed-in app)
sa login

# Remove stored credentials
sa logout

With no token, commands still run but report authenticated: false, and account-gated calls fail.

Commands

Every command returns a JSON envelope by default — { "ok": true, "data": … } or { "ok": false, "error": … }. Pass --format text for compact human-readable output.

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 archived posts (server-side, returns snippets)
bookmark	Move posts between Inbox and Archived (bulk)
subscribe	Subscribe to a public profile or feed
post	Post a local Markdown file to your timeline
share	Create a public share link for an archive
tags	List your tags
author-notes	Seed server author profiles from recent archives
export / tag / note / push	Pull archives to local Markdown, edit, and push changes back
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 the latest release

search, bookmark (with the export --archived filter), transcribe (and transcribe --doctor), ai-comment --run, and the always-on headless executor --watch were added in the latest desktop CLI update.

Run sa <command> --help for the flags on any command.

Examples

# Check readiness
sa status

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

# Search your archives
sa search --q "quantum computing" --limit 10

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

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

# Transcribe a video archive (queues a job for the desktop executor; poll it)
sa transcribe <archiveId> --mode download-and-transcribe
sa job --id="<jobId>"

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

# Offline demo, no account needed
sa status --host=mock

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 on 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, do not retry.

Obsidian Plugin CLI

The Obsidian plugin registers commands under the social-archiver namespace so you can drive the plugin without opening modals. Unlike the desktop 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:

# 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

Discover every command and its flags:

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 desktop sa CLI headlessly
• obsidian-social-archiver-cli — drive a running Obsidian vault

Install the published bundle:

# 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

sa: command not found

Add ~/.local/bin to your PATH, or run the full social-archiver. Re-run Settings → Command line → Install 'sa' command if needed.

sa runs the wrong tool

Another sa earlier on your PATH (such as /usr/sbin/sa) is shadowing it. Run social-archiver instead.

AUTH_REQUIRED

You are not signed in. Sign in to the desktop app, or set SOCIAL_ARCHIVER_TOKEN / run sa login 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 on the mobile app with the same account, or apply a license key. The CLI cannot accept payment.

Next Steps

• Desktop App
• AI Comments
• Transcription (Audio & Video)
• Subscriptions