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

# GitResolve CLI Output Modes: Terminal, JSON, Files

> Choose between GitResolve's ANSI terminal table, raw JSON to stdout for piping, or per-candidate JSON files written to an output directory on disk.

GitResolve supports three output modes that can be used individually or in combination. The default terminal display is great for interactive use, `--json` makes it easy to pipe results into other tools, and `--output-dir` writes clean per-candidate files suitable for downstream automation.

## Terminal Display (Default)

When neither `--json` nor `--output-dir` is provided, GitResolve prints an ANSI-colored summary table to your terminal. Each processed candidate gets one row with their resolved username, confidence level, number of owned repos, contributions, and any warnings. A summary line is printed at the end showing total resolved and unresolved counts.

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

```
🔍 ClyrisAI GitResolve
────────────────────────────────────────

📂 Portfolio Links (from ./data/portfolio_links.csv)
   Found 3 URL(s)
   ✅ janedoe          [high]     3 repos  1 contribution
   ✅ jsmith           [medium]   1 repo   0 contributions
   ⚠️  alice-lee        [low]      0 repos  0 contributions

📂 Resumes (from ./data/resumes/)
   Found 2 PDF(s)
   ✅ janedoe          (merged with portfolio source)
   ✅ bob-chen         [high]     5 repos  2 contributions

────────────────────────────────────────
Resolved: 3   Unresolved: 1
```

<Note>
  The terminal display is suppressed when `--json` is active, keeping stdout clean for piping.
</Note>

## `--json` Mode

The `--json` flag suppresses all terminal UI output and prints the full results as a JSON array to stdout. Each element is an `AggregatedResult` object. This is the recommended mode when feeding GitResolve output into another tool or script.

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

```json theme={null}
[
  {
    "candidateUsername": "janedoe",
    "sources": ["https://janedoe.dev", "./data/resumes/janedoe.pdf"],
    "sourceTypes": ["portfolio", "resume_file"],
    "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>
  Combine `--json` with `jq` for quick field extraction:

  ```bash theme={null}
  # Extract all resolved usernames
  gitresolve --all --json | jq '[.[] | .candidateUsername] | map(select(. != null))'

  # Get all owned repo URLs for a specific user
  gitresolve https://github.com/janedoe --json | jq '.[0].ownedRepos[].url'

  # Filter to high-confidence results only
  gitresolve --all --json | jq '[.[] | select(.confidence == "high")]'
  ```
</Tip>

## `--output-dir` Mode

The `--output-dir <dir>` flag writes one JSON file per candidate to a directory on disk. GitResolve creates two subdirectories automatically:

* `<dir>/resolved/` — one `<username>.json` file per successfully resolved candidate
* `<dir>/unresolved/` — one `<sanitized_source>_N.json` file per candidate that could not be resolved

```bash theme={null}
gitresolve --all --output-dir ./results
```

### Output Directory Structure

```
results/
├── resolved/
│   ├── janedoe.json
│   ├── jsmith.json
│   └── bob-chen.json
└── unresolved/
    └── alice_lee_pdf_1.json
```

Each file contains the full `AggregatedResult` JSON for that candidate. Unresolved filenames are derived from the first source's basename with non-alphanumeric characters replaced by underscores, followed by an incrementing counter.

<Note>
  The `resolved/` and `unresolved/` subdirectories are created automatically. You do not need to create them in advance.
</Note>

## Combining `--json` and `--output-dir`

Both flags can be used together. When combined, GitResolve writes per-candidate JSON files to disk **and** prints the full JSON array to stdout simultaneously. This is useful for saving a permanent archive while also piping the results into a downstream script in one step.

```bash theme={null}
gitresolve --all --json --output-dir ./results | jq '[.[] | .candidateUsername]'
```

The two outputs are independent — the files on disk are not affected by what you pipe stdout into.

## `AggregatedResult` Schema

Every output mode produces `AggregatedResult` objects. The table below describes every field.

| Field               | Type                                    | Description                                                                                                                  |
| ------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `candidateUsername` | `string \| null`                        | Resolved Git username, or `null` if no profile could be identified                                                           |
| `sources`           | `string[]`                              | All input sources (URLs and file paths) that contributed to this result                                                      |
| `sourceTypes`       | `InputType[]`                           | Classification of each source: `portfolio`, `git_profile`, `repo_url`, `resume_file`, `resume_url`, `linkedin`, or `unknown` |
| `ownerProfile`      | `ExtractedGitLink \| null`              | The best-guess owner profile link, or `null` if unresolved                                                                   |
| `confidence`        | `"high" \| "medium" \| "low" \| "none"` | How confident GitResolve is that the correct owner was identified                                                            |
| `ownedRepos`        | `ExtractedGitLink[]`                    | Repository links where the owner username matches `candidateUsername`                                                        |
| `contributions`     | `ExtractedGitLink[]`                    | Explicit pull request and issue links attributed to the candidate                                                            |
| `externalRepos`     | `ExtractedGitLink[]`                    | Repository links owned by other users (external references found on the page)                                                |
| `allLinks`          | `ExtractedGitLink[]`                    | All Git links extracted from all sources, unfiltered                                                                         |
| `warnings`          | `string[]`                              | Non-fatal messages such as unresolvable input types or scraping errors                                                       |

### `ExtractedGitLink` Fields

Each link object inside `ownedRepos`, `contributions`, `externalRepos`, and `allLinks` has the following shape:

| Field      | Type                                                                    | Description                                                                |
| ---------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `url`      | `string`                                                                | The normalized URL of the link                                             |
| `provider` | `"github" \| "gitlab" \| "bitbucket"`                                   | The Git hosting provider                                                   |
| `type`     | `"profile" \| "repo" \| "gist" \| "pull_request" \| "issue" \| "other"` | The kind of Git link                                                       |
| `username` | `string`                                                                | The owner or author username extracted from the URL path                   |
| `repo`     | `string` *(optional)*                                                   | Repository name, present when `type` is `repo`, `pull_request`, or `issue` |
| `number`   | `string` *(optional)*                                                   | PR or issue number, present when `type` is `pull_request` or `issue`       |

### Confidence Levels

| Value    | Meaning                                                                                     |
| -------- | ------------------------------------------------------------------------------------------- |
| `high`   | A Git profile URL was the direct input, or a single username dominated all discovered links |
| `medium` | A username was inferred from multiple links but with some ambiguity                         |
| `low`    | A username was found but evidence was sparse or conflicting                                 |
| `none`   | No Git profile could be identified from the input                                           |

<Warning>
  A `confidence` of `"none"` does not always indicate an error. LinkedIn URLs, unknown input types, and pages with no Git links all produce `"none"` by design. Check the `warnings` array for a human-readable explanation.
</Warning>