Install the CLI
Install from npm with Node.js 22 or newer. Git is also required. Standalone binaries are available if you prefer not to install Node.js.
npm install --global github-comment-cli gh-comment --help
A small CLI for thoughtful reviews
Write the comment. Keep the context.
Turn a Markdown report into pull request comments, resolvable threads, or one batched review. Point to local source lines, attach images or video, and preview before publishing.
Open source · Node.js 22+ · GitHub.com pull requests
review.mdMARKDOWN
Write in your editor
## Review notes The [name check](examples/demo.js:3-5) should reject empty input.
gh-comment post review.md --pr 123
Source line link → PR head commit SHA
Markdown in, reviews out
Publish PR comments, resolvable threads, or a summary with inline findings.
Links that stay put
Local line references become verified URLs pinned to the PR head.
Safe to rerun
Exact duplicates are skipped; keyed reports update one comment.
The first five minutes
From a local file to a useful PR comment.
Install the CLI, write a report in the code checkout, and see exactly what GitHub will receive before you post.
Write a report
In your code repository, save review.md. Replace the path and line numbers below with a tracked file in your checkout.
## Review notes The [validation](src/service.ts:12-18) should reject empty input.
Preview, then post
Inspect the comment layout in a browser, check planned actions, then publish.
gh-comment preview review.md --pr 123 gh-comment post review.md --pr 123 --dry-run gh-comment post review.md --pr 123
Before posting
Commit and push the referenced code so it matches the PR head. For authenticated access, use gh auth login, GH_TOKEN, or GITHUB_TOKEN. The included GitHub App helper can mint a token for a bot identity; the README covers its optional setup page. Posting and the default dry run need authentication.
For contributors
Build and run from source.
For source development, use Node.js 22.13+ on the 22 line, or Node.js 24+, and Git; ESLint 10 requires this version range. npm ci installs dependencies and runs the TypeScript build, so the CLI is ready to run from this checkout. The installed CLI still supports Node.js 22+.
npm ci node bin/gh-comment.js --help npm run check npm test npm run smoke:package
With Bun 1.4.2 installed, also run npm run test:bun. With Deno 2.9.6 installed, run npm run test:deno. Node.js still handles compilation.
Built for real reports
Keep the detail. Lose the busywork.
Use the Markdown you already write. The CLI validates references and prepares the comment body before it sends anything to GitHub.
Permanent code references
Write [check](src/file.ts:42-48). The CLI checks that those lines match the selected commit, then turns the link into a permanent GitHub URL.
Native media attachments
With a supported user token, include a local Markdown image or video, or add one with --attach. The uploaded asset appears in the comment.
Multiple notes, one file
Put <!-- gh-comment:next --> on its own line to publish separate entries in file order. Each entry can be a conversation comment or a diff thread.
Repeatable publishing
Exact duplicate checks are on by default. Use --key build-summary to update one recurring comment, or opt into near duplicate checks.
One review, several findings
Start with a gh-comment:review summary to submit its line threads together. Choose a neutral comment or an explicit approval decision.
File notes and replies
Comment on a changed file without picking a line, or reply to an existing review thread. Each uses its own duplicate scope.
Examples you can inspect
See where the feedback lands.
A thread directive places feedback on changed lines. The local HTML preview shows the structure before publishing; GitHub supplies the final styling and account avatar.
01 / Inline comment
Point to the changed line.
RIGHT uses the new side of the diff; LEFT uses deleted lines on the old side. The directive sets placement and is removed from the posted body.
<!-- gh-comment:thread path="src/service.ts" line="42" side="RIGHT" --> Please handle empty input here. <details> <summary>Why this matters</summary> The error would otherwise appear later. </details>
Approximate Files changed view
src/service.ts:L42Resolvable threadReview comment
Please handle empty input here.
Why this matters
The error would otherwise appear later.
02 / Resolved conversation
Close the loop in GitHub.
Once the feedback is addressed, the PR author or a repository writer can resolve the conversation in Files changed. There is no Markdown directive that marks a thread resolved. GitHub’s guide ↗
After posting the inline thread:
1. Address the feedback.
2. Select “Resolve conversation” in GitHub.
The conversation collapses and is marked resolved.
Illustrative after-state · click to expand
✓ Conversation resolved
✓ Conversation resolvedsrc/service.ts:L42Show thread
Review comment
Please handle empty input here.
Resolution is a GitHub thread state, not part of the comment body.
For a review summary with several inline findings, see the batch review Markdown example ↗.
A little more control
A workflow that fits your review.
Start with one comment. Add options only when the report needs them.
- Preview the layout:
previewwrites a local HTML page with comments and thread placement. - Preview decisions:
--dry-runshows what would be created, updated, or skipped. - Keep one status comment:
--keyedits the same comment on later runs. - Make feedback resolvable: target a changed line or file, or reply to a top-level review comment.
- Group inline findings: start a report with a review summary to submit its line comments together.
- Automate:
--jsongives scripts structured results, and a GitHub Actions example is included.
<!-- gh-comment:thread path="src/file.ts" line="42" side="RIGHT" -->
Please handle empty input here.Review thread syntax and limits ↗
Browse examples ↗terminalEXAMPLE
# Inspect the comment layout in your browser gh-comment preview review.md --pr 123 --output preview.html # See what will happen before publishing gh-comment post review.md --pr 123 --dry-run # Keep one report current across runs gh-comment post summary.md --pr 123 --key build-summary # Attach an image alongside the report gh-comment post review.md --pr 123 \ --attach screenshots/error.png
Local code paths resolve from the code repository root. Media paths in Markdown resolve from the report’s directory.
Ready to write your first report?
The README covers conversation comments, batch reviews, file notes, replies, authentication, attachments, configuration, and GitHub Actions setup.
The name check should reject empty input.