Metadata-Version: 2.4
Name: bigdata-cli
Version: 0.1.0
Summary: CLI for the Bigdata.com REST API
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.15.0
Description-Content-Type: text/markdown

# Bigdata CLI

Command-line interface for the [Bigdata.com](https://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`](https://pypi.org/project/bigdata-cli/).

**uv (recommended):**
```bash
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:**
```bash
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):**
```bash
curl -fsSL https://github.com/Bigdata-com/bigdata-cli/raw/main/install.sh | bash
```

Installs [uv](https://docs.astral.sh/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):**
```bash
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):**
```bash
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

```bash
# 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.

```bash
# 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.

```bash
# 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:

```bash
# 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:

```toml
[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`:

```bash
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`:

```bash
# 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`):

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

```

## Development

```bash
# 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](https://docs.bigdata.com/api-rest/introduction)
- [Content API docs](https://docs.bigdata.com/api-rest/content_introduction)
- [Workflows API docs](https://docs.bigdata.com/api-rest/workflows/introduction)
- [Bigdata.com](https://bigdata.com)
