instagram-dl 0.0.1__tar.gz

instagram_dl-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "README.md"
+      - "CONTRIBUTING.md"
+      - "CHANGELOG.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e '.[docs]'
+      - run: mkdocs build --strict --site-dir _site
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

instagram_dl-0.0.1/.github/workflows/lint.yml

@@ -0,0 +1,33 @@
+name: lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e '.[lint]'
+      - run: ruff check insta_dl tests
+
+  mypy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e '.[lint]'
+      - run: mypy insta_dl

instagram_dl-0.0.1/.github/workflows/tests.yml

@@ -0,0 +1,22 @@
+name: tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - run: pip install -e '.[dev]'
+      - run: pytest --cov=insta_dl --cov-report=term-missing --cov-fail-under=90

instagram_dl-0.0.1/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+_site/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.DS_Store
+.claude/
+.context/
+CLAUDE.md

instagram_dl-0.0.1/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to insta-dl. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [SemVer](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] — 2026-04-24
+
+### Added
+
+- Initial async-first skeleton with pluggable backend interface (`InstagramBackend` ABC).
+- HikerAPI backend (`HikerBackend`) with cursor pagination, dict→DTO mapping, and streaming downloads via `httpx.AsyncClient`.
+- `Downloader` facade orchestrating profile/post/hashtag/stories/highlights/comments downloads with consistent file layout.
+- CLI accepting profile names, `#hashtag`, `post:SHORTCODE`, and full `instagram.com/p/...`, `/reel/`, `/tv/` URLs (case-insensitive, anchored regex against host spoofing).
+- Sidecar JSON metadata per post; optional `--comments` sidecar streamed to disk.
+- `--fast-update` + `--latest-stamps` for incremental archive updates (INI-backed state).
+- `safe_component()` path sanitizer applied to every user-controlled component (username, owner, hashtag, highlight title, post code).
+- Hardening: HTTPS-only allowlist for CDN downloads (`*.cdninstagram.com`, `*.fbcdn.net`), manual redirect loop with cap, signed-token strip from sidecar URLs, `.part` files with UUID suffixes, configurable max-download size (default 500 MB), Windows reserved-name and bidi/zero-width character handling.
+- Test suite: 198 pytest cases at 95% coverage. `httpx.MockTransport` used for CDN, fake hikerapi client for upstream.
+- MkDocs Material documentation site at `docs/`.
+
+### Stubbed
+
+- `AiograpiBackend` — interface defined, methods raise `NotImplementedError` pending an upstream sync.
+- `--post-filter` — parsed but ignored; planned implementation uses AST-restricted compile (no raw `eval`).
+
+### Known limitations
+
+- No retry/backoff on 429 / 5xx / connection reset (relies on hikerapi defaults).
+- No support for `:feed`, `:saved`, or DMs (account-bound, blocked on aiograpi).
+- Comments sidecar is a single JSON array — fine for posts with thousands of comments, may want JSONL for hundreds of thousands.
+
+[0.0.1]: https://github.com/subzeroid/insta-dl/releases/tag/v0.0.1

instagram_dl-0.0.1/CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to insta-dl
+
+Thanks for considering a contribution. This document covers the dev workflow.
+
+## Setup
+
+```bash
+git clone git@github.com:subzeroid/insta-dl.git
+cd insta-dl
+python -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+Python 3.11+ required (we use `dataclass(slots=True)`, `X | Y` unions, `datetime.fromisoformat` with `Z`).
+
+## Running tests
+
+```bash
+pytest                                          # all tests
+pytest -k hiker                                 # subset
+pytest --cov=insta_dl --cov-report=term-missing # with coverage
+```
+
+The suite is fully offline — no real HikerAPI or Instagram calls. Network is mocked via `httpx.MockTransport` and a fake hikerapi client.
+
+Coverage targets: keep pure-logic modules at 100% (`models`, `filestore`, `latest_stamps`, `exceptions`). Everything else: 90%+ where reasonable. Don't write tests for `__main__.py`.
+
+## Project layout
+
+```
+insta_dl/
+  cli.py              # argparse + target dispatch
+  downloader.py       # Downloader facade (orchestrates files, mtime, fast-update)
+  backend.py          # InstagramBackend ABC — async iterators
+  models.py           # DTOs (Profile, Post, StoryItem, Highlight, Comment)
+  filestore.py        # safe_component, post_filename, mtime
+  latest_stamps.py    # INI state for --fast-update
+  exceptions.py       # error hierarchy
+  backends/
+    hiker.py              # HikerAPI adapter (httpx + AsyncClient)
+    _hiker_map.py         # raw dict → DTO mappers
+    aiograpi_backend.py   # aiograpi adapter (stub; in progress)
+tests/
+  test_*.py           # pytest, asyncio mode = auto
+docs/
+  *.md                # MkDocs Material site
+```
+
+## Adding a backend
+
+1. Implement `insta_dl.backend.InstagramBackend` in `insta_dl/backends/<name>.py`. All methods are `async`; iterators are `AsyncIterator[...]`.
+2. Map raw responses to DTOs in `insta_dl/backends/_<name>_map.py`. Don't fabricate missing fields — raise `ValueError` so the caller can decide to skip.
+3. Implement `download_resource(url, dest)` with:
+   - host allowlist (`*.cdninstagram.com`, `*.fbcdn.net`)
+   - https-only scheme check
+   - manual redirect loop with limit
+   - `.part` file with `uuid.uuid4().hex` suffix → `os.replace` on success, `unlink` on failure
+   - byte budget against `_max_bytes`
+   See `HikerBackend.download_resource` for the reference.
+4. Register in `insta_dl/backends/__init__.py:make_backend`.
+5. Add tests in `tests/test_<name>_backend.py` using `httpx.MockTransport` for the CDN and a fake client for the upstream API.
+
+The `Downloader` facade and DTOs are backend-agnostic — never let backend-specific types leak past the adapter layer.
+
+## Code style
+
+- No emojis in code or docs (unless the user asked for them).
+- No comments unless the *why* is non-obvious. Code should self-document via naming.
+- Default to writing nothing speculative (no helpers for hypothetical future requirements).
+- `from __future__ import annotations` everywhere — keeps annotations lazy and string-based.
+- Lazy imports for heavy backend dependencies (`hikerapi`, `aiograpi`) — top-level import of a backend module must succeed without the upstream library installed.
+
+## Documentation
+
+The MkDocs site lives in `docs/`. To preview locally:
+
+```bash
+pip install -e '.[docs]'
+mkdocs serve
+```
+
+Then open <http://localhost:8000>. The site auto-deploys to GitHub Pages on push to `main` via `.github/workflows/docs.yml`.
+
+## Pull requests
+
+- Branch from `main`, rebase before opening the PR.
+- One logical change per PR.
+- All tests must pass; coverage shouldn't drop more than 1%.
+- Update `CHANGELOG.md` under "Unreleased".
+- For new CLI flags or backend methods, update `docs/cli-reference.md` and `docs/backends.md`.
+
+## Security
+
+If you find a vulnerability (path traversal, SSRF bypass, signed-token leak, etc.), please open a private security advisory on GitHub rather than a public issue.

instagram_dl-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 subzeroid
+
+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.

instagram_dl-0.0.1/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: instagram-dl
+Version: 0.0.1
+Summary: Async Instagram downloader CLI — profiles, posts, reels, stories, highlights, hashtags, comments. Pluggable backends (HikerAPI / aiograpi).
+Project-URL: Homepage, https://subzeroid.github.io/insta-dl/
+Project-URL: Documentation, https://subzeroid.github.io/insta-dl/
+Project-URL: Repository, https://github.com/subzeroid/insta-dl
+Project-URL: Issues, https://github.com/subzeroid/insta-dl/issues
+Project-URL: Changelog, https://github.com/subzeroid/insta-dl/blob/main/CHANGELOG.md
+Author: subzeroid
+License: MIT License
+        
+        Copyright (c) 2026 subzeroid
+        
+        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.
+License-File: LICENSE
+Keywords: aiograpi,async,cli,downloader,hikerapi,instagram,instagram-downloader,instagram-scraper,osint
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aiograpi
+Requires-Dist: hikerapi
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Requires-Dist: mkdocs>=1.6; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10; extra == 'docs'
+Provides-Extra: lint
+Requires-Dist: mypy>=1.11; extra == 'lint'
+Requires-Dist: ruff>=0.6; extra == 'lint'
+Description-Content-Type: text/markdown
+
+# insta-dl
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)]()
+[![Tests](https://img.shields.io/badge/tests-198%20passing-success.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-95%25-success.svg)]()
+
+Async command-line downloader for Instagram. Profiles, posts, reels, stories, highlights, hashtags, and comments — saved to disk with the original timestamps preserved.
+
+```bash
+pip install instagram-dl   # installs the `insta-dl` command
+
+export HIKERAPI_TOKEN=your_token
+insta-dl instagram
+```
+
+**insta-dl**
+
+- downloads **profiles, hashtags, single posts, reels, stories, highlights, and comments**,
+- preserves the **original `taken_at` timestamp** as file mtime so Photos/Finder sort correctly,
+- writes a **JSON metadata sidecar** next to every post (caption, like count, location, owner),
+- supports **incremental updates** with `--fast-update` and `--latest-stamps`,
+- accepts profile names, `#hashtag`, post shortcodes, and full `instagram.com` URLs,
+- ships **two interchangeable backends**: a paid commercial API (HikerAPI, no Instagram session, no ban risk) and an open-source private-API library (aiograpi, your own login).
+
+```text
+insta-dl [--backend hiker|aiograpi]
+         [--dest DIR] [--fast-update] [--latest-stamps FILE]
+         [--stories] [--highlights] [--comments]
+         profile | "#hashtag" | post:SHORTCODE | https://instagram.com/...
+```
+
+📖 **[Full documentation](https://subzeroid.github.io/insta-dl/)** — installation, CLI reference, backends comparison, Python API, troubleshooting.
+
+## How to download an Instagram profile
+
+```bash
+export HIKERAPI_TOKEN=$(cat ~/.config/hikerapi-token)
+insta-dl --dest ./out instagram
+```
+
+This grabs every post, names files `2026-04-21_16-04-15_DXZlTiKEpxw.mp4`, and writes a metadata sidecar next to each.
+
+## How to keep a local archive in sync
+
+```bash
+insta-dl --fast-update --latest-stamps ./stamps.ini --dest ./out instagram
+```
+
+`--fast-update` stops at the first post that's already on disk; `--latest-stamps` records the newest `taken_at` per profile so even a deleted local copy can be resumed.
+
+## How to download a single post or reel
+
+```bash
+insta-dl post:DXZlTiKEpxw
+insta-dl https://www.instagram.com/p/DXZlTiKEpxw/
+insta-dl https://www.instagram.com/reel/DXZlTiKEpxw/
+```
+
+## How to download a hashtag
+
+```bash
+insta-dl '#sunset' --dest ./out
+```
+
+Pulls the recent feed for the tag into `./out/#sunset/`.
+
+## How to grab stories and highlights
+
+```bash
+insta-dl --stories --highlights --dest ./out instagram
+```
+
+Stories and highlights land under `<dest>/<username>/stories/` and `<dest>/<username>/highlights/<id>_<title>/`.
+
+## How to save comments alongside posts
+
+```bash
+insta-dl --comments --dest ./out instagram
+```
+
+Each post gets a `..._comments.json` sidecar streamed to disk.
+
+## Backends
+
+Pick the one that matches how you want to authenticate.
+
+| | **hiker** (default) | **aiograpi** *(in development)* |
+|---|---|---|
+| Auth | API token | Instagram login + 2FA |
+| Cost | Paid per request, [**100 free requests**](https://hikerapi.com/p/18j4ib4j) to start | Free |
+| Account ban risk | None — no Instagram session involved | Real, mitigated by session reuse |
+| Stability vs. Instagram changes | High (managed proxy) | Brittle |
+| Private profiles | What HikerAPI exposes | Anything your account can see |
+
+Switch with `--backend`:
+
+```bash
+insta-dl --backend hiker --hiker-token TOKEN instagram
+insta-dl --backend aiograpi --login USER --password PASS --session ./session.json instagram
+```
+
+Detailed comparison and auth setup: see the [backends documentation](https://subzeroid.github.io/insta-dl/backends/).
+
+## Output layout
+
+```
+<dest>/<username>/
+    2026-04-21_16-04-15_DXZlTiKEpxw.mp4
+    2026-04-21_16-04-15_DXZlTiKEpxw.json           # metadata sidecar
+    2026-04-21_16-04-15_DXZlTiKEpxw_comments.json  # with --comments
+    stories/
+        2026-04-21_18-30-00_178290.jpg             # with --stories
+    highlights/
+        17991_Travel/                              # with --highlights
+            2025-10-12_19-20-30_4011.jpg
+```
+
+Hashtag downloads land under `<dest>/#<tag>/`; single-post downloads use the post owner's username (or `owner_pk` fallback).
+
+## Status
+
+This is **alpha**. The hiker backend is functional end-to-end (197 tests, 95% coverage). The aiograpi backend is stubbed pending an upstream sync. CLI flags and output layout are stable; Python API may still shift.
+
+What's not yet implemented:
+
+- private profiles requiring login (waiting on aiograpi)
+- `:feed` and `:saved` (account-bound, blocked on aiograpi)
+- post-filter expressions (planned: AST-restricted eval)
+- automatic retry/backoff on 429/5xx
+
+See the [changelog](CHANGELOG.md) for what landed when, and [contributing](CONTRIBUTING.md) for how to help.
+
+## Contributing
+
+Bug reports, fixes, and backend implementations welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Tests: `pip install -e .[dev] && pytest`.
+
+## Disclaimer
+
+insta-dl is not affiliated with, authorized, maintained, or endorsed by Instagram or Meta. Use at your own risk and respect the rights of content creators. Licensed under [MIT](LICENSE).

instagram_dl-0.0.1/README.md

@@ -0,0 +1,141 @@
+# insta-dl
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)]()
+[![Tests](https://img.shields.io/badge/tests-198%20passing-success.svg)]()
+[![Coverage](https://img.shields.io/badge/coverage-95%25-success.svg)]()
+
+Async command-line downloader for Instagram. Profiles, posts, reels, stories, highlights, hashtags, and comments — saved to disk with the original timestamps preserved.
+
+```bash
+pip install instagram-dl   # installs the `insta-dl` command
+
+export HIKERAPI_TOKEN=your_token
+insta-dl instagram
+```
+
+**insta-dl**
+
+- downloads **profiles, hashtags, single posts, reels, stories, highlights, and comments**,
+- preserves the **original `taken_at` timestamp** as file mtime so Photos/Finder sort correctly,
+- writes a **JSON metadata sidecar** next to every post (caption, like count, location, owner),
+- supports **incremental updates** with `--fast-update` and `--latest-stamps`,
+- accepts profile names, `#hashtag`, post shortcodes, and full `instagram.com` URLs,
+- ships **two interchangeable backends**: a paid commercial API (HikerAPI, no Instagram session, no ban risk) and an open-source private-API library (aiograpi, your own login).
+
+```text
+insta-dl [--backend hiker|aiograpi]
+         [--dest DIR] [--fast-update] [--latest-stamps FILE]
+         [--stories] [--highlights] [--comments]
+         profile | "#hashtag" | post:SHORTCODE | https://instagram.com/...
+```
+
+📖 **[Full documentation](https://subzeroid.github.io/insta-dl/)** — installation, CLI reference, backends comparison, Python API, troubleshooting.
+
+## How to download an Instagram profile
+
+```bash
+export HIKERAPI_TOKEN=$(cat ~/.config/hikerapi-token)
+insta-dl --dest ./out instagram
+```
+
+This grabs every post, names files `2026-04-21_16-04-15_DXZlTiKEpxw.mp4`, and writes a metadata sidecar next to each.
+
+## How to keep a local archive in sync
+
+```bash
+insta-dl --fast-update --latest-stamps ./stamps.ini --dest ./out instagram
+```
+
+`--fast-update` stops at the first post that's already on disk; `--latest-stamps` records the newest `taken_at` per profile so even a deleted local copy can be resumed.
+
+## How to download a single post or reel
+
+```bash
+insta-dl post:DXZlTiKEpxw
+insta-dl https://www.instagram.com/p/DXZlTiKEpxw/
+insta-dl https://www.instagram.com/reel/DXZlTiKEpxw/
+```
+
+## How to download a hashtag
+
+```bash
+insta-dl '#sunset' --dest ./out
+```
+
+Pulls the recent feed for the tag into `./out/#sunset/`.
+
+## How to grab stories and highlights
+
+```bash
+insta-dl --stories --highlights --dest ./out instagram
+```
+
+Stories and highlights land under `<dest>/<username>/stories/` and `<dest>/<username>/highlights/<id>_<title>/`.
+
+## How to save comments alongside posts
+
+```bash
+insta-dl --comments --dest ./out instagram
+```
+
+Each post gets a `..._comments.json` sidecar streamed to disk.
+
+## Backends
+
+Pick the one that matches how you want to authenticate.
+
+| | **hiker** (default) | **aiograpi** *(in development)* |
+|---|---|---|
+| Auth | API token | Instagram login + 2FA |
+| Cost | Paid per request, [**100 free requests**](https://hikerapi.com/p/18j4ib4j) to start | Free |
+| Account ban risk | None — no Instagram session involved | Real, mitigated by session reuse |
+| Stability vs. Instagram changes | High (managed proxy) | Brittle |
+| Private profiles | What HikerAPI exposes | Anything your account can see |
+
+Switch with `--backend`:
+
+```bash
+insta-dl --backend hiker --hiker-token TOKEN instagram
+insta-dl --backend aiograpi --login USER --password PASS --session ./session.json instagram
+```
+
+Detailed comparison and auth setup: see the [backends documentation](https://subzeroid.github.io/insta-dl/backends/).
+
+## Output layout
+
+```
+<dest>/<username>/
+    2026-04-21_16-04-15_DXZlTiKEpxw.mp4
+    2026-04-21_16-04-15_DXZlTiKEpxw.json           # metadata sidecar
+    2026-04-21_16-04-15_DXZlTiKEpxw_comments.json  # with --comments
+    stories/
+        2026-04-21_18-30-00_178290.jpg             # with --stories
+    highlights/
+        17991_Travel/                              # with --highlights
+            2025-10-12_19-20-30_4011.jpg
+```
+
+Hashtag downloads land under `<dest>/#<tag>/`; single-post downloads use the post owner's username (or `owner_pk` fallback).
+
+## Status
+
+This is **alpha**. The hiker backend is functional end-to-end (197 tests, 95% coverage). The aiograpi backend is stubbed pending an upstream sync. CLI flags and output layout are stable; Python API may still shift.
+
+What's not yet implemented:
+
+- private profiles requiring login (waiting on aiograpi)
+- `:feed` and `:saved` (account-bound, blocked on aiograpi)
+- post-filter expressions (planned: AST-restricted eval)
+- automatic retry/backoff on 429/5xx
+
+See the [changelog](CHANGELOG.md) for what landed when, and [contributing](CONTRIBUTING.md) for how to help.
+
+## Contributing
+
+Bug reports, fixes, and backend implementations welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md). Tests: `pip install -e .[dev] && pytest`.
+
+## Disclaimer
+
+insta-dl is not affiliated with, authorized, maintained, or endorsed by Instagram or Meta. Use at your own risk and respect the rights of content creators. Licensed under [MIT](LICENSE).