@1a35e1/sonar-cli 0.2.1 → 0.3.4

package/README.md

@@ -33,21 +33,19 @@ export SONAR_API_KEY=snr_xxxxx
 sonar config setup key=<YOUR_API_KEY>
 ```
 
-View your account to ensure evrything works.
+View your account status:
 
 ```sh
-sonar account
+sonar status
 ```
 
-Ingest your first `tweets` and check to `monitor` progress.
+Run your first refresh to index tweets and generate suggestions:
 
-> The first time this you run this command it will take some time.
+> The first time you run this it will take some time.
 
 ```sh
-sonar ingest tweets
-
-sonar monitor
-sonar monitor --watch
+sonar refresh
+sonar status --watch
 ```
 
 ---
@@ -72,12 +70,10 @@ Setting up your own social data pipeline is genuinely awful. You're looking at O
 
 **Sonar skips all of that. Get actionalable data for OpenClaw in 15 minutes.**
 
-We believe your data is yours. So you want to go deeper than our platform allows — build your own models, run custom queries, pipe it into your own tooling — you can download everything we have indexed on your behalf into a local SQLite database and do whatever you want with it:
+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
-pnpm run cli -- data download   # full snapshot → ~/.sonar/data.db
-pnpm run cli -- data sync       # incremental updates
-pnpm run cli -- data sql        # drop into a sqlite3 shell
+sonar sync              # sync data to ~/.sonar/data.db
 ```
 
 No lock-in. If you outgrow us, you leave with your data intact.
@@ -110,91 +106,86 @@ This is what API-first looks like in the agentic era: strong contracts at the se
 Pull everything relevant that happened while you slept:
 
 ```bash
-pnpm run cli -- feed --hours 8 --render card
-pnpm run cli -- inbox --status inbox
+sonar feed --hours 8
 ```
 
-### Track a topic you care about — right now
+### Stream your feed in real time
 
-Create a new interest from a plain English prompt and get content immediately:
+Watch for new items as they appear:
 
 ```bash
-pnpm run cli -- interests create \
-  --from-prompt "I want to follow AI evals and agent infrastructure"
-
-pnpm run cli -- index suggestions --days 1
-pnpm run cli -- feed --hours 24
+sonar feed --follow                      # visual cards, polls every 30s
+sonar feed --follow --json | jq .score   # NDJSON stream for agents
 ```
 
-Sonar generates keywords and topics from your prompt, kicks off indexing, and your feed updates with relevant posts.
+### Discover new topics with AI
 
-### Build a scriptable news digest
-
-Combine `--json` output with `jq` to pipe Sonar content wherever you want:
+Let Sonar suggest topics based on your interests and feed:
 
 ```bash
-# Get today's top feed items as JSON
-pnpm run cli -- feed --hours 24 --json | jq '.[] | {author, text, url}'
-
-# Summarize your inbox with an LLM
-pnpm run cli -- inbox --json | jq '.[].text' | your-summarizer-script
+sonar topics suggest                 # interactive accept/reject
+sonar topics suggest --count 3       # just 3 suggestions
 ```
 
-### Keep your local data fresh and queryable
+### Track a topic you care about
 
-Download a full SQLite snapshot of your Sonar data and query it directly:
+Add a topic, then refresh:
 
 ```bash
-pnpm run cli -- data download
-pnpm run cli -- data sql
-# Now you have a full sqlite3 shell — write any query you want
+sonar topics add "AI agents"
+sonar refresh
+sonar feed --hours 24
 ```
 
-Run incremental syncs on a cron to keep it current:
+Sonar rebuilds your social graph, indexes recent tweets, and generates suggestions matched against your topics and interest profile.
+
+### Build a scriptable news digest
+
+Combine `--json` output with `jq` to pipe Sonar content wherever you want:
 
 ```bash
-# crontab: sync every 30 minutes
-*/30 * * * * cd /your/project && pnpm run cli -- data sync
+# Get today's feed as JSON
+sonar feed --hours 24 --json | jq '.[] | {author: .tweet.user.username, text: .tweet.text}'
+
+# Summarize with an LLM
+sonar feed --json | jq '.[].tweet.text' | your-summarizer-script
+
+# Stream high-score items to a file
+sonar feed --follow --json | jq --unbuffered 'select(.score > 0.7)' >> highlights.jsonl
 ```
 
-### Interactive triage
+### Monitor the pipeline
 
-Work through your inbox without leaving the terminal:
+Watch the queue in real time while refresh runs:
 
 ```bash
-pnpm run cli -- inbox --interactive
-pnpm run cli -- feed --interactive
+sonar refresh
+sonar status --watch
 ```
 
-Mark suggestions as read, skip, archive, or save for later — keyboard-driven.
-
-### Monitor indexing jobs
+### Interactive triage
 
-Watch the queue in real time while you trigger a full re-index:
+Work through suggestions without leaving the terminal:
 
 ```bash
-pnpm run cli -- index          # trigger all jobs
-pnpm run cli -- index status --watch   # watch until complete
+sonar                    # interactive triage is on by default
+sonar --no-interactive   # disable for scripting
 ```
 
----
-
-## What Sonar doesn't do
+Mark suggestions as skip, later, or archive — keyboard-driven.
 
-Sonar is **not a global search engine**. It won't crawl the entire internet or index trending posts from people you've never heard of.
+---
 
-Instead, it searches within your social graph — your followers and the people you follow — up to **2 degrees of separation**. That's it. This is an intentional constraint, not a limitation we're working around.
+## How Sonar finds signal
 
-The reason is practical: API rate limits make broad crawling impossible at any useful refresh frequency. But the reason it works is more interesting — **the people in your network are already a curated signal layer**. The accounts you follow, and the accounts they follow, are a surprisingly high-quality filter for what's relevant to your domain. Sonar's job is to surface what's moving through that graph before it reaches mainstream feeds.
+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.
 
 What this means in practice:
 
 * Results reflect your network's attention, not global virality
-* You won't see noise from accounts you have no connection to
 * The feed gets more useful the more intentional you are about who you follow
-* Adding interests with specific keywords and topics sharpens what Sonar surfaces *within* that graph
-
-If you want global trend monitoring, tools like Brandwatch or Twitter's native search are better fits. Sonar is for developers who want a focused, low-noise signal from a network they've already curated.
+* Bookmarking and liking content improves your recommendations over time
+* Topics sharpen what Sonar surfaces within your graph
 
 ---
 
@@ -206,71 +197,54 @@ Sonar + OpenClaw is a natural stack: **Sonar handles the signal filtering and cu
 
 ### Morning briefing delivered to your phone
 
-Set up a cron job in OpenClaw to run your Sonar digest and pipe it back to you on Telegram every morning:
+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 feed --hours 8 --json` and summarize the top 5 posts for me"
+"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 — no dashboard to open.
+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 conversationally:
+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 unread Sonar inbox"
-```
-
-Wire it up once as an OpenClaw skill and your feed becomes queryable from any messaging app.
-
-### Triage your inbox hands-free
-
-Combine OpenClaw's scheduling with Sonar's inbox API to automatically mark low-signal suggestions:
-
-```bash
-# Shell script you can hand to OpenClaw as a scheduled skill
-sonar inbox --json | \
-  jq '[.[] | select(.score < 0.4) | .id]' | \
-  xargs -I{} sonar inbox skip {}
+"Summarize my Sonar suggestions"
 ```
 
-Run this nightly and your inbox stays clean without manual triage.
-
 ### Get alerted when a topic spikes
 
-Use OpenClaw's Heartbeat (scheduled wake-up) to watch for signal surges and notify you:
+Use OpenClaw's Heartbeat to watch for signal surges:
 
 ```
 # OpenClaw cron: check every 2 hours
-"Run `sonar feed --hours 2 --json` — if there are more than 10 posts about
+"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"
 ```
 
-Effectively a custom Google Alert, but filtered through your actual interest graph.
-
 ### Build a Sonar skill for OpenClaw
 
-The cleanest integration is wrapping Sonar as a reusable OpenClaw skill. Drop a skill file in your OpenClaw workspace:
+Wrap Sonar as a reusable OpenClaw skill:
 
 ```typescript
 // skills/sonar.ts
-export async function getFeed(hours = 12) {
-  const { stdout } = await exec(`sonar feed --hours ${hours} --json`);
+export async function getSuggestions(hours = 12) {
+  const { stdout } = await exec(`sonar --hours ${hours} --json`);
   return JSON.parse(stdout);
 }
 
-export async function getInbox() {
-  const { stdout } = await exec(`sonar inbox --json`);
+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 — no manual prompting required.
+Once registered, OpenClaw can call these tools autonomously whenever it decides they're relevant.
 
 ---
 
@@ -280,111 +254,112 @@ Once registered, OpenClaw can call these tools autonomously whenever it decides
 
 * Node.js 20+
 * `pnpm`
-* A Sonar API key from [sonar.sh/account](https://sonar.sh/account?tab=api-keys)
-* Optional: `sqlite3` CLI (only needed for `data sql`)
+* A Sonar API key from [sonar.8640p.info](https://sonar.8640p.info/)
 
 ### Install and authenticate
 
 ```bash
-pnpm install
+pnpm add -g @1a35e1/sonar-cli@latest
 
 export SONAR_API_KEY="your_api_key_here"
-pnpm run cli -- init
+sonar config setup key=<YOUR_API_KEY>
 ```
 
-`init` writes your config to `~/.sonar/config.json`. If `SONAR_API_KEY` is set in your environment, it always takes precedence.
-
 Verify it works:
 
 ```bash
-pnpm run cli -- account
-pnpm run cli -- interests
+sonar status
+sonar topics
 ```
 
 ---
 
 ## Command Reference
 
-### Account & Config
+### Default — triage suggestions
+
+```bash
+sonar                                # interactive triage (default)
+sonar --hours 24                     # widen time window
+sonar --days 3                       # last 3 days
+sonar --kind bookmarks               # default | bookmarks | followers | following
+sonar --render table --limit 50      # table layout
+sonar --json                         # raw JSON output
+sonar --no-interactive               # disable interactive mode
+```
+
+### Feed — read-only view
+
+```bash
+sonar feed                           # read-only feed (last 12h, limit 20)
+sonar feed --hours 48 --limit 50     # widen window
+sonar feed --kind bookmarks          # bookmarks | followers | following
+sonar feed --render table            # table layout
+sonar feed --json | jq .             # pipe to jq
+```
+
+#### Streaming with --follow
+
+Poll for new items continuously and stream them to your terminal or another process:
 
 ```bash
-pnpm run cli -- account              # plan, usage, suggestion counters
-pnpm run cli -- config               # show current config
-pnpm run cli -- config set vendor anthropic      # or openai
-pnpm run cli -- config set feed-render card      # or table
-pnpm run cli -- config set feed-width 100
+sonar feed --follow                  # poll every 30s, visual cards
+sonar feed --follow --interval 10    # poll every 10s
+sonar feed --follow --json           # NDJSON stream (one JSON per line)
+sonar feed --follow --json | jq --unbuffered '.score'
 ```
 
-### Interests
+Press `q` to quit follow mode.
+
+### Topics
 
 ```bash
-pnpm run cli -- interests                          # list all
-pnpm run cli -- interests --json                   # JSON output
-
-# Create manually
-pnpm run cli -- interests create \
-  --name "Rust Systems" \
-  --description "Rust, compilers, and systems tooling" \
-  --keywords "rust,cargo,wasm" \
-  --topics "systems programming,performance"
-
-# Create from a natural language prompt (requires OPENAI_API_KEY or ANTHROPIC_API_KEY)
-pnpm run cli -- interests create \
-  --from-prompt "I want to follow AI evals and agent infra"
-
-# Update
-pnpm run cli -- interests update --id <id> --name "New Name"
-pnpm run cli -- interests update --id <id> --add-keywords "mcp,langgraph"
-pnpm run cli -- interests update --id <id> --remove-topics "old-topic"
+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"
 ```
 
-### Feed
+#### AI-powered topic suggestions
+
+Let Sonar suggest new topics based on your existing interests and recent feed:
 
 ```bash
-pnpm run cli -- feed                          # last 12h, limit 20, card render
-pnpm run cli -- feed --hours 24
-pnpm run cli -- feed --days 3
-pnpm run cli -- feed --kind bookmarks         # default | bookmarks | followers | following
-pnpm run cli -- feed --render table --limit 50
-pnpm run cli -- feed --interactive
-pnpm run cli -- feed --json
+sonar topics suggest                 # interactive — y/n/q per suggestion
+sonar topics suggest --count 3       # limit to 3 suggestions
+sonar topics suggest --vendor anthropic  # use Anthropic instead of OpenAI
+sonar topics suggest --json          # raw suggestions as JSON
 ```
 
-### Inbox
+Requires `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` depending on vendor.
+
+### Pipeline
 
 ```bash
-pnpm run cli -- inbox                         # list inbox suggestions
-pnpm run cli -- inbox --all
-pnpm run cli -- inbox --status inbox --limit 50
-pnpm run cli -- inbox --interactive
-pnpm run cli -- inbox --json
-
-pnpm run cli -- inbox read --id <suggestion_id>
-pnpm run cli -- inbox skip --id <suggestion_id>
-pnpm run cli -- inbox later --id <suggestion_id>
-pnpm run cli -- inbox archive --id <suggestion_id>
+sonar refresh                        # full pipeline: graph → tweets → suggestions
+sonar status                         # account status, queue activity
+sonar status --watch                 # poll every 2s
 ```
 
-### Indexing
+### Triage
 
 ```bash
-pnpm run cli -- reindex                       # run all jobs
-pnpm run cli -- reindex tweets
-pnpm run cli -- reindex graph
-pnpm run cli -- reindex graph --force
-pnpm run cli -- reindex suggestions --days 1
-pnpm run cli -- reindex bookmarks
-pnpm run cli -- reindex status
-pnpm run cli -- reindex status --watch
+sonar skip --id <suggestion_id>      # skip a suggestion
+sonar later --id <suggestion_id>     # save for later
+sonar archive                        # archive old suggestions
+```
+
+### Config
+
+```bash
+sonar config                         # show current config
+sonar config setup key=<API_KEY>     # set API key
 ```
 
 ### Local Data
 
 ```bash
-pnpm run cli -- data download     # full download → ~/.sonar/data.db
-pnpm run cli -- data sync         # incremental sync
-pnpm run cli -- data path         # print DB path
-pnpm run cli -- data sql          # open sqlite3 shell
+sonar sync                           # sync data to local SQLite
 ```
 
 ---
@@ -393,13 +368,11 @@ pnpm run cli -- data sql          # open sqlite3 shell
 
 | Variable | Required | Purpose |
 |---|---|---|
-| `SONAR_API_KEY` | Yes (unless saved by `init`) | Auth token |
-| `SONAR_API_URL` | No | GraphQL endpoint (default: `http://localhost:8000/graphql`) |
-| `SONAR_AI_VENDOR` | No | AI vendor for prompt generation (`openai` or `anthropic`) |
-| `SONAR_FEED_RENDER` | No | Default render style (`card` or `table`) |
-| `SONAR_FEED_WIDTH` | No | Default card width |
-| `OPENAI_API_KEY` | Sometimes | Required for OpenAI-powered `--from-prompt` |
-| `ANTHROPIC_API_KEY` | Sometimes | Required for Anthropic-powered `--from-prompt` |
+| `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
 
@@ -410,13 +383,25 @@ pnpm run cli -- data sql          # open sqlite3 shell
 
 ---
 
+## Drift Prevention Checks
+
+```bash
+# Run all drift checks (surface/docs/data/schema)
+pnpm drift:check
+
+# Refresh committed command snapshot after intentional command changes
+pnpm drift:surface:update
+```
+
+`drift:schema:check` validates GraphQL documents against the live schema.
+Locally, it skips when offline; in CI (`CI=true`) it is enforced.
+
+---
+
 ## Troubleshooting
 
-**`No token found. Set SONAR_API_KEY or run: sonar init`**
-Set `SONAR_API_KEY` in your environment, then run `pnpm run cli -- init`.
+**`No token found. Set SONAR_API_KEY or run: sonar config setup`**
+Set `SONAR_API_KEY` in your environment or run `sonar config setup key=<YOUR_KEY>`.
 
 **`Unable to reach server, please try again shortly.`**
-Check `SONAR_API_URL`, your network, and API availability.
-
-**`OPENAI_API_KEY is not set` / `ANTHROPIC_API_KEY is not set`**
-Set the key for your chosen vendor before using `--from-prompt` or interactive reply generation.
+Check your network connection and API availability. The CLI automatically retries transient failures (network errors, 5xx) up to 3 times with exponential backoff. Use `--debug` to see retry attempts. Set `SONAR_MAX_RETRIES=0` to disable retries.

package/dist/commands/{inbox/archive.js → archive.js}

@@ -2,8 +2,8 @@ import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { useEffect, useState } from 'react';
 import zod from 'zod';
 import { Text } from 'ink';
-import { gql } from '../../lib/client.js';
-import { Spinner } from '../../components/Spinner.js';
+import { gql } from '../lib/client.js';
+import { Spinner } from '../components/Spinner.js';
 export const options = zod.object({
     id: zod.string().describe('Suggestion ID to archive'),
 });

package/dist/commands/config/data/download.js

@@ -28,7 +28,7 @@ export default function DataDownload() {
                     upsertTweet(db, s.tweet);
                     upsertSuggestion(db, { suggestionId: s.suggestionId, tweetId: s.tweet.id, score: s.score, status: s.status, relevance: null, projectsMatched: s.projectsMatched });
                 }
-                for (const i of interestsResult.projects) {
+                for (const i of interestsResult.topics) {
                     upsertInterest(db, i);
                 }
                 setSyncState(db, 'last_synced_at', new Date().toISOString());
@@ -36,7 +36,7 @@ export default function DataDownload() {
                 setResult({
                     feedCount: feedResult.feed.length,
                     suggestionsCount: suggestionsResult.suggestions.length,
-                    interestsCount: interestsResult.projects.length,
+                    interestsCount: interestsResult.topics.length,
                 });
             }
             catch (err) {

package/dist/commands/config/data/sync.js

@@ -32,12 +32,12 @@ export default function DataSync() {
                         upsertTweet(freshDb, s.tweet);
                         upsertSuggestion(freshDb, { suggestionId: s.suggestionId, tweetId: s.tweet.id, score: s.score, status: s.status, relevance: null, projectsMatched: s.projectsMatched });
                     }
-                    for (const i of interestsResult.projects) {
+                    for (const i of interestsResult.topics) {
                         upsertInterest(freshDb, i);
                     }
                     setSyncState(freshDb, 'last_synced_at', new Date().toISOString());
                     freshDb.close();
-                    setResult({ feedCount: feedResult.feed.length, suggestionsCount: suggestionsResult.suggestions.length, interestsCount: interestsResult.projects.length });
+                    setResult({ feedCount: feedResult.feed.length, suggestionsCount: suggestionsResult.suggestions.length, interestsCount: interestsResult.topics.length });
                     return;
                 }
                 const hoursSinceSync = Math.min(Math.ceil((Date.now() - new Date(lastSyncedAt).getTime()) / 3600000), 168);

package/dist/commands/config/nuke.js

@@ -3,17 +3,35 @@ import { useEffect } from 'react';
 import { configExists, deleteConfig, deleteDatabase } from '../../lib/config.js';
 import { Text } from 'ink';
 import zod from 'zod';
+import { existsSync } from 'node:fs';
+import { DB_PATH } from '../../lib/db.js';
 export const options = zod.object({
     confirm: zod.boolean().default(false).describe('Pass to confirm deletion'),
 });
 export default function Nuke({ options: flags }) {
     useEffect(() => {
-        if (configExists() && flags.confirm) {
+        if (!flags.confirm) {
+            return;
+        }
+        const hadConfig = configExists();
+        const hadDb = existsSync(DB_PATH);
+        if (hadConfig) {
             deleteConfig();
+        }
+        if (hadDb) {
             deleteDatabase();
-            process.stdout.write('Workspace deleted at ~/.sonar/config.json and ~/.sonar/database.sqlite\n');
+        }
+        if (!hadConfig && !hadDb) {
+            process.stdout.write('Nothing to delete. No local Sonar config or data database found.\n');
             process.exit(0);
         }
+        const deleted = [];
+        if (hadConfig)
+            deleted.push('~/.sonar/config.json');
+        if (hadDb)
+            deleted.push(DB_PATH);
+        process.stdout.write(`Deleted: ${deleted.join(', ')}\n`);
+        process.exit(0);
     }, []);
     return _jsxs(Text, { dimColor: true, children: ["Tip. (pass ", _jsx(Text, { color: "cyan", children: "--confirm" }), " to nuke)"] });
 }