nvelop

Retrieve, analyze, and store your digital life. Ingests content from data sources, follows links, analyzes via LLM, and exports to knowledge bases.

Install

npm install

Requires Node.js 22+.

Setup

# Initialize config and credentials files
nvelop init

# Add your X Developer App client ID to ~/.nvelop/credentials.json
# (or set X_APP_CLIENT_ID env var)

# Login via OAuth 2.0
nvelop login

# Clear credentials
nvelop logout

Commands

Primitives

Small, focused commands that return structured data. An agent can compose these.

# Fetch a single post
nvelop get x post https://x.com/dharmesh/status/2029611903547252849

# Fetch your bookmarks
nvelop get x bookmarks --limit 10 --since 3d

# Extract content from a URL (requires agent-browser)
nvelop crawl https://example.com/article

# Write a document to storage (from stdin or file)
echo '{"id":"x:123", ...}' | nvelop store
nvelop store --input artifact.json

# Run LLM analysis on a markdown file
nvelop analyze ~/.nvelop/docs/x/bookmarks/123/raw.md

Orchestrators

Chain primitives into workflows with threaded execution.

# Ingest bookmarks (fetch -> store, threaded)
nvelop ingest x bookmarks --limit 20

# Ingest with link crawling and LLM analysis
nvelop ingest x bookmarks --limit 10 --depth 1 --analyze

# Ingest and delete bookmarks from source after storing
nvelop ingest x bookmarks --limit 10 --delete

# Dry run
nvelop ingest x bookmarks --limit 5 --dry-run

# Control concurrency and retries
nvelop ingest x bookmarks --concurrency 3 --retry 2

Delete

# Delete bookmarks from X (max 50 per run)
nvelop delete x bookmarks --limit 10
nvelop delete x bookmarks --since 7d

Export

# JSON dump
nvelop export json
nvelop export json --output docs.json

# Obsidian vault with wikilinks
nvelop export obsidian --vault ~/notes

# Notion (stub - not yet implemented)
nvelop export notion --token ntn_xxx --database db_xxx

Utilities

# List all documents
nvelop list

# Show a document
nvelop show x/bookmarks/2035517012647272689
nvelop show x/bookmarks/2035517012647272689 --meta
nvelop show x/bookmarks/2035517012647272689 --analysis

# List/inspect runs
nvelop runs
nvelop runs run_1711468800_abc12

Architecture

Three layers:

1. Core functions -- pure, composable, take explicit args, return data
2. Orchestration -- chains core functions with threading (ingestBookmarks)
3. CLI -- Ink-based interactive UI in TTY mode, plain text when piped

All commands emit typed events through a central event bus, enabling both the interactive terminal UI and plain-text fallback.

Storage

Documents stored at ~/.nvelop/docs/{source}/{resource}/{id}/:

~/.nvelop/docs/x/bookmarks/2035517012647272689/
  raw.md          # original content
  meta.json       # metadata (author, dates, metrics, tags, links)
  analysis.md     # LLM analysis (optional)
  refs/           # crawled external links (optional, depth >= 1)
    substack-com-article.md

LLM Analysis

Supports Anthropic and OpenAI. Add your API key to ~/.nvelop/credentials.json (created by nvelop init):

// ~/.nvelop/credentials.json
{
  "ANTHROPIC_API_KEY": "sk-ant-...",
  // or
  "OPENAI_API_KEY": "sk-...",
}

Configure the provider and model in ~/.nvelop/config.json:

{
  "analyze": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6"
  }
}

Custom prompts: nvelop analyze raw.md --prompt-file my-prompt.md

Development

npm run dev -- ingest x bookmarks --limit 3
npm run build
npm run format
npm test