> ## Documentation Index
> Fetch the complete documentation index at: https://jonathansantilli-codegate-92.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Output formats

> The five output formats CodeGate supports — terminal, json, sarif, markdown, and html — and how to select them with --format and --output.

CodeGate supports five output formats. The default is `terminal`. Use `--format` to select a format and `--output` to write to a file instead of stdout.

```bash theme={null}
codegate scan . --format <type>
codegate scan . --format <type> --output <path>
```

You can also set a persistent default in `~/.codegate/config.json`:

```json theme={null}
{
  "output_format": "json"
}
```

## Formats

<Tabs>
  <Tab title="terminal">
    The default format. Renders an interactive TUI (terminal user interface) when a TTY is available. The TUI presents findings grouped by severity, supports keyboard navigation, and shows inline remediation guidance.

    Disable the TUI to get plain text output suitable for log capture:

    ```bash theme={null}
    codegate scan . --no-tui
    ```

    Add `--verbose` for extended output including additional finding fields:

    ```bash theme={null}
    codegate scan . --verbose
    ```

    The `terminal` format is always used by `codegate run`. Machine-readable formats are only available from `codegate scan`.
  </Tab>

  <Tab title="json">
    Machine-readable JSON output. Each finding is serialised as a full `Finding` object. Suitable for piping into custom tooling, policy engines, or dashboards.

    ```bash theme={null}
    codegate scan . --format json
    codegate scan . --format json --output findings.json
    ```

    Example output structure:

    ```json theme={null}
    {
      "findings": [
        {
          "rule_id": "env-override-api-base",
          "finding_id": "ENV_OVERRIDE-...",
          "severity": "HIGH",
          "category": "ENV_OVERRIDE",
          "layer": "L2",
          "file_path": ".claude/settings.json",
          "description": "Environment variable redirects API base URL to an external host.",
          "affected_tools": ["claude-code"],
          "cve": null,
          "owasp": ["A05:2021"],
          "cwe": "CWE-610",
          "confidence": "HIGH",
          "fixable": true,
          "remediation_actions": ["remove_field", "replace_with_default"],
          "suppressed": false
        }
      ],
      "summary": {
        "total": 1,
        "critical": 0,
        "high": 1,
        "medium": 0,
        "low": 0,
        "info": 0
      }
    }
    ```
  </Tab>

  <Tab title="sarif">
    Static Analysis Results Interchange Format (SARIF) v2.1.0 output. Designed for upload to GitHub Code Scanning and other SARIF-compatible security tooling.

    ```bash theme={null}
    codegate scan . --format sarif --output codegate.sarif
    ```

    Use in a GitHub Actions workflow:

    ```yaml theme={null}
    - name: Run CodeGate
      run: codegate scan . --no-tui --format sarif --output codegate.sarif

    - name: Upload SARIF
      uses: github/codeql-action/upload-sarif@v3
      with:
        sarif_file: codegate.sarif
    ```

    Each finding maps to a SARIF `result` with `ruleId`, `level`, `message`, and `locations`. Rule metadata (CWE, OWASP, description) is included in the `rules` array of the SARIF `tool` object.
  </Tab>

  <Tab title="markdown">
    Markdown report suitable for inclusion in pull request comments, wikis, or documentation systems.

    ```bash theme={null}
    codegate scan . --format markdown --output report.md
    ```

    The report includes a summary table, findings grouped by severity, and remediation guidance in fenced sections.
  </Tab>

  <Tab title="html">
    Self-contained HTML report suitable for sharing as a file or hosting as a static page.

    ```bash theme={null}
    codegate scan . --format html --output report.html
    ```

    The HTML report renders findings in a styled table grouped by severity. No external dependencies or network requests are required to view it.
  </Tab>
</Tabs>

## Format comparison

| Format     | Use case              | Interactive | Machine-readable | File output |
| ---------- | --------------------- | ----------- | ---------------- | ----------- |
| `terminal` | Local development     | Yes (TUI)   | No               | No          |
| `json`     | Pipelines and tooling | No          | Yes              | Optional    |
| `sarif`    | GitHub Code Scanning  | No          | Yes              | Recommended |
| `markdown` | PR comments, wikis    | No          | No               | Optional    |
| `html`     | Shareable reports     | No          | No               | Optional    |

## Exit codes

All formats produce the same exit code regardless of which format is selected.

| Code | Meaning                                                   |
| ---- | --------------------------------------------------------- |
| `0`  | No unsuppressed findings.                                 |
| `1`  | Findings exist below the configured `severity_threshold`. |
| `2`  | Findings at or above the configured `severity_threshold`. |
| `3`  | Scanner or runtime error.                                 |