@1a35e1/sonar-cli 0.3.4 → 0.3.5

package/README.md

@@ -1,21 +1,14 @@
-# 🔊 Sonar (Preview)
+# 🔊 Sonar (Alpha)
 
-Experimental X CLI for OpenClaw 🦞 power users.
+Agent optimised [X](https://x.com) CLI for founders who want to stay ahead of the curve.
 
-Sonar matches interests from your X graph using various AI pipelines. We built this to automate our social intelligence.
+We got tired of missing important content in our feed and built Sonar to fix it.
 
-This cli has been designed to handover indexing and consumption to agents.
-
-* Pipe it into scripts,
-* automate your morning briefing,
-* Or just discover tweets you probably missed out on the web interface.
-
----
+Sonar matches your interests from your X network, filtering only relevant content from your graph using a variety of AI pipelines. We built this to automate our social intelligence at [@LighthouseGov](https://x.com/LighthouseGov).
 
 ## Get started
 
-* Register with `X` to get an API key from `https://sonar.8640p.info/`
-  * Learn more about which [scopes](#scopes) we request and why.
+* Login with your `X` account to obtain a [free API key](https://sonar.8640p.info/).
 
 Install the CLI
 
@@ -26,7 +19,7 @@ pnpm add -g @1a35e1/sonar-cli@latest
 Register your API key.
 
 ```sh
-# Make "SONAR_API_KEY" avaliable in your env
+# Ensure "SONAR_API_KEY" available in your env
 export SONAR_API_KEY=snr_xxxxx
 
 # or, manually register
@@ -52,54 +45,11 @@ sonar status --watch
 
 ## Scopes
 
-* We currently request `read:*` and `offline:processing` scopes based on <<https://docs.x.com/fundamentals/authentication/oauth-2-0/>. If there is an appite
-
-* So we can stay connected to your account until you revoke access.
-* Posts you’ve liked and likes you can view.
-* All the posts you can view, including posts from protected accounts.
-* Accounts you’ve muted.
-* Accounts you’ve blocked.
-* People who follow you and people who you follow.
-* All your Bookmarks.
-* Lists, list members, and list followers of lists you’ve created or are a member of, including private lists.
-* Any account you can view, including protected accounts.
-
-## Why Sonar exists
-
-Setting up your own social data pipeline is genuinely awful. You're looking at OAuth flows, rate limit math, pagination handling, webhook plumbing, deduplication logic, and a SQLite schema you'll regret in three weeks — before you've seen a single useful result. Most developers who try it abandon it halfway through.
-
-**Sonar skips all of that. Get actionalable data for OpenClaw in 15 minutes.**
-
-We believe your data is yours. If you want to go deeper than our platform allows — build your own models, run custom queries, pipe it into your own tooling — you can sync everything we have indexed on your behalf into a local SQLite database:
-
-```bash
-sonar sync              # sync data to ~/.sonar/data.db
-```
-
-No lock-in. If you outgrow us, you leave with your data intact.
-
-## Design philosophy
-
-There's a quiet shift happening in how developer tools are built.
+* We currently request `read:*` and `offline:processing` scopes
+* This allows us to read your feed, bookmarks, followers/following, and other account data to power our signal filtering and topic suggestions.
 
-In the early web2 era, API-first was a revelation. Stripe, Twilio, Sendgrid — companies that exposed clean REST contracts unlocked entire ecosystems of products built on top of them. The insight was simple: if your service has strong, reliable APIs, anyone can build anything. The interface didn't matter as much as the contract underneath.
-We're at a similar inflection point now, but the interface layer has changed dramatically.
 
-The goal for most workflows today is fire and forget — you define what you want, set it in motion, and let agents handle the execution. That only works if the underlying APIs are strong enough to support complex, long-running ETL pipelines without hand-holding. Sonar is built with that assumption: the API is the product, the CLI is just one interface into it.
-Which raises an interesting question about CLIs themselves. Traditionally a CLI was developer-first by definition — you were writing for someone comfortable with flags, pipes, and man pages. But if the primary consumer of your CLI is increasingly an agent (OpenClaw, a cron job, an LLM with tool access), the design principles shift:
-
-Output should be machine-readable by default. Every command has a --json flag. Agents don't parse card renders.
-Commands should be composable. Small, single-purpose commands that pipe cleanly into each other are more useful to an agent than monolithic workflows.
-
-Side effects should be explicit. An agent calling index --force should know exactly what it's triggering. No surprises.
-Errors should be structured. A human reads an error message. An agent needs to know whether to retry, skip, or escalate.
-
-The CLI still needs to work well for humans — interactive mode, card renders, readable output — but those are progressive enhancements on top of a foundation built for automation. Design for the agent, polish for the human.
-This is what API-first looks like in the agentic era: strong contracts at the service layer, composable interfaces at the CLI layer, and a clear separation between the two.
-
----
-
-## What you can do with it
+## Use cases
 
 ### Morning briefing in one command
 
@@ -174,11 +124,21 @@ sonar --no-interactive   # disable for scripting
 
 Mark suggestions as skip, later, or archive — keyboard-driven.
 
+### Build your own filters and dashboards (WIP)
+
+Download your data and build your own tools on top of it.
+
+```bash
+sonar sync # sync data to ~/.sonar/data.db
+```
+
+No lock-in. If you outgrow us, you leave with your data intact.
+
 ---
 
-## How Sonar finds signal
+## How Sonar finds relevant content
 
-Sonar surfaces relevant content from your X social graph — the people you follow and who follow you. Your network is already a curated signal layer. Sonar's job is to surface what's moving through that graph before it reaches mainstream feeds.
+Sonar surfaces relevant content from your immediate network — the people you follow and who follow you. Your network is already a curated signal layer. Sonar's job is to surface what's moving through that graph before it reaches mainstream feeds.
 
 What this means in practice:
 
@@ -187,67 +147,6 @@ What this means in practice:
 * Bookmarking and liking content improves your recommendations over time
 * Topics sharpen what Sonar surfaces within your graph
 
----
-
-## Pair with OpenClaw
-
-[OpenClaw](https://github.com/openclaw/openclaw) is a local-first autonomous AI agent that runs on your machine and talks to you through WhatsApp, Telegram, Discord, Slack, or iMessage. It can execute shell commands, run on a schedule, and be extended with custom skills.
-
-Sonar + OpenClaw is a natural stack: **Sonar handles the signal filtering and curation, OpenClaw handles delivery and action.** Together they turn your social feed into an ambient intelligence layer you don't have to babysit.
-
-### Morning briefing delivered to your phone
-
-Set up a cron job in OpenClaw to run your Sonar digest every morning:
-
-```
-# In OpenClaw: schedule a daily 8am briefing
-"Every morning at 8am, run `sonar --hours 8 --json` and summarize the top 5 posts for me"
-```
-
-OpenClaw will execute the CLI, pass the JSON output to your LLM, and send a clean summary straight to your phone.
-
-### Ask your feed questions in natural language
-
-Because `--json` makes Sonar output composable, OpenClaw can reason over it:
-
-```
-# Example prompts you can send OpenClaw via WhatsApp:
-"What's the most discussed topic in my Sonar feed today?"
-"Did anyone in my feed mention Uniswap V4 in the last 48 hours?"
-"Summarize my Sonar suggestions"
-```
-
-### Get alerted when a topic spikes
-
-Use OpenClaw's Heartbeat to watch for signal surges:
-
-```
-# OpenClaw cron: check every 2 hours
-"Run `sonar --hours 2 --json` — if there are more than 10 posts about
-'token launchpad' or 'LVR', send me a Telegram alert with the highlights"
-```
-
-### Build a Sonar skill for OpenClaw
-
-Wrap Sonar as a reusable OpenClaw skill:
-
-```typescript
-// skills/sonar.ts
-export async function getSuggestions(hours = 12) {
-  const { stdout } = await exec(`sonar --hours ${hours} --json`);
-  return JSON.parse(stdout);
-}
-
-export async function getStatus() {
-  const { stdout } = await exec(`sonar status --json`);
-  return JSON.parse(stdout);
-}
-```
-
-Once registered, OpenClaw can call these tools autonomously whenever it decides they're relevant.
-
----
-
 ## Setup
 
 ### Prerequisites
@@ -317,7 +216,9 @@ Press `q` to quit follow mode.
 sonar topics                         # list all topics
 sonar topics --json                  # JSON output
 sonar topics add "AI agents"         # add a topic
-sonar topics edit --id <id> --name "New Name"
+sonar topics view <id>               # view a topic
+sonar topics edit <id> --name "New Name"
+sonar topics delete <id>             # delete a topic
 ```
 
 #### AI-powered topic suggestions
@@ -346,7 +247,7 @@ sonar status --watch                 # poll every 2s
 ```bash
 sonar skip --id <suggestion_id>      # skip a suggestion
 sonar later --id <suggestion_id>     # save for later
-sonar archive                        # archive old suggestions
+sonar archive --id <suggestion_id>   # archive a suggestion
 ```
 
 ### Config
@@ -356,30 +257,30 @@ sonar config                         # show current config
 sonar config setup key=<API_KEY>     # set API key
 ```
 
-### Local Data
+### Sync
 
 ```bash
-sonar sync                           # sync data to local SQLite
+sonar sync bookmarks                 # sync bookmarks to local SQLite
 ```
 
 ---
 
 ## Environment Variables
 
-| Variable | Required | Purpose |
-|---|---|---|
-| `SONAR_API_KEY` | Yes | Auth token from [sonar.8640p.info](https://sonar.8640p.info/) |
-| `SONAR_API_URL` | No | GraphQL endpoint (default: production API) |
-| `SONAR_MAX_RETRIES` | No | Max retry attempts on transient failures (default: 3, 0 to disable) |
-| `OPENAI_API_KEY` | For `topics suggest` | Required when using OpenAI vendor for AI suggestions |
-| `ANTHROPIC_API_KEY` | For `topics suggest` | Required when using Anthropic vendor for AI suggestions |
+| Variable            | Required             | Purpose                                                             |
+| ------------------- | -------------------- | ------------------------------------------------------------------- |
+| `SONAR_API_KEY`     | Yes                  | Auth token from [sonar.8640p.info](https://sonar.8640p.info/)       |
+| `SONAR_API_URL`     | No                   | GraphQL endpoint (default: production API)                          |
+| `SONAR_MAX_RETRIES` | No                   | Max retry attempts on transient failures (default: 3, 0 to disable) |
+| `OPENAI_API_KEY`    | For `topics suggest` | Required when using OpenAI vendor for AI suggestions                |
+| `ANTHROPIC_API_KEY` | For `topics suggest` | Required when using Anthropic vendor for AI suggestions             |
 
 ## Local Files
 
-| Path | Contents |
-|---|---|
+| Path                   | Contents                     |
+| ---------------------- | ---------------------------- |
 | `~/.sonar/config.json` | Token, API URL, CLI defaults |
-| `~/.sonar/data.db` | Local synced SQLite database |
+| `~/.sonar/data.db`     | Local synced SQLite database |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1a35e1/sonar-cli",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "X social graph CLI for signal filtering and curation",
   "type": "module",
   "bin": {