Nami coordinates gallery-dl and yt-dlp through a pure functional planning core and isolated execution shell. Engineered for batch extraction, atomic deduplication, classified retry loops, and headless pipelines.

Platform Matrix · Architecture · Installation · Quickstart · CLI Reference · Configuration · Diagnostics

Architecture

Nami separates pure domain logic from side effects using narrow module seams.

Data flow

flowchart TD
    subgraph Core ["Pure Domain Core (No Side Effects)"]
        A[Target URLs / Profiles] -->|parse_target| B[targets.py]
        B -->|build_plan| C[planner.py]
    end

    subgraph Shell ["Stateful Imperative Shell"]
        D{NamiService Orchestrator}
        D -->|Lock Archive| E[archive.py]
        D -->|Execute Command| F[process.py]
        F --> G[gallery-dl / yt-dlp]
        F -->|Capture Output| H[failures.py]
        H -->|Evaluate Decision| I[retry.py]
    end

    C --> D
    D --> J[BatchResult: Exit Code & JSON]

Module seams

Platform Support Matrix

[!NOTE] Unsupported platform/media combinations return structured Outcome.UNSUPPORTED records and exit with status 3.

Installation

Requires Python 3.10 or newer.

# Install from PyPI
python -m pip install nami

# Upgrade existing install
python -m pip install --upgrade nami

Quickstart

Interactive mode

Run nami (or python -m nami if Python Scripts directory is not on system PATH):

nami

╭─ Nami ───────────────────────────────────────────────────────────── v5.0.6 ─╮
│ What do you want to download?                                               │
│                                                                             │
│  1  Photos only                                                             │
│  2  Videos only                                                             │
│  3  Stories only                                                            │
│  4  Highlights only                                                         │
│  5  Photos + Videos                                                         │
│  6  Stories + Highlights                                                    │
│  7  All                                                                     │
│  8  Settings                                                                │
│  0  Exit                                                                    │
│                                                                             │
│  Save: ~/Nami/downloads                                                     │
╰─────────────────────────────────────────────────────────────────────────────╯

CLI batch invocations

# Download direct posts and reels
nami download https://www.instagram.com/p/C_EXAMPLE/ https://x.com/OpenAI/status/1234567890

# Target specific profile media
nami download https://www.instagram.com/natgeo/ --media photos,videos

# Headless batch processing with JSON stdout
nami download --profiles --platform instagram --media all --json

Workspace layout

Nami/
├── downloads/                     # Output directory organized by platform & account
│   ├── instagram/
│   │   └── natgeo/
│   │       ├── Photos/
│   │       │   └── archive.txt    # Deduplication ledger
│   │       ├── Videos/
│   │       │   └── archive.txt
│   │       └── Stories/
│   │           └── archive.txt
│   └── tiktok/
│       └── example_user/
│           └── Videos/
│               └── archive.txt
├── cookies/                       # Netscape-format cookie files
│   ├── instagram_cookies.txt
│   ├── tiktok_cookies.txt
│   ├── facebook_cookies.txt
│   └── x_cookies.txt
└── profiles/                      # Target profile lists
    ├── instagram_profiles.txt
    ├── tiktok_profiles.txt
    ├── facebook_profiles.txt
    └── x_profiles.txt

CLI Reference

nami download

Plan and execute downloads for individual URLs or profile lists.

nami download [URL ...] [OPTIONS]

nami setup

Initialize directory layout and write configuration.

nami setup [OPTIONS]

nami doctor

Run read-only system diagnostic checks without network access.

nami doctor [OPTIONS]

Example output:

PASS  config: Configuration loaded successfully
PASS  python: Python 3.14.7 (>= 3.10 required)
PASS  dependencies: All required packages are installed
PASS  workspace: Base directory is writable
PASS  browser: Brave is installed and unlocked
PASS  cookies: Netscape cookies valid
PASS  urllib3: Clean namespace (no conflicts)
PASS  archive_locks: No stale locks detected

nami config

Manage persistent settings in ~/.nami/nami_config.json.

nami config show [--json]
nami config get <KEY> [--json]
nami config set <KEY> <VALUE> [--json]
nami config unset <KEY> [--json]

nami archive reset

Manage download tracking records (archive.txt) safely without data loss.

nami archive reset [OPTIONS]

Authentication & Cookies

Netscape cookie files

Save exported cookies into cookies_dir. Nami verifies that files contain genuine 7-column rows before passing them to child engines:

• instagram_cookies.txt or instagram.com_cookies.txt
• tiktok_cookies.txt or tiktok.com_cookies.txt
• facebook_cookies.txt or facebook.com_cookies.txt
• x_cookies.txt or x.com_cookies.txt

Browser database extraction

For TikTok downloads without a cookie file, Nami extracts session tokens from local browser databases (brave, chrome, edge, firefox).

Failure Taxonomy & Recovery Matrix

failures.py maps subprocess output to deterministic FailureKind categories:

Deterministic Exit Codes

Configuration & Environment Variables

Development & Verification

Local environment setup

git clone https://github.com/OpenSelena/nami.git
cd nami
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Verification commands

# Run pytest unit test suite
python -m pytest

# Run Ruff linter and code formatter checks
python -m ruff check src tests
python -m ruff format --check src tests

# Verify package build & metadata
python -m build
python -m twine check dist/*

License

Distributed under the MIT License. Developed and maintained by Igect under OpenSelena.