Table of Contents

• Platform Support Matrix
• Architecture & Pipeline
• Installation
• Quickstart
  • 1. Interactive Mode
  • 2. CLI Batch Invocations
• Workspace Hierarchy
• CLI Reference
  • nami download
  • nami setup
  • nami doctor
  • nami config
  • nami archive reset
• Authentication & Cookies
• Failure Taxonomy & Retry Policy
• Deterministic Exit Codes
• Configuration & Environment Variables
• Development & Verification
• License

Platform Support Matrix

Architecture & Pipeline

Nami enforces a strict boundary between pure deterministic domain planning and stateful subprocess execution (ADR-0001):

flowchart TD
    A[Target URLs / Profiles] --> B[targets.py: Canonicalization & Endpoint Expansion]
    B --> C[planner.py: Pure Functional PlanStep Generator]
    C --> D{NamiService Orchestrator}
    D -->|Acquire File Lock| E[archive.lock]
    D -->|Select Backend| F[gallery-dl Engine]
    F -->|Success| G[Update archive.txt & Emit BatchResult]
    F -->|FailureKind.EXTRACTOR| H[Fallback: yt-dlp Engine]
    F -->|Transient Network/Timeout| I[Exponential Jittered Retry]
    H -->|Success| G
    H -->|Exhausted| J[Structured Failure Report]

Core Design Guarantees

1. Pure Planning Layer: targets.py and planner.py compute output paths and executable PlanStep sequences without performing disk I/O or network requests.
2. Subprocess Isolation: Zero shell interpretation (shell=False). Subprocesses execute via discrete argv tuples with full process-tree cleanup upon timeout or cancellation.
3. Atomic File Locking: Download archives (archive.txt) are protected by non-blocking PID-keyed locks (archive.lock) to prevent concurrent process corruption.
4. Path Containment: All output directories are verified against base_dir using safe_target_dir() to prevent path traversal or drive-escaping.

Installation

Requires Python 3.10 or newer.

python -m pip install nami

To update an existing installation:

python -m pip install --upgrade nami

Quickstart

1. Interactive Terminal UI

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

nami
# or
python -m nami

╭─ Nami ───────────────────────────────────────────────────────────── v5.0.4 ─╮
│ 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                                                     │
╰─────────────────────────────────────────────────────────────────────────────╯

2. 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 Hierarchy

Nami/
├── downloads/                     # Output files grouped by platform & account
│   ├── instagram/
│   │   └── natgeo/
│   │       ├── Photos/            # Downloaded image assets
│   │       │   └── archive.txt    # Deduplication tracking record
│   │       ├── Videos/            # Downloaded video assets
│   │       │   └── archive.txt
│   │       └── Stories/           # Downloaded story assets
│   │           └── archive.txt
│   └── tiktok/
│       └── example_user/
│           └── Videos/
│               └── archive.txt
├── cookies/                       # Netscape-format cookie files (*_cookies.txt)
│   ├── instagram_cookies.txt
│   ├── tiktok_cookies.txt
│   ├── facebook_cookies.txt
│   └── x_cookies.txt
└── profiles/                      # Batch target profile lists (*_profiles.txt)
    ├── 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 generate default configuration.

nami setup [OPTIONS]

nami doctor

Run read-only system diagnostic checks without network activity.

nami doctor [OPTIONS]

PASS  config: Configuration file is valid
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

1. Netscape Cookie Files

Place exported cookies into cookies_dir. Nami verifies that files contain genuine 7-column rows before mounting 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

2. Browser Database Session Extraction

For TikTok downloads without an explicit cookie file, Nami extracts session tokens directly from local browser stores (brave, chrome, edge, firefox).

Failure Taxonomy & Retry Policy

failures.py maps engine stderr diagnostics into typed 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.