Metadata-Version: 2.4
Name: hn-cli
Version: 0.1.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 hello Alice
uv run hn-cli hello Alice --shout
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`: placeholder (not implemented yet)
- `hn-cli best`: placeholder (not implemented yet)
- `hn-cli item <id>`: placeholder (not implemented yet)

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