EverestLens CLI

A machine-readable command-line interface for the EverestLens content intelligence platform. All output is structured JSON, making it suitable for AI agents, automation pipelines, and shell scripting.

Overview

The EverestLens CLI (elens) provides direct access to the three core domains of the platform:

• ideas — list and generate AI-powered content ideas from viral post patterns
• creators — manage the list of creators you follow across platforms
• feed — browse scraped viral posts from followed creators

All successful output is written to stdout as:

{"ok": true, "data": { ... }}

All errors are written to stderr as:

{"ok": false, "error": "Human-readable message", "code": "MACHINE_READABLE_CODE"}

Getting Started

1. Install

npm install -g everestlens

2. Generate an API key

Go to your EverestLens dashboard → My Account → API Keys → New Key.

Give it a name (e.g. "My laptop") and copy the key — it's only shown once.

3. Authenticate the CLI

elens auth init --api-key elens_xxxxxxxxxxxxxxxx

This verifies the key against the server and saves it to ~/.config/everestlens/credentials.json (mode 600 — only you can read it). You only do this once per machine.

For a self-hosted instance pass --url:

elens auth init --api-key elens_xxx --url https://your-instance.com

4. Verify

elens auth whoami

You're ready.

Environment Variables (optional — override credentials file)

| Variable | Description | |---|---| | EVERESTLENS_API_KEY | API key — overrides credentials file | | EVERESTLENS_BASE_URL | Server URL (default: https://everestlens.vercel.app) |

Command Reference

auth init --api-key <key>

Verify and save an API key to the credentials file.

elens auth init --api-key elens_xxxxxxxxxxxxxxxx

| Flag | Description | |---|---| | --api-key <key> | Your EverestLens API key (required) | | --url <url> | Server URL (default: https://everestlens.vercel.app) |

auth whoami

Show the currently authenticated user.

elens auth whoami

auth logout

Remove the saved credentials file.

elens auth logout

ideas list

List AI-generated content ideas for the configured user.

elens ideas list [options]

| Flag | Default | Description | |---|---|---| | -l, --limit <n> | 20 | Number of ideas to return (max 100) | | -p, --platform <platform> | — | Filter by platform: youtube, tiktok, instagram, linkedin | | --since <date> | — | Only ideas generated at or after this ISO date (e.g. 2025-01-01) |

Examples:

# List the 10 most recent ideas
elens ideas list --limit 10

# List YouTube ideas generated this year
elens ideas list --platform youtube --since 2025-01-01

Output:

{
  "ok": true,
  "data": {
    "ideas": [
      {
        "id": "uuid",
        "title": "I Tested The 5 Most Viral Productivity Tools",
        "title_variations": ["...", "...", "..."],
        "format": "I Tested X",
        "platform": "youtube",
        "evidence": "4 creators had 3–9x outliers with this format",
        "generated_at": "2025-03-18T10:00:00Z",
        "source_posts": [...]
      }
    ],
    "count": 1
  }
}

ideas generate

Run the insight pipeline: fetch unused viral outlier posts from followed creators, extract patterns with Claude, and store new content ideas.

elens ideas generate [options]

| Flag | Default | Description | |---|---|---| | --dry-run | — | Preview available outliers without generating ideas | | --force | — | Bypass the one-generation-per-day guard |

Examples:

# Check if generation is possible without doing anything
elens ideas generate --dry-run

# Generate ideas (blocked if already generated today)
elens ideas generate

# Force regeneration even if already generated today
elens ideas generate --force

Dry-run output:

{
  "ok": true,
  "data": {
    "dry_run": true,
    "available_outliers": 12,
    "would_generate": true
  }
}

Success output:

{
  "ok": true,
  "data": {
    "ideas_generated": 5
  }
}

Error codes:

• ALREADY_GENERATED_TODAY — use --force to override
• NOT_ENOUGH_OUTLIERS — fewer than 3 unused outlier posts available
• PIPELINE_ERROR — Claude or database error during generation

creators list

List all creators currently being followed.

elens creators list

Output:

{
  "ok": true,
  "data": {
    "creators": [
      {
        "id": "uuid",
        "platform": "youtube",
        "handle": "mkbhd",
        "is_connected": true,
        "last_sync": "2025-03-18T08:00:00Z",
        "created_at": "2025-01-01T00:00:00Z"
      }
    ],
    "count": 1
  }
}

creators follow <platform> <handle>

Start following a creator on the specified platform.

elens creators follow <platform> <handle>

• <platform>: one of youtube, tiktok, instagram, linkedin
• <handle>: creator handle (with or without leading @)

Examples:

elens creators follow youtube mkbhd
elens creators follow tiktok @kayla_itsines

Output:

{
  "ok": true,
  "data": {
    "followed": {
      "id": "uuid",
      "platform": "youtube",
      "handle": "mkbhd"
    }
  }
}

Error codes:

• ALREADY_FOLLOWING — creator is already in the follow list
• CREATOR_LIMIT_REACHED — at the 30-creator limit; unfollow someone first
• INVALID_PLATFORM — platform not in the allowed list

creators unfollow <id>

Stop following a creator by their connection ID (soft-delete).

elens creators unfollow <id> --yes

| Flag | Required | Description | |---|---|---| | -y, --yes | Yes | Confirm the unfollow action |

Example:

elens creators unfollow abc12345-0000-0000-0000-000000000000 --yes

Output:

{
  "ok": true,
  "data": {
    "unfollowed": true,
    "id": "abc12345-0000-0000-0000-000000000000"
  }
}

Error codes:

• CONFIRMATION_REQUIRED — --yes flag not passed

feed

Browse viral posts from followed creators.

elens feed [options]

| Flag | Default | Description | |---|---|---| | -l, --limit <n> | 20 | Number of posts to return (max 100) | | -p, --platform <platform> | — | Filter by platform | | -d, --days <n> | — | Posts from the last N days only | | --min-viral <n> | 0 | Minimum viral_index_norm score | | --sort <field> | viral | Sort by viral (score desc) or date (post_date desc) | | --unused-only | — | Only posts not yet used for idea generation |

Examples:

# Top 10 most viral posts
elens feed --limit 10

# YouTube posts from the last 7 days with viral score >= 200
elens feed --platform youtube --days 7 --min-viral 200

# Unused outlier posts available for idea generation
elens feed --min-viral 180 --unused-only --limit 50

# Most recent posts sorted by date
elens feed --sort date --days 30

Output:

{
  "ok": true,
  "data": {
    "posts": [
      {
        "id": "uuid",
        "caption": "I tested every AI tool for 30 days and here's what happened...",
        "platform": "youtube",
        "creator": "mkbhd",
        "viral_index_norm": 342,
        "views": 2400000,
        "likes": 98000,
        "post_url": "https://youtube.com/watch?v=...",
        "post_date": "2025-03-15",
        "used_for_ideas": false
      }
    ],
    "count": 1
  }
}

Output Format

Success

All successful responses go to stdout with exit code 0:

{
  "ok": true,
  "data": { ... }
}

Error

All error responses go to stderr with a non-zero exit code:

{
  "ok": false,
  "error": "Human-readable description of what went wrong",
  "code": "MACHINE_READABLE_ERROR_CODE"
}

Exit Codes

| Code | Value | Meaning | |---|---|---| | OK | 0 | Command succeeded | | USER_ERROR | 1 | Invalid input, missing flags, business rule violation | | SYSTEM_ERROR | 2 | Missing env vars, database error, external API failure |

Integration Example

The following shows how an AI agent might chain commands to run the full EverestLens workflow:

#!/usr/bin/env bash
set -euo pipefail

# 1. Check if idea generation is worth running
DRY=$(elens ideas generate --dry-run 2>/dev/null)
AVAILABLE=$(echo "$DRY" | jq '.data.available_outliers')
WOULD=$(echo "$DRY" | jq '.data.would_generate')

echo "Available outliers: $AVAILABLE, would generate: $WOULD"

if [ "$WOULD" = "true" ]; then
  # 2. Generate ideas
  RESULT=$(elens ideas generate 2>/dev/null)
  COUNT=$(echo "$RESULT" | jq '.data.ideas_generated')
  echo "Generated $COUNT ideas"

  # 3. Fetch the new ideas
  elens ideas list --limit 5 | jq '.data.ideas[] | {title, platform, format}'
else
  echo "Not enough outlier posts — skipping generation"

  # Show what's available in the feed
  elens feed --min-viral 100 --limit 10 | jq '.data.posts[] | {creator, caption, viral_index_norm}'
fi

Checking for errors in scripts:

OUTPUT=$(elens creators follow youtube newcreator 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -ne 0 ]; then
  CODE=$(echo "$OUTPUT" | jq -r '.code')
  MSG=$(echo "$OUTPUT" | jq -r '.error')
  echo "Error [$CODE]: $MSG"
  exit $EXIT_CODE
fi