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

# Quickstart: Resolve Your First Git Profile with GitResolve

> Go from zero to a resolved GitHub profile in minutes. This guide covers the GitResolve CLI, resume PDF parsing, and the TypeScript programmatic API.

This guide walks you through resolving your first candidate profile using GitResolve. You'll run the CLI against a live GitHub profile URL, parse a local resume PDF, and then wire up the programmatic TypeScript API for use inside your own application — all with zero required configuration.

<Steps>
  ### Install GitResolve

  The fastest way to try GitResolve is with `npx` — no installation required:

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

  For repeated use, install it globally so the `gitresolve` command is always available:

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

  <Note>
    Puppeteer is bundled as a direct dependency and is installed automatically alongside GitResolve. No manual Puppeteer setup is needed for local or project installs. For global installs, you may need to run `npm install -g puppeteer` separately if JavaScript rendering is required for SPA portfolio sites.
  </Note>

  ### Resolve a GitHub Profile via the CLI

  Pass any GitHub (or GitLab, Bitbucket) profile URL directly as the first argument:

  ```bash theme={null}
  gitresolve https://github.com/janedoe
  ```

  GitResolve will classify the input as `git_profile`, scrape the page, extract all repository links, disambiguate ownership, and print a formatted summary to your terminal.

  To get machine-readable output instead, add the `--json` flag:

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

  This outputs the full `ResolverResult` as JSON, which you can pipe to `jq` or redirect to a file:

  ```bash theme={null}
  gitresolve https://github.com/janedoe --json | jq '.ownerProfile'
  ```

  **Example JSON output shape:**

  ```json theme={null}
  {
    "source": "https://github.com/janedoe",
    "sourceType": "git_profile",
    "ownerProfile": {
      "url": "https://github.com/janedoe",
      "provider": "github",
      "type": "profile",
      "username": "janedoe"
    },
    "confidence": "high",
    "ownedRepos": [
      {
        "url": "https://github.com/janedoe/my-project",
        "provider": "github",
        "type": "repo",
        "username": "janedoe",
        "repo": "my-project"
      }
    ],
    "contributions": [],
    "externalRepos": [],
    "allLinks": [],
    "warnings": []
  }
  ```

  ### Parse a Resume PDF via the CLI

  Point GitResolve at a local PDF file path to extract git links from both the text content and embedded hyperlink annotations:

  ```bash theme={null}
  gitresolve ./resume.pdf
  ```

  GitResolve detects the `.pdf` extension and automatically classifies the input as `resume_file`. For remote PDF URLs, provide the URL and pass `--type resume` to force resume parsing:

  ```bash theme={null}
  gitresolve https://example.com/candidate-resume.pdf --type resume
  ```

  <Tip>
    The `--type resume` flag is useful when a resume URL doesn't end in `.pdf` — for example, a Google Drive export link or a CDN-hosted file with a generic path.
  </Tip>

  ### Use the Programmatic TypeScript API

  Install GitResolve as a project dependency:

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

  Then import and use the core functions directly in your TypeScript (or JavaScript) backend:

  ```typescript theme={null}
  import { createProvider, scrapePortfolio, parseResume } from '@clyrisai/gitresolve';

  // createProvider() auto-selects: puppeteer → browserless → fetch
  const provider = await createProvider();

  try {
    // Resolve a portfolio site or git profile URL
    const portfolioResult = await scrapePortfolio('https://janedoe.dev', provider);
    console.log('Owner profile:', portfolioResult.ownerProfile);
    console.log('Confidence:', portfolioResult.confidence);
    console.log('Owned repos:', portfolioResult.ownedRepos);
    console.log('Contributions:', portfolioResult.contributions);
    console.log('External repos:', portfolioResult.externalRepos);
    console.log('Warnings:', portfolioResult.warnings);

    // Parse a local resume PDF
    const resumeResult = await parseResume('./resumes/candidate.pdf');
    console.log('Links found in resume:', resumeResult.allLinks.length);
    console.log('Resolved owner:', resumeResult.ownerProfile);
  } finally {
    // Always release browser resources
    await provider.cleanup();
  }
  ```

  <Warning>
    Always call `provider.cleanup()` in a `finally` block. When using the Puppeteer or Browserless provider, failing to clean up will leave a browser process or connection open.
  </Warning>
</Steps>

## ResolverResult Shape

Every resolved input — whether a portfolio URL, a profile link, a repo URL, or a resume PDF — returns a `ResolverResult` object with this shape:

```typescript theme={null}
interface ResolverResult {
  source: string;
  sourceType: InputType;
  ownerProfile: ExtractedGitLink | null;
  confidence: "high" | "medium" | "low" | "none";
  ownedRepos: ExtractedGitLink[];
  contributions: ExtractedGitLink[];
  externalRepos: ExtractedGitLink[];
  allLinks: ExtractedGitLink[];
  warnings: string[];
  error?: string;
}
```

### ResolverResult Fields

| Field           | Type                                    | Description                                                                                                    |
| --------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `source`        | `string`                                | The original input — a URL or a file path                                                                      |
| `sourceType`    | `InputType`                             | Classified type: `portfolio`, `git_profile`, `repo_url`, `resume_file`, `resume_url`, `linkedin`, or `unknown` |
| `ownerProfile`  | `ExtractedGitLink \| null`              | The best resolved git profile for the candidate; `null` if unresolvable                                        |
| `confidence`    | `"high" \| "medium" \| "low" \| "none"` | How confident GitResolve is in the `ownerProfile` resolution                                                   |
| `ownedRepos`    | `ExtractedGitLink[]`                    | Repos where the `username` matches the resolved owner — the candidate's own projects                           |
| `contributions` | `ExtractedGitLink[]`                    | Explicit PR and Issue links extracted — signals open-source activity                                           |
| `externalRepos` | `ExtractedGitLink[]`                    | Repos owned by other users that the candidate has referenced                                                   |
| `allLinks`      | `ExtractedGitLink[]`                    | Every git link found, unfiltered and uncategorized                                                             |
| `warnings`      | `string[]`                              | Non-fatal issues encountered during resolution (e.g. skipped LinkedIn links)                                   |
| `error`         | `string \| undefined`                   | Set if a fatal error occurred during processing                                                                |

## What's Next

<CardGroup cols={2}>
  <Card title="CLI Guide" icon="terminal" href="/cli">
    Explore all CLI flags including batch processing with --portfolios, --resumes, and --output-dir.
  </Card>

  <Card title="API Reference" icon="code" href="/api/overview">
    Full reference for every exported function and type in the programmatic API.
  </Card>

  <Card title="Browser Providers" icon="globe" href="/providers/overview">
    Learn how to configure Puppeteer, Browserless, and the fetch provider for different environments.
  </Card>

  <Card title="Installation" icon="download" href="/installation">
    All install options, environment variables, and TypeScript setup details.
  </Card>
</CardGroup>