Nami

An open-source CLI media downloader for Instagram, TikTok, Facebook, and X.

Nami coordinates gallery-dl and yt-dlp through a pure functional planning core and deterministic execution shell. It provides deduplicated archive indexing, multi-attempt failure classification, process isolation, and both interactive Rich terminal UI and scriptable JSON CLI modes.

Table of Contents

• Supported Platforms
• Architecture & Design Principles
• Installation
• Quickstart
• Workspace Layout
• CLI Reference
  • nami setup
  • nami download
  • nami doctor
  • nami config
  • nami archive reset
• Authentication
• Failure Classification & Retry Policy
• Exit Codes
• Development & Testing
• License

Supported Platforms

Unsupported media/platform combinations return structured Outcome.UNSUPPORTED (Exit Code 3) rather than silent failure or fake success.

Architecture & Design Principles

1. Pure Core, Imperative Shell:
   • targets.py: URL parsing, sanitization, canonical host mapping, and media endpoint expansion.
   • planner.py: Pure mapping from Target + MediaKind to deterministic PlanStep sequences without filesystem I/O.
   • retry.py: Stateless retry decision engine with exponential jittered backoff.
   • service.py: Orchestrator executing plan steps behind atomic file locks (archive.lock).
2. Dual-Engine Routing (ADR-0001):
   • Photos, Instagram stories, and highlights route to gallery-dl.
   • Videos route to gallery-dl with automatic fallback to yt-dlp upon FailureKind.EXTRACTOR.
   • Network errors, rate limits, and authentication rejections retry on the same engine without inappropriate cross-engine churn.
3. No Shell Invocations (shell=False):
   • All subprocess arguments are passed as discrete string arrays (argv) to prevent shell injection.
   • Process trees are tracked and terminated via process group signals (SIGTERM / SIGKILL on POSIX, taskkill /PID <PID> /T /F on Windows).
4. Strict Path Containment:
   • Every destination folder is validated against base_dir using safe_target_dir() to prevent path traversal attacks.

Installation

Requires Python 3.10 or newer.

python -m pip install nami

Upgrade to latest release:

python -m pip install --upgrade nami

Quickstart

1. Interactive Terminal UI

Run nami without arguments:

nami

┌──────────────────────── Nami ────────────────────────┐
│ 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                              │
└──────────────────────────────────────────────────────┘

On first launch without configuration, Nami interactively guides setup and workspace initialization.

2. Command-Line Direct Invocations

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

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

# Batch download profiles from configured text files
nami download --profiles --platform instagram --media stories,highlights

Workspace Layout

Nami/
├── downloads/
│   ├── instagram/
│   │   └── natgeo/
│   │       ├── Photos/
│   │       │   └── archive.txt
│   │       ├── Videos/
│   │       │   └── archive.txt
│   │       └── Stories/
│   │           └── archive.txt
│   └── tiktok/
│       └── example_user/
│           └── Videos/
├── cookies/
│   ├── instagram_cookies.txt
│   ├── tiktok_cookies.txt
│   ├── facebook_cookies.txt
│   └── x_cookies.txt
└── profiles/
    ├── instagram_profiles.txt
    ├── tiktok_profiles.txt
    ├── facebook_profiles.txt
    └── x_profiles.txt

CLI Reference

nami setup

Initializes configuration and workspace directories:

# Initialize workspace under specific root
nami setup --root /path/to/parent

# Create empty Netscape cookie template files
nami setup --root . --cookie-templates

# Machine-readable JSON output
nami setup --root . --json

nami download

Executes download planning and execution for URLs and profile lists:

nami download [URL ...] [OPTIONS]

nami doctor

Runs local, read-only diagnostic checks without network I/O:

nami doctor
nami doctor --json

Checks executed:

• Config JSON structure and permissions
• Python version (>= 3.10)
• Core module imports (rich, gallery_dl, yt_dlp)
• Read/write access on base_dir, cookies_dir, and profiles_dir
• Browser installation and process lock check (brave, chrome, edge, firefox)
• Netscape cookie file syntax validation (minimum 7 valid columns)
• Profile file accessibility and syntax validation
• Namespace conflicts (urllib3_future, niquests)
• Stale archive.lock files (> 1 hour old)

nami config

Inspects and updates persistent configuration (~/.nami/nami_config.json):

# Display all configuration
nami config show

# Get specific key
nami config get base_dir
nami config get browser

# Set key
nami config set browser chrome
nami config set timeout_seconds 3600

# Reset key to default
nami config unset browser

# JSON mode
nami config show --json

nami archive reset

Manages download tracking records (archive.txt) safely:

# Dry run preview
nami archive reset --all --dry-run

# Back up archives for target (creates .bak files)
nami archive reset --platform instagram --target natgeo --yes

# Reset specific media kind
nami archive reset --platform instagram --target natgeo --media stories --yes

# Delete matching archives permanently
nami archive reset --platform tiktok --target creator --delete --yes

Authentication

Netscape Cookie Files

Export cookies from your browser using a Netscape-compatible extension and save them into cookies_dir:

• 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, x.com_cookies.txt, or twitter_cookies.txt

Nami validates that cookie files contain valid 7-column rows before passing them to engines.

Browser Cookie DB

When downloading from TikTok without an explicit cookie file, Nami attempts direct cookie extraction from the configured browser (brave, chrome, edge, firefox).

Failure Classification & Retry Policy

failures.py maps error logs to typed FailureKind categories:

Exit Codes

Development & Testing

Setup Environment

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

Running Test Suite

# Run pytest
python -m pytest

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

# Build distribution package
python -m build

License

Distributed under the MIT License. Maintained by Igect under OpenSelena.