CLI reference

Markdown · Agent index

Use sponge COMMAND --help for the command’s syntax and constraints. Every command accepts --library /absolute/path, --json, and --debug. The default library is ~/.local/share/sponge.

For ordinary CLI commands, --json success writes an object with ok: true to stdout. Failures write categorical JSON to stderr. The long-running sponge mcp server uses a JSON-RPC message stream instead; see the MCP reference. Exit statuses are zero for success, one for failure, two for invalid input, three for partial content, four for action required, and 130 for cancellation.

Use a coding agent gives complete setup and examples. This reference is generated from the command definitions.

login

Connect this device to a Sponge account.

sponge login [--label NAME] [--server ORIGIN] [--no-wait] [--no-browser]

Opens your browser to approve this device.

sponge login --finish

Finish a previously started device sign-in.

Flag	Value
--label	Required value when provided
--server	Required value when provided
--no-wait	Switch
--no-browser	Switch
--finish	Switch

logout

Revoke this device and remove its saved sign-in.

sponge logout [--local]

Sign out; –local forgets an offline device without revoking it.

Flag	Value
--local	Switch

sync

Sync your private library with your Sponge account.

sponge sync [--join] [--dry-run]

Exchange verified library changes; –join requires an empty library.

sponge sync --watch

Keep exchanging changes every 30 seconds.

sponge sync --no-saves

Skip capturing save requests queued from the web.

sponge sync --no-digest

Skip drafting summaries with the local model on this device.

sponge sync --checkpoint

Also upload a checkpoint now, so new devices start from it.

sponge sync status

Show this device and cloud storage.

Flag	Value
--join	Switch
--dry-run	Switch
--watch	Switch
--no-saves	Switch
--no-digest	Switch
--checkpoint	Switch

saves

List, queue and capture save requests from your Sponge account.

sponge saves

List open and recent save requests.

sponge saves add URL [--note TEXT]

Queue a URL for any connected device to capture.

sponge saves run [--limit 5]

Claim queued requests, capture them here and sync them back.

Flag	Value
--note	Required value when provided
--limit	Required value when provided

mcp

Serve the library to AI agents over MCP (stdio).

sponge mcp

Run a Model Context Protocol server on stdin/stdout for Claude Code, Codex and other agents.

Tools: search_library, list_items, read_item, save_url, queue_save, add_highlight, add_comment, sync.

Claude Code: claude mcp add sponge – sponge mcp

Codex (~/.codex/config.toml): [mcp_servers.sponge] command = “sponge” args = [“mcp”]

Other clients (JSON): { “mcpServers”: { “sponge”: { “command”: “sponge”, “args”: [“mcp”] } } }

Add –library /absolute/path to the args to serve a library other than the default.

init

Create a private library.

sponge init

Create a private library.

setup

Download one pinned runtime.

sponge setup --capture|--asr|--embedding

Download one pinned runtime.

sponge setup --digest [--digest-model ALIAS] [--model-file GGUF]

Install the local digest model; –model-file copies a GGUF you already have.

Flag	Value
--capture	Switch
--asr	Switch
--embedding	Switch
--digest	Switch
--digest-model	Required value when provided
--model-file	Required value when provided

add

Save an article, PDF or media source.

sponge add URL_OR_PDF [--kind article|pdf|media] [--connection ID] [--wait]

sponge add URL --archive [--wait]

Capture the newest Internet Archive copy of a dead or paywalled page.

sponge add URL --browser [--wait]

Capture through your browser and its sign-ins (sponge browser setup).

Flag	Value
--connection	Required value when provided
--kind	Required value when provided
--wait	Switch
--archive	Switch
--browser	Switch
--language	Required value when provided
--force-local	Switch
--allow-private-network	Switch

run

Process queued work sequentially.

sponge run --drain

Process queued captures, indexes and local digests sequentially.

Flag	Value
--drain	Switch
--language	Required value when provided
--force-local	Switch
--allow-private-network	Switch

queue

Inspect and manage jobs.

sponge queue status

Show jobs and their states.

sponge queue cancel JOB

Cancel a queued or active job.

sponge queue retry JOB

Retry a failed job after resolving its cause.

sponge queue recover

Reconcile a stopped worker after cleanup.

list

List saved and queued items.

sponge list [--limit N]

List saved and queued items; –limit N lists only the N newest, newest first.

sponge list --short

Web articles saved with under 200 words: paywalls, error pages, script-only pages.

Flag	Value
--short	Switch
--limit	Required value when provided

At a terminal list shows the 50 newest items, newest first, with the day each was saved. Piped or with –json it lists every item, oldest first, unless –limit asks for the newest.

show

Show an item as Markdown or JSON.

sponge show ITEM [--format markdown|json]

Flag	Value
--format	Required value when provided

asset

Write a verified asset to stdout.

sponge asset ITEM SHA

Write a verified asset to stdout.

search

Search saved items.

sponge search QUERY [--mode hybrid|lexical] [--profile default] [--limit 20]

Flag	Value
--mode	Required value when provided
--limit	Required value when provided
--profile	Required value when provided

refresh

Capture a new revision.

sponge refresh ITEM [--wait]

Capture a new revision.

sponge refresh ITEM --archive [--wait]

Capture the newest Internet Archive copy instead of the live page.

sponge refresh ITEM --browser [--wait]

Capture through your browser and its sign-ins.

Flag	Value
--wait	Switch
--archive	Switch
--browser	Switch
--language	Required value when provided
--force-local	Switch
--allow-private-network	Switch

delete

Hide an item and remove it from search.

sponge delete ITEM

Hide an item and remove it from search.

index

Manage embedding generations.

sponge index create [--profile default]

Queue a new embedding generation.

sponge index status [GENERATION] [--profile default]

Active (or given) generation coverage and pending inputs.

sponge index run

Drain queued embedding jobs.

sponge index rollback GENERATION

Reactivate a compatible complete generation.

sponge index prune [--keep 1] [--dry-run] [--vacuum]

Delete vectors of retired generations.

Flag	Value
--profile	Required value when provided
--keep	Required value when provided
--dry-run	Switch
--vacuum	Switch

doctor

Check library and runtime states.

sponge doctor

Check library and runtime states.

status

Overview of items, index, digests and queue.

sponge status

Overview of items, index, digests and queue.

export

Export Markdown and local assets.

sponge export ITEM --output DIR

Export Markdown and local assets.

Flag	Value
--output	Required value when provided

backup

Save a verified offline backup.

sponge backup --output FILE

Save a verified offline backup.

Flag	Value
--output	Required value when provided

restore

Restore into a new private library.

sponge restore FILE --into NEW_DIR

Restore into a new private library.

Flag	Value
--into	Required value when provided

gc

Collect unreferenced blobs and superseded runtimes.

sponge gc --dry-run

Write a report of unreferenced blobs.

sponge gc --apply REPORT

Recheck and remove reported blobs.

sponge gc --runtimes [--dry-run]

Remove superseded runtimes, models and worker journals.

Flag	Value
--dry-run	Switch
--apply	Required value when provided
--runtimes	Switch

images

Retire stored images: show them from their web addresses instead.

sponge images retire --dry-run [--urls MAP]

Write a report of stored images and the address each will use.

sponge images retire --apply REPORT

Remove those images here; sync removes them everywhere else.

Flag	Value
--dry-run	Switch
--apply	Required value when provided
--urls	Required value when provided

MAP is a JSON object from image sha256 to its https address. An image with no address shows its alt text. Text, notes and summaries stay. Make a backup first: removed images cannot be restored from Sponge.

worker

Manage the optional background worker.

sponge worker install [--language en]

Enable the optional background worker.

sponge worker status

Inspect the background worker.

sponge worker uninstall

Stop it and preserve the library.

sponge worker foreground [--language en]

Keep processing queued work on macOS or Linux.

Flag	Value
--language	Required value when provided
--force-local	Switch

update

Install the latest Sponge release.

sponge update [--check]

Install the latest release with npm (–check only reports it).

sponge update auto on|off

Install releases daily from the worker or one-off syncs (default on).

Flag	Value
--check	Switch

Updates use the npm that installed Sponge globally, then reinstall installed background workers. The worker checks at most once a day and leaves a release that changes native runtimes to you. Without a worker, a one-off sync runs the same check when no other Sponge process is running. update auto off works everywhere; SPONGE_NO_AUTO_UPDATE=1 works for one-off syncs, foreground and systemd workers. Restart other running Sponge processes (sync –watch, mcp) after an update.

browser

Capture through your own browser and its sign-ins.

sponge browser setup [--hosts-dir DIR]

Connect the Sponge extension in Chrome and other Chromium browsers.

sponge browser status

Show which browsers are set up and whether the extension is connected.

sponge browser captcha on|off

Enable or disable entirely local reCAPTCHA image solving in capture tabs.

sponge browser remove

Disconnect Sponge from every browser.

Flag	Value
--hosts-dir	Required value when provided

import

Import existing captures.

sponge import MANIFEST [--apply|--dry-run] [--limit 20] [--offset 0]

Preview (the default) or import existing Wordcell captures, a page at a time.

sponge import jungle DIR [--apply|--dry-run] [--limit 1000] [--offset 0]

Preview or import Jungle Reading notes, their captures and published state.

Flag	Value
--apply	Switch
--dry-run	Switch
--limit	Required value when provided
--offset	Required value when provided

visibility

Set whether an item is public.

sponge visibility ITEM public|private|default

Publish, unpublish, or restore the default (private).

title

Set or reset an item’s title.

sponge title set ITEM TEXT

Use TEXT as the title; refresh and import never change it.

sponge title reset ITEM

Restore the default: the captured title (a local scan takes its import note title).

highlight

Anchor a verbatim quote.

sponge highlight ITEM TEXT [--note BODY] [--occurrence N]

Anchor a verbatim quote.

Flag	Value
--note	Required value when provided
--occurrence	Required value when provided

comment

Comment on an item or reply.

sponge comment ITEM BODY [--on ANNOTATION]

Comment on an item or reply.

Flag	Value
--on	Required value when provided

publish

Publish items on your public page, or show what is public.

sponge publish

Show your public page, what is public, and whether new saves publish.

sponge publish ITEM...

Publish items; your page updates on the next sync.

sponge publish --auto on|off

Publish new saves from public web pages automatically, or stop.

sponge publish --dry-run [--min-age-days N]

Show the public reading-list entries.

sponge publish --output DIR [--title T] [--base-url https://...] [--min-age-days N]

Write a signed static feed site with .

Flag	Value
--dry-run	Switch
--output	Required value when provided
--min-age-days	Required value when provided
--title	Required value when provided
--base-url	Required value when provided
--auto	Required value when provided

unpublish

Make items private again.

sponge unpublish ITEM...

Remove items from your public page on the next sync.

share

Share items at an unlisted link.

sponge share ITEM... [--title T] [--highlights]

Create a link to these items, with their highlights if asked.

sponge share list [--all]

Show your shared links; –all includes revoked ones.

sponge share revoke ID

Take a shared link down on the next sync.

Flag	Value
--title	Required value when provided
--highlights	Switch
--all	Switch

digest

Draft or show an item digest.

sponge digest ITEM --endpoint http://127.0.0.1:PORT --model NAME [--check-support]

Draft a digest with a local model server you started.

sponge digest ITEM --draft [--model ALIAS]

Draft a digest with the model from sponge setup --digest.

sponge digest ITEM

Show the current digest and its review state.

sponge digest --auto on|off

Digest new captures in the background with the worker, or stop.

Flag	Value
--endpoint	Required value when provided
--model	Required value when provided
--check-support	Switch
--draft	Switch
--auto	Required value when provided

map

Show or build the library map of concepts across digests.

sponge map

Show the library map: when it was built, its size, and whether a rebuild is due.

sponge map build [--force]

Build it now with the local embedding and digest models.

Flag	Value
--force	Switch

The map groups ideas from accepted digests into named concepts. The worker rebuilds it when at least 5 accepted digests changed, or any changed a day ago, at most every 6 hours. Only the newest map syncs. Building needs sponge setup --digest and the embedding model; it waits if another model server is running.

review

Accept or reject digest fields.

sponge review DIGEST --accept SPEC --reject SPEC

Review fields: all, gist, idea:N, quote:N.M, as sponge digest ITEM labels them.

Flag	Value
--accept	Required value when provided
--reject	Required value when provided

help

Show help for all commands or one.

sponge help [COMMAND]

Show help for all commands or one.

version

Print the version.

sponge --version

Print the version.