Install GitResolve: CLI and npm Package Setup Guide

Install GitResolve via npx, global CLI, or npm project dependency. Covers Node.js 18+ requirements, TypeScript types, browser providers, and env vars.

GitResolve ships as a single npm package (@clyrisai/gitresolve) that covers both the CLI and the programmatic API. You can run it immediately with npx, install it globally for persistent CLI access, or add it as a dependency in your Node.js project. TypeScript types are bundled — no separate @types package is required.

Requirements

GitResolve requires Node.js >= 18.0.0. Check your version before installing:

node --version

No other system dependencies are required for the fetch or Puppeteer providers. Puppeteer is bundled as a direct dependency and installed automatically. For the Browserless provider, you will need a running Docker container — see the Browser Providers guide.

Zero-Install with npx

Run GitResolve on-demand without a permanent installation. This is the fastest way to try it:

npx @clyrisai/gitresolve --help

npx @clyrisai/gitresolve https://github.com/janedoe --json

The npx approach is ideal for one-off lookups or CI jobs where you don’t want to manage a global install. npx will always pull the latest published version.

Global Install

Install globally to make the gitresolve command available in any directory:

npm install -g @clyrisai/gitresolve

After installation, verify it’s working:

gitresolve --version
gitresolve --help

Puppeteer is bundled as a dependency in the package, so it installs automatically for project-level installs via npm. For global installs, Puppeteer’s browser binaries may not be downloaded automatically depending on your npm configuration. If you see errors about a missing Chromium executable when processing JavaScript-heavy portfolio sites, run npm install -g puppeteer to install it alongside GitResolve.

Project Dependency

To use the programmatic API inside your own application, install @clyrisai/gitresolve as a project dependency:

npm

npm install @clyrisai/gitresolve

Then import the functions you need:

import { createProvider, scrapePortfolio, parseResume } from '@clyrisai/gitresolve';

TypeScript Support

TypeScript types are included in the package at ./dist/index.d.ts. No @types/gitresolve package is needed — types work out of the box after install.

All types, values, and functions exported from @clyrisai/gitresolve:

import type {
  InputType,
  GitProvider,
  ParsedRepo,
  GitLinkType,
  ExtractedGitLink,
  ResolverResult,
  BrowserProvider,
  BrowserProviderOptions,
  ProviderName,
} from '@clyrisai/gitresolve';

import {
  // Constants
  GIT_HOSTS,

  // Classifier utilities
  classifyInput,
  parseRepoUrl,
  parseGitLink,
  extractGitUrlsFromText,
  isGitProviderUrl,

  // Scraping & parsing
  scrapePortfolio,
  extractLinksFromHtml,
  parseResume,

  // Disambiguation
  resolveOwnerAndCategorize,
  dedupeProfilesByUsername,

  // Browser providers
  createProvider,
  FetchProvider,
  BrowserlessProvider,
  PuppeteerProvider,
} from '@clyrisai/gitresolve';

Browser Providers

GitResolve’s browser provider is used when scraping portfolio websites and git profile pages. The createProvider() function auto-selects the best available provider using this resolution order: puppeteer → browserless → fetch.

Puppeteer is included as a bundled dependency, so it is available automatically for project-level installs. For global installs, you may need to install it separately if JavaScript rendering is needed.

# Force a specific provider via CLI
gitresolve https://janedoe.dev --provider fetch
gitresolve https://janedoe.dev --provider puppeteer
gitresolve https://janedoe.dev --provider browserless

You can also set the preferred provider for the programmatic API:

import { createProvider } from '@clyrisai/gitresolve';

// Explicit provider selection
const provider = await createProvider('fetch');

// Or let GitResolve auto-select (puppeteer → browserless → fetch)
const autoProvider = await createProvider();

See the Browser Providers guide for Browserless Docker setup instructions.

Environment Variables

GitResolve reads several environment variables to configure runtime behavior. All of them are optional and have sensible defaults.

Variable	Default	Description
BROWSERLESS_URL	http://localhost:3000	URL of a running Browserless instance for the Browserless provider
BROWSER_PROVIDER	Auto-detect	Force a specific provider: puppeteer, browserless, or fetch
PORTFOLIO_CSV	./data/portfolio_links.csv	Path to the CSV file used by --portfolios batch mode
RESUMES_DIR	./data/resumes	Path to the directory of PDF files used by --resumes batch mode

You can set these in a .env file, in your shell profile, or inline before the command:

BROWSER_PROVIDER=fetch gitresolve https://janedoe.dev --json

BROWSERLESS_URL=http://my-server:3000 gitresolve --portfolios

Verify Your Installation

After installing globally, run these two commands to confirm everything is set up correctly:

gitresolve --version

gitresolve --help

You should see the version number (0.1.0) and the full usage output listing all available flags and options.

If gitresolve is not found after a global install, your npm global bin directory may not be on your PATH. Run npm bin -g to find the directory and add it to your shell profile (~/.bashrc, ~/.zshrc, etc.).