Metadata-Version: 2.4
Name: qgist-cli
Version: 0.1.0
Summary: CLI for the QuantGist macro event API — qgist events today
Project-URL: Homepage, https://quantgist.com
Project-URL: Repository, https://github.com/QuantGist-Technologies/quantgist-cli
Project-URL: Documentation, https://quantgist.com/docs
Author-email: QuantGist <dev@quantgist.com>
License: MIT
License-File: LICENSE
Keywords: cli,earnings,economic-calendar,macro,quantgist,trading
Requires-Python: >=3.10
Requires-Dist: quantgist>=0.7.1
Requires-Dist: rich>=13.0.0
Requires-Dist: tomli-w>=1.0.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# qgist

[![PyPI](https://img.shields.io/pypi/v/qgist-cli)](https://pypi.org/project/qgist-cli)
[![Python](https://img.shields.io/pypi/pyversions/qgist-cli)](https://pypi.org/project/qgist-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Command-line interface for the [QuantGist](https://quantgist.com) macro event API. Check upcoming economic events, export historical data, and configure your key — all from the terminal.

The PyPI package is **`qgist-cli`**; it installs the **`qgist`** command.

---

## Install

```bash
pip install qgist-cli
# or (recommended — installs as an isolated tool)
uv tool install qgist-cli
```

---

## Quick start

```bash
# 1. Set your API key (get one free at quantgist.com/signup)
qgist config set api-key qg_live_your_key_here

# 2. Check today's events
qgist events

# 3. Check this week's high-impact events
qgist events week --impact high
```

---

## Commands

### `qgist events [today|week]`

Show upcoming macro events in a formatted table.

```
Usage: qgist events [PERIOD] [OPTIONS]

Arguments:
  PERIOD  today (default) | week

Options:
  -s, --symbol TEXT   Filter by symbol (e.g. XAUUSD)
  -c, --country TEXT  ISO country code (e.g. us, eu, gb)
  -i, --impact TEXT   Impact filter: low | medium | high
  --json              Output raw JSON
```

**Examples:**
```bash
qgist events                          # Today, all impacts
qgist events week                     # Next 7 days
qgist events week --impact high       # This week, high-impact only
qgist events today --country us       # Today, US events
qgist events today --symbol XAUUSD    # Today, Gold-affecting events
qgist events today --json             # Raw JSON output

# Example output:
# ┌──────────────┬────────┬─────────┬──────────────────────────────┬──────────┬──────────┬────────┐
# │ Time (UTC)   │ Impact │ Country │ Event                        │ Forecast │ Previous │ Actual │
# ├──────────────┼────────┼─────────┼──────────────────────────────┼──────────┼──────────┼────────┤
# │ 08:30        │  HIGH  │  US     │ Non-Farm Payrolls            │ 185K     │ 175K     │ —      │
# │ 10:00        │  HIGH  │  US     │ ISM Manufacturing PMI        │ 48.5     │ 47.8     │ —      │
# └──────────────┴────────┴─────────┴──────────────────────────────┴──────────┴──────────┘
```

---

### `qgist config set|get|show`

Manage your API key and settings stored at `~/.config/qgist/config.toml`.

```
Usage: qgist config set KEY VALUE
       qgist config get KEY
       qgist config show
```

**Examples:**
```bash
qgist config set api-key qg_live_abc123
qgist config get api-key
# api-key = qg_live_abc*****

qgist config show
# ╭── QuantGist Config ──────────────────╮
# │ api-key = qg_live_abc*****           │
# │ base-url = https://api.quantgist.com │
# ╰──────────────────────────────────────╯
```

Config file location: `~/.config/qgist/config.toml`

---

### `qgist export <keyword>`

Export historical events matching a keyword to CSV or JSON.

```
Usage: qgist export KEYWORD [OPTIONS]

Arguments:
  KEYWORD  Keyword to search (e.g. nfp, cpi, fomc)

Options:
  --from TEXT     Start date (YYYY-MM-DD), default 30 days ago
  --to TEXT       End date (YYYY-MM-DD), default today
  --format TEXT   csv (default) | json
  --output TEXT   Output file path (default: stdout)
```

**Examples:**
```bash
qgist export nfp                              # NFP events, last 30 days, CSV to stdout
qgist export cpi --from 2024-01-01 --to 2024-12-31 --format json
qgist export fomc --output fomc_history.csv
```

---

### `qgist status`

Check your connection and API key status.

```bash
qgist status

# ╭─ QuantGist Status ──────────────────────────────╮
# │ Connection    ✓ Connected                        │
# │ API Key       qg_live_abc***** (active)          │
# │ Plan          free                               │
# │ Rate limit    47 / 100 remaining today           │
# ╰─────────────────────────────────────────────────╯
```

---

## Configuration

The CLI stores settings in `~/.config/qgist/config.toml`:

```toml
api-key = "qg_live_..."
base-url = "https://api.quantgist.com/v1"
```

**Environment variable override** — set `QUANTGIST_API_KEY` to bypass the config file:
```bash
export QUANTGIST_API_KEY=qg_live_...
qgist events
```

---

## Free API key

[quantgist.com/signup](https://quantgist.com/signup) — 100 calls/day, 365-day history. No credit card.

---

## License

MIT
