Skip to content

v0.1.2 —Public release

Choose a tag to compare

View all tags
@nimblemo nimblemo released this 29 Aug 07:57
v0.1.2
d5fb692

v0.1.2 — First public release

The first official release of insta-boards, a CLI for backing up every
Instagram Saved Collection into a plain, human-readable on-disk layout.
This release ships the unified entry point, a clean rename, MIT licensing,
and a fully automated PyPI release pipeline.

What is insta-boards?

insta-boards is a small, opinionated CLI that talks to Instagram's
private API (via instagrapi),
walks every Saved Collection on the account, and writes the result
to disk as one directory per collection: media files + per-item JSON
metadata + a top-level index. Re-runs are state-aware and incremental —
interrupt-safe, resumable, and friendly to rate limits.

Unified CLI — one entry point, four subcommands

The previous four entry points (sync-instagram, list-collections,
list-items, download-collection) are replaced by a single command
with subcommands. Pick the verb; everything else is a flag.

Command Purpose
insta-boards sync Full sync of all collections (state-aware, resumable).
insta-boards list boards JSONL of every collection on the account.
insta-boards list items --collection <id> JSONL of items in a single collection.
insta-boards download --collection <id> Download a single collection into data/raw/<slug>/.

Migration:

# before
sync-instagram --dry-run
list-collections
list-items --collection 18427410172124759
download-collection --collection 18427410172124759

# after
insta-boards sync --dry-run
insta-boards list boards
insta-boards list items --collection 18427410172124759
insta-boards download --collection 18427410172124759

The wheel name on PyPI also shortens: insta-sync-boards → insta-boards.

Highlights

  • State-aware incremental sync — every item is persisted to a JSON
    state file the moment it is downloaded, so a network drop or
    Ctrl-C never loses progress.
  • Cursor-based pagination — every walk is resumable via
    --max-id / --output-cursor. The next run picks up exactly where
    the previous one stopped.
  • Human-like throttling — log-normal pause distribution with
    micro- and session-breaks, optional User-Agent rotation. Toggle off
    with --no-humanize for deterministic CI runs.
  • Parallel carousel downloads — bounded thread pool that still
    routes every byte through the pacer. Per-request IG_DOWNLOAD_*
    env vars tune timeouts, retries, and backoff.
  • Pure stdlib + uv — single-binary install, no global Python
    pollution, no transitive build deps.

Installation

# Recommended (one-shot, isolated)
uv tool install insta-boards
insta-boards --help

Requires uv.
Substitute pipx or pip if you prefer.

For development, run from a local checkout:

git clone https://github.com/nimblemo/insta-boards.git
cd insta-boards
uv sync
uv run insta-boards sync --dry-run

Requirements

  • Python ≥ 3.11 (CI matrix: 3.11 / 3.12 / 3.13)
  • A working Instagram account (credentials, sessionid cookie, or
    a pre-saved instagrapi settings file — see README → Configuration)
  • Outbound HTTPS to i.instagram.com and the scontent-*.cdninstagram.com
    CDN

CI / CD

Shipped on day one:

  • .github/workflows/ci.yml — runs on every push to main and on
    every pull request. Matrix-builds the sdist + wheel on Python
    3.11 / 3.12 / 3.13 and smoke-tests every subcommand.
  • .github/workflows/release.yml — runs on every published GitHub
    Release (or via the Run workflow button). Builds the wheel,
    smoke-tests it, and pushes to PyPI via Trusted Publishing (OIDC).
    No API tokens are stored in GitHub secrets.

Repository layout

The project lives across two GitHub repositories by design:

Repo Visibility Purpose
nimblemo/insta-boards public Source of truth. Tagged, released, published to PyPI.
nimblemo/my-insta-boards private Personal working copy. The private branch keeps a relaxed .gitignore so secrets/, data/, and the local sync-collection-list.txt can be committed.

The private branch is fast-forwarded from main after every release.

License

MIT. See the LICENSE file for the full text.

MIT License — Copyright (c) nimblemo

Changelog (0.1.2)

  • CLI: collapsed four entry points into one (insta-boards <sub>).
  • Packaging: renamed wheel and project from insta-sync-boards to
    insta-boards.
  • Docs: leading uv tool install block at the top of the
    Installation section.
  • CI: GitHub Actions matrix (Python 3.11–3.13) + PyPI trusted
    publishing via OIDC.
  • Licensing: MIT.
Assets 2
Loading