qgist-cli 0.1.0__tar.gz

qgist_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  package-check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv sync
+      - run: uv run qgist --help
+      - run: uv build
+
+  publish:
+    # Publishes to PyPI via the trusted publisher bound to this workflow
+    # (QuantGist-Technologies/quantgist-cli · ci.yml). Runs only on v* tags.
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: package-check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      id-token: write  # required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          skip-existing: true

qgist_cli-0.1.0/.gitignore

@@ -0,0 +1,46 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+pip-wheel-metadata/
+uv.lock
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pyre/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+
+# Local
+.env
+.env.local
+CLAUDE.md

qgist_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## v0.1.0 — 2026-06-28
+
+First PyPI release as **`qgist-cli`** (provides the `qgist` command).
+
+### Notes
+- Requires `quantgist>=0.7.1` (the SDK release that matches the current API: optional
+  country/currency, string-valued forecast/previous/actual, header-based rate limit).
+- `events` tolerates events with no country; `export` caps at the API's 100/page limit and
+  exports the `symbols` column. Get a free key at https://quantgist.com.
+
+### Added
+- `qgist events [today|week]` — Rich table of upcoming events with impact color coding
+- `qgist events --symbol`, `--country`, `--impact`, `--json` flags
+- `qgist config set/get/show` — API key management in `~/.config/qgist/config.toml`
+- `qgist export <keyword>` — CSV/JSON export of historical events with `--from`/`--to`/`--output` options
+- `qgist status` — connection check, masked API key, plan info, rate limit remaining
+- `QUANTGIST_API_KEY` environment variable support (overrides config file)

qgist_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QuantGist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

qgist_cli-0.1.0/PKG-INFO

@@ -0,0 +1,190 @@
+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

qgist_cli-0.1.0/README.md

@@ -0,0 +1,172 @@
+# 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

qgist_cli-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "qgist-cli"
+version = "0.1.0"
+description = "CLI for the QuantGist macro event API — qgist events today"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "QuantGist", email = "dev@quantgist.com" }]
+requires-python = ">=3.10"
+keywords = ["quantgist", "trading", "macro", "cli", "economic-calendar", "earnings"]
+dependencies = [
+    "quantgist>=0.7.1",
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "tomli-w>=1.0.0",
+]
+
+[project.scripts]
+qgist = "qgist.cli:main"
+
+[project.urls]
+Homepage = "https://quantgist.com"
+Repository = "https://github.com/QuantGist-Technologies/quantgist-cli"
+Documentation = "https://quantgist.com/docs"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qgist"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"

qgist_cli-0.1.0/src/qgist/api.py

@@ -0,0 +1,21 @@
+import os
+from functools import lru_cache
+
+from quantgist import QuantGistClient
+
+from qgist.config_store import load_config
+
+
+@lru_cache(maxsize=1)
+def get_client() -> QuantGistClient:
+    cfg = load_config()
+    api_key = os.environ.get("QUANTGIST_API_KEY") or cfg.get("api_key", "")
+    if not api_key:
+        import typer
+        typer.echo(
+            "No API key found. Run: qgist config set api-key <your-key>\n"
+            "Or set QUANTGIST_API_KEY environment variable.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    return QuantGistClient(api_key=api_key)

qgist_cli-0.1.0/src/qgist/cli.py

@@ -0,0 +1,19 @@
+import typer
+
+app = typer.Typer(
+    name="qgist",
+    help="QuantGist CLI — macro event data in your terminal.",
+    add_completion=False,
+    rich_markup_mode="rich",
+)
+
+# Import commands so they register themselves on `app`
+from qgist.commands import config, events, export, status  # noqa: E402, F401
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

qgist_cli-0.1.0/src/qgist/commands/config.py

@@ -0,0 +1,52 @@
+"""qgist config set <key> <value> | qgist config get <key> | qgist config show"""
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from qgist.cli import app
+from qgist.config_store import get_value, load_config, set_value
+
+console = Console()
+
+config_app = typer.Typer(help="Manage qgist configuration.")
+app.add_typer(config_app, name="config")
+
+
+@config_app.command("set")
+def config_set(
+    key: str = typer.Argument(..., help="Config key (e.g. api-key, timezone)"),
+    value: str = typer.Argument(..., help="Value to set"),
+) -> None:
+    """Set a config value."""
+    set_value(key, value)
+    console.print(f"[green]✓[/] Set [bold]{key}[/] = {value!r}")
+
+
+@config_app.command("get")
+def config_get(
+    key: str = typer.Argument(..., help="Config key to retrieve"),
+) -> None:
+    """Get a single config value."""
+    val = get_value(key)
+    if val is None:
+        console.print(f"[yellow]Not set:[/] {key}")
+        raise typer.Exit(1)
+    console.print(val)
+
+
+@config_app.command("show")
+def config_show() -> None:
+    """Show all current config values."""
+    cfg = load_config()
+    if not cfg:
+        console.print("[dim]No config found. Run: qgist config set api-key <your-key>[/]")
+        return
+    table = Table(title="qgist config", show_header=True)
+    table.add_column("Key", style="cyan")
+    table.add_column("Value")
+    for k, v in cfg.items():
+        display = "****" + str(v)[-4:] if "key" in k else str(v)
+        table.add_row(k, display)
+    console.print(table)

qgist_cli-0.1.0/src/qgist/commands/events.py

@@ -0,0 +1,64 @@
+"""qgist events [today|week] [--symbol] [--country] [--impact] [--json]"""
+import json
+from datetime import date, timedelta
+from typing import Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from qgist.cli import app
+from qgist.api import get_client
+
+console = Console()
+
+
+@app.command("events")
+def events_cmd(
+    period: str = typer.Argument("today", help="today | week"),
+    symbol: Optional[str] = typer.Option(None, "--symbol", "-s", help="Filter by symbol, e.g. XAUUSD"),
+    country: Optional[str] = typer.Option(None, "--country", "-c", help="ISO country code, e.g. us"),
+    impact: Optional[str] = typer.Option(None, "--impact", "-i", help="low | medium | high"),
+    as_json: bool = typer.Option(False, "--json", help="Output raw JSON"),
+) -> None:
+    today = date.today()
+    from_date = str(today)
+    to_date = str(today if period == "today" else today + timedelta(days=6))
+
+    client = get_client()
+    response = client.get_events(
+        from_date=from_date,
+        to_date=to_date,
+        symbol=symbol,
+        country=country,
+        impact=impact,  # type: ignore[arg-type]
+    )
+
+    if as_json:
+        typer.echo(json.dumps([e.model_dump() for e in response.data], default=str))
+        return
+
+    table = Table(title=f"Events — {period}", show_lines=False)
+    table.add_column("Time (UTC)", style="cyan", no_wrap=True)
+    table.add_column("Impact", justify="center")
+    table.add_column("Country", style="dim")
+    table.add_column("Event")
+    table.add_column("Forecast", justify="right", style="dim")
+    table.add_column("Previous", justify="right", style="dim")
+    table.add_column("Actual", justify="right")
+
+    impact_colors = {"high": "[red]", "medium": "[yellow]", "low": "[green]"}
+
+    for event in response.data:
+        color = impact_colors.get(event.impact, "")
+        table.add_row(
+            event.release_time.strftime("%H:%M"),
+            f"{color}{(event.impact or '').upper()}[/]",
+            (event.country or "").upper(),
+            event.title,
+            str(event.forecast) if event.forecast is not None else "—",
+            str(event.previous) if event.previous is not None else "—",
+            str(event.actual) if event.actual is not None else "—",
+        )
+
+    console.print(table)

qgist_cli-0.1.0/src/qgist/commands/export.py

@@ -0,0 +1,70 @@
+"""qgist export <event-name> --from <date> --to <date> [--format csv|json]"""
+import csv
+import io
+import json
+import sys
+from datetime import date
+from typing import Optional
+
+import typer
+from rich.console import Console
+
+from qgist.cli import app
+from qgist.api import get_client
+
+console = Console()
+
+
+@app.command("export")
+def export_cmd(
+    event_name: str = typer.Argument(..., help="Event keyword to filter (e.g. nfp, cpi)"),
+    from_date: Optional[str] = typer.Option(None, "--from", help="Start date YYYY-MM-DD"),
+    to_date: Optional[str] = typer.Option(None, "--to", help="End date YYYY-MM-DD"),
+    fmt: str = typer.Option("csv", "--format", "-f", help="Output format: csv | json"),
+    output: Optional[str] = typer.Option(None, "--output", "-o", help="Output file path (default: stdout)"),
+) -> None:
+    """Export historical event data to CSV or JSON."""
+    client = get_client()
+
+    # The API caps per_page at 100; pagination is not yet implemented in v0.1.
+    response = client.get_events(
+        from_date=from_date or "2020-01-01",
+        to_date=to_date or str(date.today()),
+        limit=100,
+    )
+
+    # filter by keyword in title
+    keyword = event_name.lower()
+    filtered = [e for e in response.data if keyword in e.title.lower()]
+
+    if not filtered:
+        Console(stderr=True).print(f"[yellow]No events found matching '{event_name}'[/]")
+        raise typer.Exit(1)
+
+    out = sys.stdout if not output else open(output, "w", newline="")
+
+    try:
+        if fmt == "json":
+            json.dump([e.model_dump() for e in filtered], out, default=str, indent=2)
+            if output:
+                console.print(f"[green]✓[/] Exported {len(filtered)} events to {output}")
+        else:
+            writer = csv.DictWriter(
+                out,
+                fieldnames=[
+                    "id", "release_time", "title", "country", "currency",
+                    "impact", "forecast", "previous", "actual", "surprise_score",
+                    "symbols", "event_type", "source",
+                ],
+                extrasaction="ignore",  # model has more fields than we export
+            )
+            writer.writeheader()
+            for e in filtered:
+                row = e.model_dump()
+                row["symbols"] = ",".join(row.get("symbols") or [])
+                writer.writerow(row)
+            if output:
+                console.print(f"[green]✓[/] Exported {len(filtered)} events to {output}")
+    finally:
+        if output:
+            out.close()

qgist_cli-0.1.0/src/qgist/commands/status.py

@@ -0,0 +1,44 @@
+"""qgist status — show API health, rate limit, and plan info"""
+import typer
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from qgist.cli import app
+from qgist.api import get_client
+from qgist.config_store import get_value
+
+console = Console()
+
+
+@app.command("status")
+def status_cmd() -> None:
+    """Show API connection status, rate limit, and plan."""
+    client = get_client()
+
+    console.print("[dim]Checking QuantGist API...[/]")
+    try:
+        resp = client.get_events(limit=1)
+    except Exception as e:
+        console.print(f"[red]✗ API error:[/] {e}")
+        raise typer.Exit(1)
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_column("Key", style="dim")
+    table.add_column("Value", style="bold")
+
+    table.add_row("Status", "[green]✓ Connected[/]")
+
+    remaining = resp.meta.rate_limit_remaining
+    if remaining is not None:
+        color = "green" if remaining > 10 else "yellow" if remaining > 0 else "red"
+        table.add_row("Rate limit remaining", f"[{color}]{remaining}[/]")
+
+    api_key = get_value("api_key") or ""
+    if api_key:
+        masked = api_key[:12] + "****"
+        table.add_row("API key", masked)
+
+    table.add_row("API base", "https://api.quantgist.com/v1")
+
+    console.print(Panel(table, title="qgist status", border_style="cyan"))

qgist_cli-0.1.0/src/qgist/config_store.py

@@ -0,0 +1,28 @@
+import tomllib
+import tomli_w
+from pathlib import Path
+
+_CONFIG_PATH = Path.home() / ".config" / "qgist" / "config.toml"
+
+
+def load_config() -> dict:
+    if not _CONFIG_PATH.exists():
+        return {}
+    with open(_CONFIG_PATH, "rb") as f:
+        return tomllib.load(f)
+
+
+def save_config(config: dict) -> None:
+    _CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with open(_CONFIG_PATH, "wb") as f:
+        tomli_w.dump(config, f)
+
+
+def set_value(key: str, value: str) -> None:
+    cfg = load_config()
+    cfg[key.replace("-", "_")] = value
+    save_config(cfg)
+
+
+def get_value(key: str) -> str | None:
+    return load_config().get(key.replace("-", "_"))