dataverse-cli AGENTS.md

Dataverse CLI — Agent Integration Guide

Binary: dv

Dataverse CLI provides real-time social media data from X/Twitter and Reddit via the Bittensor SN13 decentralized data network (Macrocosmos).

Machine-Readable Command Catalog

dv commands

Emits a full JSON schema of all commands, flags, types, defaults, enums, examples, and API endpoint mappings. Use this to discover capabilities programmatically.

Quick Start for Agents

# Set API key (get free at https://app.macrocosmos.ai/account?tab=api-keys)
export MC_API="your-key"

# Always use -o json for structured output
dv -o json search x -k bittensor -l 10

# Preview request without executing (no API call, no credits consumed)
dv --dry-run search x -k bitcoin -l 5

Output Modes

Flag	Format	Use Case
-o table	Human-readable table (default)	Interactive terminal
-o json	JSON array to stdout	Agent parsing, piping to jq
-o csv	CSV to stdout	Data analysis, spreadsheets

Convention: Data goes to stdout, diagnostics/errors go to stderr. Safe to pipe stdout.

Response Structure (JSON mode)

Search (dv -o json search ...)

Returns a JSON array of post objects. Each post has:

{
  "datetime": "2026-03-17T14:53:00Z",
  "source": "x",
  "text": "Post content...",
  "uri": "https://x.com/user/status/123",
  "user": {
    "username": "handle",
    "display_name": "Display Name",
    "followers_count": 1234,
    "user_blue_verified": true
  },
  "tweet": {
    "id": "123456",
    "like_count": 42,
    "retweet_count": 5,
    "reply_count": 3,
    "view_count": 1000,
    "hashtags": ["#bittensor"],
    "language": "en"
  }
}

Dry Run (dv --dry-run ...)

Returns the exact HTTP request that would be sent:

{
  "method": "POST",
  "url": "https://constellation.api.cloud.macrocosmos.ai/sn13.v1.Sn13Service/OnDemandData",
  "headers": { "authorization": "Bearer 87ae...c800", "content-type": "application/json" },
  "body": { "source": "X", "keywords": ["bittensor"], "limit": 10 }
}