WubberDucky TypeScript SDK + CLI

TypeScript API client and CLI for discovery and compute operations on the WubberDucky API.

Install

npm install -g @wubberducky/wubberducky

Install for application use (SDK):

npm install @wubberducky/wubberducky

Local development:

npm install
npm run build
npm link

Publishing

Publish package (@wubberducky/wubberducky):

npm run publish:package

Requirements

• Node.js 18+

Configuration

Show config:

wubberducky config show

Set API key:

wubberducky config set-key <YOUR_API_KEY>

Set API URL override:

wubberducky config set-url https://api.wubberducky.com

Environment variables override config file values:

• WUBBERDUCKY_API_KEY
• WUBBERDUCKY_API_URL

Config file path: ~/.wubberducky/config.json

Command Structure

The CLI is organized for machine and human discovery:

wubberducky discover cli
wubberducky discover commands
wubberducky discover command <name>
wubberducky discover format [id]
wubberducky compute <universe> <operation> ...
wubberducky <universe> <operation> ...   # shorthand alias
wubberducky agent <subcommand>
wubberducky config <subcommand> ...

Discovery

wubberducky discover cli
wubberducky discover commands
wubberducky discover command <name>
wubberducky discover format [id]
wubberducky discover universes
wubberducky discover universe <id>
wubberducky discover universe <id> indicators|methods|operations|fields|syntax

Discovery output is machine-readable JSON intended for autonomous agents.

Recommended agent bootstrap sequence:

wubberducky discover cli
wubberducky discover universes
wubberducky discover universe <id> methods
wubberducky discover command <operation>
wubberducky discover format

Compute

wubberducky compute <universe> series <entity> <field> <start> <end>
wubberducky compute <universe> aggregate <entity> <method> <start> <end> [--field <name>] [--benchmark <entity>]
wubberducky compute <universe> evaluate <entity> <expression> <start> <end>
wubberducky compute <universe> simulate <entity|entities> <model> <start> <end> [--entry-rule <expr>] [--exit-rule <expr>] [--initial-capital <num>] [--position-size <num>] [--stop-loss <num>] [--take-profit <num>] [--weights <csv>] [--rebalance <freq>] [--debug-payload]

CLI accepts both --flag value and --flag=value.

Aggregate defaults:

• equities: default field is returns
• weather: default field is tavg_c

Architecture

The project is API-client-first:

1. src/sdk/* is the source of truth for GraphQL request construction and transport.
2. src/cli.ts (CLI) only handles argument parsing, validation, and output formatting.
3. src/mcp/* (MCP server) calls the same SDK methods as the CLI.

This keeps CLI and MCP behavior aligned and reduces schema drift.

SDK layout:

• src/sdk/types.ts: shared operation/discovery types.
• src/sdk/errors.ts: normalized client error model.
• src/sdk/graphql.ts: GraphQL transport wrapper.
• src/sdk/discovery.ts: discovery methods.
• src/sdk/compute.ts: series/aggregate/evaluate/simulate methods.
• src/sdk/index.ts: unified client entrypoint.

SDK quickstart:

import { createApiClient } from '@wubberducky/wubberducky';

const client = createApiClient({
  apiKey: process.env.WUBBERDUCKY_API_KEY!,
  apiUrl: 'https://api.wubberducky.com',
});

const result = await client.discover('universes');
console.log(result);

Agent

wubberducky agent mcp
wubberducky agent manifest

Utility

wubberducky usage
wubberducky help
wubberducky version

MCP Server

Start MCP mode over stdio:

wubberducky agent mcp

Convenience binary (same behavior):

wubberducky-mcp

Agent MCP config example:

{
  "mcpServers": {
    "wubberducky": {
      "command": "wubberducky",
      "args": ["agent", "mcp"],
      "env": {
        "WUBBERDUCKY_API_KEY": "sk_live_..."
      }
    }
  }
}

Tool call examples:

{ "type": "universes" }

{
  "operation": "simulate",
  "universe": "equities",
  "entity": "NVDA",
  "model": "backtest",
  "entry_rule": "RSI(14) < 30",
  "exit_rule": "RSI(14) > 60",
  "initial_capital": 100000,
  "stop_loss": 0.1,
  "start": "2024-02-01",
  "end": "2026-02-01"
}

Examples

# Explore all functionality and input schemas
wubberducky discover cli

# Explore only simulate schema
wubberducky discover command simulate

# Explore universe capabilities
wubberducky discover universe equities

# Series
wubberducky compute equities series AAPL close 2024-01-01 2024-06-30

# Aggregate
wubberducky compute equities aggregate AAPL SHARPE 2024-01-01 2024-06-30

# Weather aggregate with alias label (resolved to canonical method)
wubberducky compute weather aggregate DEN,SEA WEATHER_CO_MOVEMENT 2000-01-01 2000-12-31

# Weather sensitivity (beta alias) with benchmark
wubberducky compute weather aggregate DEN WEATHER_SENSITIVITY 2000-01-01 2000-12-31 --benchmark SEA

# Evaluate
wubberducky compute equities evaluate AAPL "RSI(14) < 30" 2024-01-01 2024-06-30

# Simulate
wubberducky compute equities simulate AAPL backtest 2024-01-01 2024-06-30 --entry-rule "RSI(14)<30" --exit-rule "RSI(14)>70" --initial-capital 100000

# Simulate (portfolio, multi-entity)
wubberducky compute equities simulate AAPL,MSFT,GOOGL portfolio 2023-01-01 2024-06-30 --weights 0.4,0.3,0.3 --rebalance MONTHLY --initial-capital 100000

# Simulate with request payload debug
wubberducky compute equities simulate AAPL,MSFT,GOOGL portfolio 2023-01-01 2024-06-30 --weights 0.4,0.3,0.3 --rebalance MONTHLY --debug-payload

# Shorthand alias form
wubberducky weather series DEN tavg_c 2000-01-01 2000-01-10

Output and Exit Codes

• Most commands write JSON to stdout.
• Prompts and errors are written to stderr.
• Exit code 0 indicates success, 1 indicates failure.

License

MIT