Install Guide

FETCHIT is distributed as a standalone binary, an npm package, and source code. You can install it on macOS, Linux, and Windows using any of the methods below. Choose the approach that best fits your environment — whether you are setting up a dev machine, provisioning a CI pipeline, or deploying to a Docker container.

System requirements

Before installing, make sure your environment meets these minimum requirements.

• Operating system: macOS 12+ (Intel & Apple Silicon), Windows 10+ (x64), or Linux (x64, glibc ≥ 2.28, or musl-based distros like Alpine 3.17+). ARM Linux is supported experimentally — binaries are built for aarch64.
• Architecture: x86_64 (amd64) and aarch64 (ARM64). 32-bit systems are not supported.
• Disk space: Approximately 250 MB free after installation — ~100 MB for the binary, ~100 MB for the bundled yt-dlp engine, and headroom for temporary downloads and cache.
• Permissions: The installer script needs write access to ~/.fetchit. The npm install path may require sudo on POSIX systems depending on your Node.js setup. On Windows, admin rights are not required unless you are installing a system-wide npm package.
• Network: Outbound HTTPS access to github.com, registry.npmjs.org, and fetchit-cli.vercel.app.

Quick start (one-liner)

The recommended way to install fetchit for most users. The installer auto-detects your platform, downloads the correct binary, sets up PATH, and pre-fetches the yt-dlp engine — all in a single command.

Multi-Platform Installation

Select your operating system or package manager below to get the recommended one-line installation command:

The PowerShell variant uses Invoke-RestMethod (irm) to download the installer script and Invoke-Expression (iex) to execute it in one pipeline.

What the installer script does, step by step

Understanding the installer helps you debug issues and know exactly what changes are made to your system.

1. Platform detection. The script reads uname -s and uname -m (or PROCESSOR_ARCHITECTURE on Windows) to select the correct binary archive. It supports darwin / linux / win32 on x86_64 and aarch64. If the platform is unknown, the script exits with a clear error message listing supported targets.
2. Node.js check (optional shortcut). If node --version reports 18 or higher, the script offers to install via npm instead of the standalone binary (unless the --binary flag is passed). This produces a smaller install and integrates with your existing Node.js toolchain.
3. Binary download. The script fetches the latest release tarball from https://github.com/Vedant1521/fetchit/releases/latest. It uses curl (or Invoke-WebRequest on Windows) with a 30-second timeout and retries on failure. The archive is streamed and extracted in memory to avoid leaving temp files.
4. Installation directory. The binary is placed at ~/.fetchit/bin/fetchit (or ~\.fetchit\bin\fetchit.exe on Windows). This directory is created if it does not exist. If a previous installation is detected, the old binary is backed up as fetchit.old before replacement.
5. PATH configuration. The script appends the binary directory to your shell profile: ~/.bashrc, ~/.zshrc, ~/.config/fish/config.fish, or the PowerShell profile ($PROFILE). It uses grep to avoid duplicate entries. If the profile is read-only or cannot be detected, a warning is printed with manual instructions.
6. Engine pre-fetch. fetchit downloads the yt-dlp engine on first use. The installer runs fetchit doctor immediately to trigger this download so that the first real command is fast. If the download fails (e.g. no network), the installation still succeeds — the engine is fetched lazily on first invocation.
7. Cleanup & verification. Temporary files are removed and the script prints the installed version via fetchit --version. If the binary does not run (e.g. missing glibc version), the script falls back to the npm installation path automatically.

The installer script is open source and auditable. You can inspect it at scripts/install.sh or scripts/install.ps1 before running it.

Install via npm

If you already work with Node.js, installing fetchit through npm keeps everything within your existing package manager workflow. The npm package is a thin wrapper that installs the platform-specific binary as a dependency.

Global installation

npm install -g @vedant1521/fetchit

This installs fetchit globally so the fetchit command is available in your terminal. On POSIX systems, global installs are often placed in /usr/local/lib/node_modules; you may need sudo or a configured npm prefix. On Windows, the executable is placed in %APPDATA%\npm, which is typically already on your PATH.

Version pinning

npm install -g @vedant1521/fetchit@1.2.3

Pinning to a specific version is recommended for production environments and CI/CD pipelines. This prevents unexpected breaking changes when new versions are published. Check the releases page for available versions.

Verifying the npm install

npm list -g @vedant1521/fetchit
fetchit --version

The first command confirms the package is installed in the global registry. The second prints the semantic version of the binary. If the version does not match what you expected, run npm outdated -g @vedant1521/fetchit to check for newer releases.

Run without installing (npx)

npx @vedant1521/fetchit

The npx runner downloads and caches the latest fetchit package on demand. It is perfect for one-off uses, quick tests, or CI steps where you do not want to manage a global install. The cache lives in ~/.npm/_npx and is cleaned automatically.

Build from source

Building fetchit from source gives you full control over the compilation process. This is useful for contributing patches, testing unreleased changes, or customising the build for a non-standard environment.

Prerequisites

• Node.js version 18 or later. Verify with node --version. We recommend the latest LTS release.
• npm version 9 or later (ships with Node.js 18+).
• Git to clone the repository.
• Bun (optional) — required only if you want to generate a standalone binary via scripts/build-binary.js. Install with curl -fsSL https://bun.sh/install | bash.
• C/C++ build tools — native modules are compiled from source. On macOS, install Xcode Command Line Tools (xcode-select --install). On Linux, install build-essential (Debian/Ubuntu) or base-devel (Arch). On Windows, install windows-build-tools via npm install --global windows-build-tools.

Step-by-step

Follow these steps exactly. Each stage has been tested on macOS, Ubuntu 22.04, and Windows Server 2022.

1. Clone the repository.
   BASH

   Try in Playground

   git clone https://github.com/Vedant1521/fetchit.git
   cd fetchit

   This fetches the full history. If you only want the latest revision, add --depth 1 to the clone command.
2. Install dependencies.
   NPM

   Try in Playground

   npm install

   This resolves and installs all Node.js dependencies listed in package.json. Native addons are compiled from source during this step, which is why build tools are required.
3. Build the project.
   NPM

   Try in Playground

   npm run build

   The build script runs the TypeScript compiler (tsc) and bundles the output. If the build fails, check that your TypeScript version matches the one in package.json and that there are no type errors.
4. Link the CLI (optional).
   NPM

   Try in Playground

   npm link

   This creates a symlink in your global npm prefix so you can run fetchit from any directory without specifying the path. Useful during development.

Generate a standalone binary

Building a standalone binary bundles the entire CLI along with a Node.js runtime into a single executable. This binary does not require Node.js to be installed on the target machine.

npm install
bun scripts/build-binary.js

The output binary is placed at dist/fetchit on macOS and Linux, or dist/fetchit.exe on Windows. The binary is approximately 100 MB because it embeds the Node.js runtime and all dependencies.

You can move this binary to any directory on your PATH and run it independently. No additional DLLs, shared libraries, or runtimes are required.

Docker installation

fetchit is available as a Docker image for containerised environments. The image is based on node:22-alpine and includes the binary pre-installed.

Pull the image

docker pull ghcr.io/vedant1521/fetchit:latest

Run a one-off command

docker run --rm ghcr.io/vedant1521/fetchit fetchit --help

Use as a base image

FROM ghcr.io/vedant1521/fetchit:latest AS fetchit
# ... your build steps

COPY --from=fetchit /usr/local/bin/fetchit /usr/local/bin/fetchit

Docker Compose

services:
  fetcher:
    image: ghcr.io/vedant1521/fetchit:latest
    command: ["fetchit", "download", "https://example.com/video", "-o", "/data/video.mp4"]
    volumes:
      - ./data:/data

CI/CD installation

Integrate fetchit into your continuous integration pipelines. These recipes work with GitHub Actions, GitLab CI, and CircleCI out of the box.

GitHub Actions

- name: Install fetchit
  run: curl -fsSL https://fetchit-cli.vercel.app/install.sh | sh

- name: Use fetchit
  run: fetchit download <url> -o output.mp4

For faster installs, use the npm route (GitHub Actions runners have Node.js pre-installed):

- name: Install fetchit (npm)
  run: npm install -g @vedant1521/fetchit@1.2.3

- name: Verify
  run: fetchit --version

GitLab CI

install-fetchit:
  before_script:
    - curl -fsSL https://fetchit-cli.vercel.app/install.sh | sh
  script:
    - fetchit download <url> -o output.mp4

CircleCI

version: 2.1
jobs:
  download:
    docker:
      - image: cimg/node:22.0
    steps:
      - run: npm install -g @vedant1521/fetchit
      - run: fetchit --version

Installing a specific version

You may need to install an older release for compatibility reasons or pin to a specific version for reproducible builds.

One-liner with version flag

curl -fsSL https://fetchit-cli.vercel.app/install.sh | sh -s -- --version 1.2.3

The --version flag overrides the default "latest" behaviour. The installer resolves the version tag against the GitHub Releases API.

npm with exact version

npm install -g @vedant1521/fetchit@1.2.3

Direct binary download

You can skip the installer entirely and download the binary archive directly from GitHub:

# macOS (Apple Silicon)
curl -fsSL https://github.com/Vedant1521/fetchit/releases/download/v1.2.3/fetchit-darwin-arm64.tar.gz | tar xz -C /usr/local/bin

# Linux (x64)
curl -fsSL https://github.com/Vedant1521/fetchit/releases/download/v1.2.3/fetchit-linux-x64.tar.gz | tar xz -C /usr/local/bin

# Windows (x64) via PowerShell
Invoke-WebRequest -Uri "https://github.com/Vedant1521/fetchit/releases/download/v1.2.3/fetchit-win32-x64.zip" -OutFile fetchit.zip
Expand-Archive -Path fetchit.zip -DestinationPath "$env:LOCALAPPDATAetchit"

Verifying your installation

After installation, run these checks to confirm everything works correctly.

Check the version

fetchit --version

Prints the installed semantic version (e.g. 1.2.3). If this command fails, fetchit is not on your PATH.

Run the doctor command

fetchit doctor

The doctor command runs a comprehensive health check: it verifies the binary integrity, checks that the yt-dlp engine is present and up to date, confirms network connectivity to the YouTube API, and validates your configuration file. If any check fails, it prints a descriptive error and suggested fix.

Test a real download

fetchit --best "https://www.youtube.com/watch?v=dQw4w9WgXcQ" -o /dev/null

Downloads a short audio stream to /dev/null (or nul on Windows) to validate the full pipeline — engine invocation, streaming, and output. If this succeeds, fetchit is fully operational.

PATH setup (manual)

If the installer could not modify your shell profile — for example, your profile is read-only, stored in a non-standard location, or the auto-detection failed — you can add fetchit to your PATH manually.

macOS / Linux

Add the following line to ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish depending on your shell:

export PATH="$HOME/.fetchit/bin:$PATH"

Then reload your shell configuration:

source ~/.zshrc   # or ~/.bashrc, etc.

Windows

Run this PowerShell command to add the directory to your user PATH permanently:

[Environment]::SetEnvironmentVariable(
  "PATH",
  [Environment]::GetEnvironmentVariable("PATH", "User") + ";$env:USERPROFILE.fetchitin",
  "User"
)

Restart your terminal for the change to take effect.

Upgrading fetchit

Keeping fetchit up to date ensures you have the latest features, bug fixes, and engine compatibility.

Re-run the installer (recommended)

curl -fsSL https://fetchit-cli.vercel.app/install.sh | sh

The installer is idempotent — running it again overwrites the old binary with the latest version, updates the PATH if needed, and re-fetches the yt-dlp engine. Your existing configuration in ~/.fetchit/config.json is preserved.

npm global update

npm update -g @vedant1521/fetchit

Check for updates

fetchit --version
# Then compare with the latest on:
# https://github.com/Vedant1521/fetchit/releases/latest

fetchit does not phone home for version checks. You are responsible for keeping it updated. Subscribe to the GitHub releases RSS feed to receive notifications.

Uninstalling fetchit

Removing fetchit completely involves deleting the binary, its data directory, and optionally the npm global package.

Standalone binary install

rm -rf ~/.fetchit

This removes the binary, the yt-dlp engine, downloaded cache files, and configuration. If you also added PATH entries manually, remove the relevant lines from your shell profile.

npm install

npm uninstall -g @vedant1521/fetchit

This removes the npm package. Global binaries linked by npm are deleted automatically. The ~/.fetchit data directory is not removed by npm — delete it separately if you want a clean sweep.

Complete removal (all paths)

rm -rf ~/.fetchit
npm uninstall -g @vedant1521/fetchit
# Also remove any manually downloaded binaries
rm /usr/local/bin/fetchit   # if you placed it here

Platform-specific troubleshooting

If you run into issues, consult the section for your operating system. Most problems have straightforward workarounds.

Windows

• SmartScreen / Windows Defender. The first time you run the .exe, Windows may show "Windows protected your PC." Click "More info" then "Run anyway." This happens because the binary is not code-signed. You can verify the binary's SHA-256 checksum against the published hash in the release notes.
• PowerShell execution policy. If you see "running scripts is disabled on this system," run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned and try again. This allows locally downloaded scripts to run.
• Path too long. The installer places the binary in %USERPROFILE%\.fetchit\bin. If your username contains spaces, the path is quoted automatically. If you encounter "command not found" after installation, restart your terminal or add the path manually (see PATH setup above).
• Antivirus false positives. Some antivirus software may flag the standalone binary because it embeds a Node.js runtime. This is a known false positive. Add the binary to your antivirus exclusion list or use the npm installation method instead.
• Node.js not found after npm install. If npm install -g succeeds but fetchit is not recognized, ensure your npm global bin directory is on PATH. Run npm config get prefix and add the bin subdirectory to your PATH.

macOS

• Gatekeeper. The binary is not notarised by Apple. When you run it for the first time, macOS may show "fetchit cannot be opened because the developer cannot be verified." Right-click the binary in Finder, select "Open," and confirm the dialog. This adds a security exception for that specific binary.
• Quarantine attribute. If you prefer the command line, remove the quarantine extended attribute manually:
  BASH

  Try in Playground

  xattr -d com.apple.quarantine ~/.fetchit/bin/fetchit

  This tells macOS that the binary has been vetted by you.
• Apple Silicon (M1/M2/M3). The ARM64 binary is a native build — it does not run through Rosetta 2. Performance is equivalent to Intel builds. If you are using npm, Node.js must also be ARM-native; an x64 Node.js will work but runs under Rosetta with slightly lower performance.
• macOS 15 (Sequoia) compatibility. fetchit is tested on Sequoia. If you encounter permission prompts for network access, grant them in System Settings > Privacy & Security.
• Code signing identity. If you are building from source and distribute the binary internally, you can self-sign it with codesign -s "Your Identity" dist/fetchit to suppress Gatekeeper warnings.

Linux

• glibc version mismatch. The prebuilt binary is linked against glibc 2.28 (equivalent to RHEL 8 / Ubuntu 20.04). If your system uses an older glibc (e.g. CentOS 7), the binary will fail with version GLIBC_2.28 not found. In this case, use the npm installation method or build from source.
• musl-based distros (Alpine). A separate musl-linked binary is provided for Alpine Linux. The installer auto-detects musl via /lib/ld-musl-x86_64.so.1 existence. If the installer picks the wrong binary, force the install with --target linux-musl-x64.
• Missing shared libraries. Though the binary is statically linked, certain system calls (e.g. DNS resolution via libnss) may depend on system libraries. If you see Error: spawn ENOENT, ensure /etc/resolv.conf is present and ca-certificates is installed.
• Permissions on /usr/local/bin. If you manually place the binary in a system directory, you may need sudo. Prefer ~/.local/bin or ~/.fetchit/bin to avoid permission issues.
• SELinux / AppArmor. On security-hardened distros, the binary may be restricted. Check audit.log for AVC denials. You can add a local policy module or run fetchit from an unconfined domain.

Environment variables that affect installation

The installer and fetchit itself respect several environment variables. Setting these can alter behaviour without modifying command-line arguments.

Example usage:

FETCHIT_VERSION=1.2.3 FETCHIT_BINARY_DIR=/opt/fetchit curl -fsSL https://fetchit-cli.vercel.app/install.sh | sh

Installing in air-gapped / offline environments

If your machine has no internet access, you can still install fetchit using a side-loaded approach:

1. On a machine with internet, download the binary archive from the GitHub Releases page for your target platform.
2. Transfer the archive via USB drive, internal network share, or your organisation's artifact repository.
3. Extract the archive and place the binary in a directory on PATH (e.g. /usr/local/bin or ~/.fetchit/bin).
4. The yt-dlp engine will not be available offline. Pass --engine-path /path/to/yt-dlp to each invocation if you have a local copy, or download it separately from yt-dlp's releases.

Next steps

Now that fetchit is installed, read the Usage Guide to learn how to download videos, extract audio, manage playlists, and customise output formats. Run fetchit --help any time for a quick reference of all commands and flags.