---
title: Install the CLI and trace your first issue
description: Install issue-graph from npm, sign in with GitHub CLI, trace your first issue, and save the result as JSON or an HTML explorer.
url: "https://issue-graph.dev/docs/get-started"
docs_index: /llms.txt
lastUpdated: "2026-09-27T00:00:00.000Z"
navTitle: "Get started"
canonical_url: "https://issue-graph.dev/docs/get-started"
---

# Install the CLI and trace your first issue

> For an index of all documentation, see [/llms.txt](/llms.txt).

## Prerequisites

- Node.js 20 or later
- [GitHub CLI](https://cli.github.com) on your `PATH`
- Read access to the repositories you want to query

## Install from npm

```bash
npm install --global issue-graph@latest
issue-graph --help
```

To run the [npm package](https://www.npmjs.com/package/issue-graph) without a global installation:

```bash
npx issue-graph@latest --help
```

In any CLI example, you can replace `issue-graph` with `npx issue-graph@latest`.

These docs follow the repository's `main` branch, which can be ahead of the published package. Run `issue-graph --help` to see the commands supported by your installed release. If a command is missing, install a release that includes it or build from source as described in [Optional source development](#optional-source-development).

## Authenticate GitHub

```bash
gh auth login
issue-graph auth status
```

issue-graph uses your GitHub CLI credentials. `issue-graph auth status` reports sign-in state without printing tokens. For GitHub CLI diagnostics, run `gh auth status`. To query a private repository, your account needs access to it and any SSO authorization the organization requires.

## Trace an issue

Start with [agent-browser issue #1113](https://github.com/vercel-labs/agent-browser/issues/1113):

```bash
issue-graph graph vercel-labs/agent-browser#1113 --depth 1 --budget 12 --no-save
```

You can also pass the issue URL:

```bash
issue-graph graph https://github.com/vercel-labs/agent-browser/issues/1113 --depth 1 --budget 12 --no-save
```

The command prints a formatted report in a terminal and Markdown when piped. This example, captured on 2026-09-22, found a merged fix and two open follow-ups:

| Issue or PR                                                             | Captured state | Description                        |
| ----------------------------------------------------------------------- | -------------- | ---------------------------------- |
| [Issue #1113](https://github.com/vercel-labs/agent-browser/issues/1113) | CLOSED         | Original orphaned Chrome report    |
| [PR #1137](https://github.com/vercel-labs/agent-browser/pull/1137)      | MERGED         | Fix linked to #1113                |
| [Issue #1148](https://github.com/vercel-labs/agent-browser/issues/1148) | CLOSED         | Regression after the fix           |
| [Issue #1371](https://github.com/vercel-labs/agent-browser/issues/1371) | OPEN           | Chrome Helper using high CPU       |
| [Issue #1607](https://github.com/vercel-labs/agent-browser/issues/1607) | OPEN           | GUI Chrome launch problem on macOS |

Each run queries GitHub, so your results may differ. The flags limit the crawl to depth 1 and 12 fetched nodes, and `--no-save` skips saving a new snapshot. Before you act on the report, check its missing references and limits. See [Graph](/docs/graph) for the capture details and crawl limits.

## Save an explorer

To save the results, add `-o` with a `.json` or `.html` path:

```bash
issue-graph graph vercel-labs/agent-browser#1113 --depth 1 --budget 12 --no-save -o graph.json -o graph.html
```

Open `graph.html` in your browser. If you move it, move its sibling `_next/` directory and `font-LICENSE.txt` with it. Export paths write files even with `--no-save` and replace existing files, so choose new filenames to keep earlier results.

To filter results from the CLI and get an exact dashboard link, save a model first:

```bash
issue-graph open vercel-labs/agent-browser --no-open
issue-graph query github:vercel-labs/agent-browser --state open --kind Issue --view rank --json --open
```

The first command collects data from GitHub within its crawl budget. The second reads the saved data offline, makes no GitHub requests, and returns a `viewUrl` for the matching dashboard view. See [Dashboard and saved queries](/docs/dashboard) for Heat, clusters, replay, and scoring defaults.

## Update

```bash
npm install --global issue-graph@latest
```

After updating, run `issue-graph --help` to see the commands the new release supports.

## Troubleshooting

If your shell cannot find `issue-graph`, check that npm's global bin directory is on your `PATH`, or run the CLI with `npx issue-graph@latest`. For GitHub access errors, run `gh auth status` and check your repository permissions and SSO authorization.

## Optional source development

To build from source, use pnpm and Node.js 20.19.x or 22.12 and later. Node.js 24 is recommended.

```bash
gh repo clone vercel-labs/issue-graph
cd issue-graph
pnpm install --frozen-lockfile
pnpm build
node dist/bin.js --help
```

Continue with [Graph](/docs/graph), [Status and history](/docs/status), or [Agents and skills](/docs/agents).

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)