Metadata-Version: 2.4
Name: cpe-data-cli
Version: 0.3.1
Summary: Read-only CLI for a research data API (wiki, graph, memos, raw, coverage, eval). Self-documenting; an agent can drive it without a skill.
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Provides-Extra: monitoring
Requires-Dist: sentry-sdk>=2.0; extra == 'monitoring'
Description-Content-Type: text/markdown

# data-cli

Read-only CLI for a research data API. Gives an agent (or you) access to every
research surface — wiki, knowledge graph, memos, raw primary-source files,
coverage, and eval — through one self-documenting tool.

It is **read-only**: the key it uses can only GET. It can never trigger a
research run, refetch, or any write.

This tool talks to a private data API. You need two values, **provided to you
separately**: the API base URL and a read-only key. Without both, the tool does
nothing.

## Install

```bash
pip install cpe-data-cli
# or, isolated:
pipx install cpe-data-cli
```

### Upgrade

```bash
pip install --upgrade cpe-data-cli
# or, with pipx:
pipx upgrade cpe-data-cli
```

## Configure

```bash
export CPE_API_BASE=<base url you were given>
export CPE_API_KEY=<read-only key you were given>
data-cli auth check              # verify base + key + connectivity
```

Both are required. The tool makes no network call until both are set.

## Version & completion

```bash
data-cli --version               # or -V
data-cli --install-completion    # install shell completion (bash/zsh/fish)
```

## Use

Start with orientation, then drill in. Every command prints the next commands to
run, so you can navigate without memorizing anything.

```bash
data-cli ticker NVDA                    # what exists for a ticker + next steps
data-cli coverage NVDA                  # trust layer: how complete is the data
data-cli eval NVDA                      # trust layer: quality + contradictions
data-cli memo get NVDA                  # full verified dossier (markdown)
data-cli memo list NVDA                 # list memos for a ticker (run ids)
data-cli wiki get NVDA                  # synthesized company page (markdown)
data-cli wiki list                      # all covered companies
data-cli raw NVDA                       # list primary-source files
data-cli raw NVDA source_map.json       # provenance map: read FIRST to find Tier-1 files
data-cli graph ticker NVDA              # cross-ticker links
data-cli graph search "TSMC"            # find nodes by NAME (companies/people, not concepts)
data-cli graph all                      # the full knowledge graph
data-cli guide                          # this workflow, any time
```

Recommended flow for researching a ticker: `ticker` → `coverage` → `eval` →
`memo get` → `raw <file>`. Check coverage and eval **before** trusting figures.

## Output

- Markdown-native surfaces (`wiki`, `memo`, raw `.md`) print **markdown** by
  default. `coverage` and `eval` print a **human-readable summary** by default
  (the trust layer, scannable at a glance); add `--json` for the full payload.
  Other structured surfaces (`ticker`, `graph`, lists) print **JSON**.
- `--json` on any data command for structured output (with `_next` breadcrumbs
  in the body).
- `-o FILE` writes the content to a file (confirmation goes to stderr). Plain
  `> file.md` works too — diagnostics and breadcrumbs go to stderr, so a
  redirected or `-o` file holds only clean content. (`auth check` and `guide`
  are diagnostics and ignore `-o`.)

## For AI agents

This tool ships with an agent skill that teaches the right way to drive it
(which surface answers which question, how to read the trust layer in both
directions, and the common pitfalls):

```bash
data-cli skill          # print the skill
data-cli skill --path   # print its path — point your agent's skills dir at it
```
