Metadata-Version: 2.4
Name: hn-cli
Version: 0.2.0
Summary: HN CLI utility.
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28
Requires-Dist: rich>=14.0
Requires-Dist: typer>=0.15
Description-Content-Type: text/markdown

# hn-cli

HN CLI utility.

## Tech Stack

- **Python 3.12+** with `src/` layout
- **[uv](https://docs.astral.sh/uv/)** — package manager
- **[Typer](https://typer.tiangolo.com/)** — CLI framework
- **[pytest](https://docs.pytest.org/)** — testing
- **[Ruff](https://docs.astral.sh/ruff/)** — linting & formatting
- **[pre-commit](https://pre-commit.com/)** — git hooks

## Getting Started

```bash
# Install dependencies
uv sync

# Run the CLI
uv run hn-cli --help
uv run hn-cli top
uv run hn-cli top --json
uv run hn-cli top --csv
uv run hn-cli top --format human --output top.txt

# Run tests
uv run pytest

# Lint & format
uv run ruff check .
uv run ruff format .

# Set up git hooks
uv run pre-commit install
```

## Working with AI Agents

This project includes an `AGENTS.md` file with instructions for AI coding agents.

## Project Structure

See [ARCHITECTURE.md](ARCHITECTURE.md) for details on how the project is organized
and how to grow it as your application evolves.

## Commands

- `hn-cli top`: fetch top Hacker News stories (implemented)
- `hn-cli new`: fetch new Hacker News stories (implemented)
- `hn-cli best`: fetch best Hacker News stories (implemented)
- `hn-cli item <id>`: fetch one Hacker News item by ID (implemented)

### `top` options

- `--limit, -n`: number of stories, default `10`, max `100`
- `--format`: `human`, `json`, or `csv`
- `--json`: shortcut for `--format json`
- `--csv`: shortcut for `--format csv`
- `--output, -o`: write output to file
- `--timeout`: HTTP timeout seconds

## Python API (Scripts and Notebooks)

`hn-cli` exposes a stable import API in `hn_cli.api` and top-level re-exports in
`hn_cli`.

### Script example

```python
from hn_cli import get_top, stories_to_json

stories = get_top(limit=5, timeout=10.0)
print(stories_to_json(stories))
```

### Notebook example

```python
from hn_cli.api import get_item, item_to_json

item = get_item(8863)
item_to_json(item)
```

### Stable exports

Top-level supported imports:

- `HNStory`
- `HNApiError`
- `get_top`, `get_new`, `get_best`, `get_item`
- `stories_to_json`, `stories_to_csv`
- `item_to_json`, `item_to_csv`
