# CLI reference

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](/docs/mcp). 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](/docs/agents) gives complete setup and examples. This reference is generated from the command definitions.

## login

Connect this device to a Sponge account.

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

Opens your browser to approve this device.

```sh
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.

```sh
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.

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

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

```sh
sponge sync --watch
```

Keep exchanging changes every 30 seconds.

```sh
sponge sync --no-saves
```

Skip capturing save requests queued from the web.

```sh
sponge sync --no-digest
```

Skip drafting summaries with the local model on this device.

```sh
sponge sync --checkpoint
```

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

```sh
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.

```sh
sponge saves
```

List open and recent save requests.

```sh
sponge saves add URL [--note TEXT]
```

Queue a URL for any connected device to capture.

```sh
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).

```sh
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.

```sh
sponge init
```

Create a private library.

## setup

Download one pinned runtime.

```sh
sponge setup --capture|--asr|--embedding
```

Download one pinned runtime.

```sh
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.

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



```sh
sponge add URL --archive [--wait]
```

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

```sh
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.

```sh
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.

```sh
sponge queue status
```

Show jobs and their states.

```sh
sponge queue cancel JOB
```

Cancel a queued or active job.

```sh
sponge queue retry JOB
```

Retry a failed job after resolving its cause.

```sh
sponge queue recover
```

Reconcile a stopped worker after cleanup.

## list

List saved and queued items.

```sh
sponge list [--limit N]
```

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

```sh
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.

```sh
sponge show ITEM [--format markdown|json]
```



| Flag | Value |
| --- | --- |
| `--format` | Required value when provided |

## asset

Write a verified asset to stdout.

```sh
sponge asset ITEM SHA
```

Write a verified asset to stdout.

## search

Search saved items.

```sh
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.

```sh
sponge refresh ITEM [--wait]
```

Capture a new revision.

```sh
sponge refresh ITEM --archive [--wait]
```

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

```sh
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.

```sh
sponge delete ITEM
```

Hide an item and remove it from search.

## index

Manage embedding generations.

```sh
sponge index create [--profile default]
```

Queue a new embedding generation.

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

Active (or given) generation coverage and pending inputs.

```sh
sponge index run
```

Drain queued embedding jobs.

```sh
sponge index rollback GENERATION
```

Reactivate a compatible complete generation.

```sh
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.

```sh
sponge doctor
```

Check library and runtime states.

## status

Overview of items, index, digests and queue.

```sh
sponge status
```

Overview of items, index, digests and queue.

## export

Export Markdown and local assets.

```sh
sponge export ITEM --output DIR
```

Export Markdown and local assets.

| Flag | Value |
| --- | --- |
| `--output` | Required value when provided |

## backup

Save a verified offline backup.

```sh
sponge backup --output FILE
```

Save a verified offline backup.

| Flag | Value |
| --- | --- |
| `--output` | Required value when provided |

## restore

Restore into a new private library.

```sh
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.

```sh
sponge gc --dry-run
```

Write a report of unreferenced blobs.

```sh
sponge gc --apply REPORT
```

Recheck and remove reported blobs.

```sh
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.

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

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

```sh
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.

```sh
sponge worker install [--language en]
```

Enable the optional background worker.

```sh
sponge worker status
```

Inspect the background worker.

```sh
sponge worker uninstall
```

Stop it and preserve the library.

```sh
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.

```sh
sponge update [--check]
```

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

```sh
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.

```sh
sponge browser setup [--hosts-dir DIR]
```

Connect the Sponge extension in Chrome and other Chromium browsers.

```sh
sponge browser status
```

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

```sh
sponge browser captcha on|off
```

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

```sh
sponge browser remove
```

Disconnect Sponge from every browser.

| Flag | Value |
| --- | --- |
| `--hosts-dir` | Required value when provided |

## import

Import existing captures.

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

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

```sh
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.

```sh
sponge visibility ITEM public|private|default
```

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

## title

Set or reset an item's title.

```sh
sponge title set ITEM TEXT
```

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

```sh
sponge title reset ITEM
```

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

## highlight

Anchor a verbatim quote.

```sh
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.

```sh
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.

```sh
sponge publish
```

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

```sh
sponge publish ITEM...
```

Publish items; your page updates on the next sync.

```sh
sponge publish --auto on|off
```

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

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

Show the public reading-list entries.

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

Write a signed static feed site with <sponge-list>.

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

```sh
sponge unpublish ITEM...
```

Remove items from your public page on the next sync.

## share

Share items at an unlisted link.

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

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

```sh
sponge share list [--all]
```

Show your shared links; --all includes revoked ones.

```sh
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.

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

Draft a digest with a local model server you started.

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

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

```sh
sponge digest ITEM
```

Show the current digest and its review state.

```sh
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.

```sh
sponge map
```

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

```sh
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.

```sh
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.

```sh
sponge help [COMMAND]
```

Show help for all commands or one.

## version

Print the version.

```sh
sponge --version
```

Print the version.