bigdata-cli 0.1.0

CLI for the Bigdata.com REST API

Bigdata CLI

Command-line interface for the Bigdata.com REST API. Search news, access financial data, explore the Knowledge Graph, and more — all from your terminal.

Installation

The CLI is published on PyPI as bigdata-cli.

uv (recommended):

uv tool install bigdata-cli

Installs the CLI into its own isolated environment and puts bigdata / bd on your $PATH. Upgrade later with uv tool upgrade bigdata-cli (or bd update).

pip:

pip install bigdata-cli

Prefer pipx install bigdata-cli if you'd rather not pollute your global site-packages.

One-liner (no Python toolchain needed):

curl -fsSL https://github.com/Bigdata-com/bigdata-cli/raw/main/install.sh | bash

Installs uv if it's missing (which also manages Python for you), then installs the CLI in an isolated environment. Re-run it to upgrade.

Latest from git (unreleased changes):

uv tool install git+https://github.com/Bigdata-com/bigdata-cli.git
# or
pip install git+https://github.com/Bigdata-com/bigdata-cli.git

From source (for development):

git clone https://github.com/Bigdata-com/bigdata-cli.git
cd bigdata-cli
uv sync

Two entry points are available: bigdata (full name) and bd (short alias).

Quick start

# 1. Configure your API key (interactive — prompts for key and profile)
bd configure

# Or non-interactive (useful for CI/scripts)
bd configure --non-interactive --api-key your-api-key

# You can also set the key via environment variable instead
export BIGDATA_API_KEY=your-api-key

# 2. Discover the available commands
bd --help
bd search --help
bd find --help
bd resolve --help

# 3. Search across news, filings, and transcripts
bd search run "Tesla AI chips" --limit 5

# 4. Discover entities in the Knowledge Graph (fuzzy search)
bd find companies "Apple"

# 5. Resolve a known identifier to a stable entity (deterministic lookup)
bd resolve isin US0378331005

# 6. Combine commands — get an entity ID, then filter a search by it
bd find companies "Tesla" -o json | jq -r '.results[0].id'
bd search run "earnings" --entity-any-of DD3BB1 --limit 10

# 7. Aggregate signals over time
bd search volume "Tesla" --date-start 2025-01-01 --date-end 2025-03-31
bd search co-mentions-entities "AI chips" --limit 10

Most commands accept -o json|csv|ndjson for machine-readable output and --raw for the unmodified API response — both useful for piping into jq, scripts, or AI agents.

Commands

Search (bd search)

Search across news, filings, transcripts, and research.

# Basic text search
bd search run "AI regulation in Europe"

# Search with filters
bd search run "earnings beat" \
  --entity-any-of DD3BB1 \
  --date-start 2025-01-01 \
  --date-end 2025-03-31 \
  --sentiment positive \
  --limit 10

# Smart search (semantic)
bd search run "What is Tesla's revenue growth?" --mode smart

# Co-mentioned entities
bd search co-mentions-entities "AI chips" --limit 10

# Co-mentioned topics
bd search co-mentions-topics "electric vehicles"

# Search volume over time
bd search volume "Tesla" --date-start 2025-01-01 --date-end 2025-03-31

# Complex filters via JSON file
bd search run --body-file query.json

Available search filters:

Flag	Description
TEXT (positional)	Search query text (4-1400 chars)
--mode, -m	fast (default) or smart
--limit, -l	Max results
--entity-any-of	Entity IDs — match any
--entity-all-of	Entity IDs — match all
--entity-none-of	Entity IDs — exclude
--keyword-any-of	Keywords — match any
--keyword-all-of	Keywords — match all
--topic-any-of	Topic IDs — match any
--source-include	Source IDs to include
--source-exclude	Source IDs to exclude
--date-start	Start date (ISO 8601)
--date-end	End date (ISO 8601)
--sentiment	positive, negative, neutral
--category	news, filings, transcripts, etc.
--document-type	NEWS, FILING, TRANSCRIPT

Knowledge Graph

The Knowledge Graph is split across two command groups based on how you query it:

• bd find -- fuzzy discovery. Input is ambiguous (a name, a query string) and the response may contain multiple candidate matches. Use this when you're exploring or don't yet know the entity's stable ID.
• bd resolve -- deterministic 1:1 lookup. Input is a stable identifier (ISIN, CUSIP, SEDOL, listing) and the response maps it to the matching entity. Use this when you already know which identifier you have and want the canonical entity back.

# Fuzzy discovery
bd find companies "Apple"
bd find sources "Reuters"
bd find etfs "SPY"
bd find sectors

# Deterministic resolution (companies, today)
bd resolve isin US0378331005
bd resolve cusip 037833100
bd resolve sedol 2046251
bd resolve listing XNAS:AAPL

# Bulk resolution -- pass multiple identifiers
bd resolve isin US0378331005 US88160R1014

# Lookup an entity by its Bigdata ID
bd find entities D8442A

Configuration

bd configure

The quickest way to set up your API key:

# Interactive (prompts for API key and profile name)
bd configure

# Non-interactive (for CI/scripts)
bd configure --non-interactive --api-key your-api-key
bd configure --non-interactive --api-key other-key --profile work

This writes credentials to ~/.bigdata/config.toml. If the file already exists, the profile is updated and you'll see a warning before overwriting.

Config file

You can also edit ~/.bigdata/config.toml directly — one section per profile:

[default]
api_key = "your-api-key"

[work]
api_key = "work-api-key"

The file is created with a placeholder on first run if it doesn't exist.

Switch profiles with --profile:

bd --profile work find companies "Apple"

Resolution order

Settings are resolved by load_config() in src/bigdata_cli/config.py per profile.

For any CLI flag like output_format is (highest → lowest):

1. -o / --output CLI flag
2. Selected profile in ~/.bigdata/config.toml
3. BIGDATA_OUTPUT_FORMAT environment variable (or .env file in the working directory)
4. Built-in default (table)

For api_key and base_url (highest → lowest):

1. Selected profile in ~/.bigdata/config.toml (when the value is set in that profile)
2. BIGDATA_API_KEY / BIGDATA_BASE_URL environment variables (or .env file)
3. Built-in default (empty api_key, https://api.bigdata.com for base_url)

Raw JSON input

For complex queries that go beyond CLI flags, use --body or --body-file:

# Inline JSON
bd search run --body '{"query": {"text": "Tesla", "max_chunks": 5}}'

# From file
bd search run --body-file my-query.json

This works on every POST command.

Entity IDs

Most structured data commands take entity identifiers as positional arguments. By default, identifiers are treated as Bigdata entity IDs (rp_entity_id). Use --id-type to specify a different type (ticker, isin, cusip, sedol):

# Find Tesla's entity ID
bd find companies "Tesla" -o json | head -5
# → "id": "DD3BB1"

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest -v

# Run a specific test file
pytest tests/test_commands/test_search.py -v

Links

• Bigdata.com API docs
• Content API docs
• Workflows API docs
• Bigdata.com