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

# Process a Single URL or File with the GitResolve CLI

> Pass any portfolio, GitHub profile, GitLab URL, repo link, or resume PDF as a positional argument and resolve it to a structured candidate profile.

The simplest way to use GitResolve is to pass a single URL or local file path as a positional argument. GitResolve automatically classifies the input, selects the right processing strategy, and prints a resolved candidate profile to your terminal.

## Basic Usage

```bash theme={null}
gitresolve <url-or-path>
```

The `<url-or-path>` argument accepts any of the input types documented below. You do not need to specify a mode flag — GitResolve infers what the input is and handles it accordingly.

## URL Normalization

GitResolve normalizes bare domains before processing so you do not need to type the full `https://` prefix every time.

The following inputs are treated as-is and are **not** prefixed:

* Inputs that already start with `http://` or `https://`
* Local file paths starting with `./`, `/`, or `~/`
* File names ending in `.pdf`, `.doc`, `.docx`, or `.rtf`

Everything else has `https://` prepended automatically:

```bash theme={null}
# These two commands resolve the same page
gitresolve github.com/janedoe
gitresolve https://github.com/janedoe
```

## Supported Input Types

| Input Type        | Example                                 | Processing Strategy                          |
| ----------------- | --------------------------------------- | -------------------------------------------- |
| Portfolio website | `https://janedoe.dev`                   | Scrapes page for Git links                   |
| GitHub profile    | `https://github.com/janedoe`            | Scrapes profile, discovers repos             |
| GitLab profile    | `https://gitlab.com/janedoe`            | Scrapes profile, handles `/users/` routes    |
| Bitbucket profile | `https://bitbucket.org/janedoe`         | Scrapes profile page                         |
| Repository URL    | `https://github.com/janedoe/my-project` | Scrapes repo page, resolves owner            |
| Remote resume PDF | `https://example.com/resume.pdf`        | Downloads PDF, extracts text and links       |
| Local resume PDF  | `./resumes/janedoe.pdf`                 | Reads PDF from disk, extracts text and links |

### Portfolio Website

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

The page is fetched and scraped for any GitHub, GitLab, or Bitbucket URLs. All discovered links are classified, deduped, and organized into owned repos, contributions, and external references.

### GitHub Profile

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

GitResolve detects the `github.com` hostname, recognizes the path as a single-segment user profile, and scrapes the profile page to extract all linked repositories.

### GitLab Profile

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

Both the standard route (`/janedoe`) and the long-form `/users/janedoe` route are handled correctly.

### Bitbucket Profile

```bash theme={null}
gitresolve https://bitbucket.org/janedoe
```

### Repository URL

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

The owner username is extracted from the repo path. GitResolve scrapes the repository page and resolves the owning profile.

### Remote Resume PDF

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

GitResolve fetches the PDF, saves it to a temporary file, and extracts both the raw text content and any embedded hyperlink annotations. All Git URLs found are classified and returned.

### Local Resume PDF

```bash theme={null}
gitresolve ./resumes/janedoe.pdf
```

Local file paths are read directly from disk. The `.pdf` extension — or the leading `./`, `/`, or `~/` — prevents URL normalization from prepending `https://`.

<Note>
  To process a directory of local PDF resumes, use `--resumes` or `--resumes-dir` batch mode instead of the single-URL argument. See [Batch Processing](/cli/batch-processing) for details.
</Note>

## The `--type` Flag

When GitResolve cannot determine the input type from the URL alone — for example, a resume hosted behind a redirect or a URL without a `.pdf` extension — use `--type` to provide a hint.

```bash theme={null}
# Force a URL to be treated as a resume PDF
gitresolve https://storage.example.com/candidate-cv --type resume

# Force a URL to be treated as a portfolio page
gitresolve https://example.com/about --type portfolio
```

Accepted values are `portfolio` and `resume`. The `--type` flag overrides the classifier but only applies to the single-URL mode — it is ignored during batch processing.

## Classification Pipeline

When you pass a URL, GitResolve runs through the following steps before any network request is made:

<Steps>
  <Step title="Normalize input">
    The raw input string is checked for a protocol prefix, file extension, and local path markers. A `https://` prefix is prepended if needed.
  </Step>

  <Step title="Classify input type">
    The classifier checks the hostname against known Git providers (`github.com`, `gitlab.com`, `bitbucket.org`), runs a repo-URL parser to distinguish profile URLs from repo URLs, and flags URLs with document extensions as resume inputs. Any other valid URL is classified as a `portfolio`.
  </Step>

  <Step title="Select processing strategy">
    Resume URLs are routed to the PDF fetcher and parser. Portfolio pages, Git profiles, and repo URLs are routed to the portfolio scraper with the appropriate browser provider.
  </Step>

  <Step title="Scrape or parse">
    For portfolio and Git URLs, the page is fetched (via `fetch`, Puppeteer, or Browserless) and all Git URLs are extracted from the HTML. For remote resume PDFs, the file is downloaded to a temporary path and text content and hyperlink annotations are extracted.
  </Step>

  <Step title="Disambiguate owner">
    All discovered links are analysed to determine which username appears most frequently as an owner. That username becomes the `ownerProfile`, and links are sorted into `ownedRepos`, `contributions`, and `externalRepos`.
  </Step>

  <Step title="Return result">
    A structured `AggregatedResult` object is printed to the terminal (or emitted as JSON if `--json` is set).
  </Step>
</Steps>

## JSON Output

Add `--json` to suppress the ANSI terminal UI and print a raw JSON array to stdout instead. The single-URL mode still returns an array — it will contain one `AggregatedResult` object.

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

```json theme={null}
[
  {
    "candidateUsername": "janedoe",
    "sources": ["https://github.com/janedoe"],
    "sourceTypes": ["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": []
  }
]
```

<Tip>
  Pipe `--json` output directly to `jq` for quick field extraction:

  ```bash theme={null}
  gitresolve https://github.com/janedoe --json | jq '.[0].ownerProfile'
  ```
</Tip>

## Unresolvable Input Types

Some input types are recognized by the classifier but cannot be resolved to a Git profile. In these cases the result will always have `confidence: "none"`, `ownerProfile: null`, and a human-readable explanation in the `warnings` array.

### LinkedIn URLs

LinkedIn URLs are classified with an `InputType` of `linkedin`. GitResolve **does not scrape LinkedIn pages** — passing a LinkedIn URL returns a result with `confidence: "none"` and a warning explaining that LinkedIn cannot be resolved. Use a portfolio URL or a direct Git profile link instead.

<Note>
  LinkedIn classification exists to give you a clear warning rather than a silent failure. If a candidate's only provided link is LinkedIn, you will see the URL echoed back with an explanatory message in `warnings`.
</Note>

### Unknown Input Types

If the classifier cannot determine a URL's type — for example, a short-link redirect or an unrecognized hostname that is neither a known Git provider nor a portfolio-style domain — the input is classified as `unknown`. Like `linkedin`, an `unknown` input type cannot be resolved: the result will have `confidence: "none"` and a warning of the form `"Input classified as 'unknown' — cannot resolve"`.

```bash theme={null}
# Example: an unrecognized short-link
gitresolve https://bit.ly/candidate-profile
# → confidence: "none", warnings: ["Input classified as 'unknown' — cannot resolve"]
```