> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/clyrisai/gitresolve/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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](/providers/overview) guide.

## Zero-Install with npx

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

```bash theme={null}
npx @clyrisai/gitresolve --help
```

```bash theme={null}
npx @clyrisai/gitresolve https://github.com/janedoe --json
```

<Tip>
  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.
</Tip>

## Global Install

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

```bash theme={null}
npm install -g @clyrisai/gitresolve
```

After installation, verify it's working:

```bash theme={null}
gitresolve --version
gitresolve --help
```

<Note>
  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.
</Note>

## Project Dependency

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

<CodeGroup>
  ```bash npm theme={null}
  npm install @clyrisai/gitresolve
  ```

  ```bash pnpm theme={null}
  pnpm add @clyrisai/gitresolve
  ```

  ```bash yarn theme={null}
  yarn add @clyrisai/gitresolve
  ```

  ```bash bun theme={null}
  bun add @clyrisai/gitresolve
  ```
</CodeGroup>

Then import the functions you need:

```typescript theme={null}
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`:

```typescript theme={null}
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.

```bash theme={null}
# 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:

```typescript theme={null}
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](/providers/overview) 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:

```bash theme={null}
BROWSER_PROVIDER=fetch gitresolve https://janedoe.dev --json
```

```bash theme={null}
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:

```bash theme={null}
gitresolve --version
```

```bash theme={null}
gitresolve --help
```

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

<Warning>
  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.).
</Warning>