Commentary CLI

The Commentary CLI is the terminal companion for draft reviews and Brainstorming Reviews. It creates hosted reviews from local Markdown, MDX, static HTML, and plain text files, then syncs new revisions as local files change.

Project: commentary-dev/commentary-cli

Package: @commentary-dev/cli

Install

Use it without installing:

npx @commentary-dev/cli --help

Or install it globally:

npm install -g @commentary-dev/cli
commentary --help

The CLI requires Node.js 22 or newer.

Authentication

Use browser/device login:

commentary login

Use a Commentary API token when a token was created for automation:

commentary login --token <commentary-api-token>
COMMENTARY_TOKEN=<token> commentary whoami --json

CLI authentication state is stored outside project metadata. The local .commentary/session.json file stores review metadata, not secrets.

Draft Review Workflow

Create a review:

commentary review ./docs/spec.md --title "Product spec"
commentary review ./docs/spec.md --title "Product spec" --git-base auto
commentary review ./docs ./README.md

Upload a new revision after editing local files:

commentary sync --message "Address review comments"

Add a file to the same review:

commentary track ./docs/new-page.md --message "Add requested page"

List comments for an agent loop:

commentary comments --format markdown --open
commentary next-comment --timeout 60s --json

Reply or resolve:

commentary reply <thread-id> "Updated this in revision 3." --alias "Docs agent"
commentary resolve <thread-id> --message "Addressed in revision 3." --alias "Docs agent"

Share a review:

commentary share --anyone
commentary share --user reviewer@example.com
commentary share --list

Restore local metadata for an existing review:

commentary restore <session-id> --dry-run --json
commentary restore <session-id>

Pull reviewed content back to disk only when you intend to use Commentary-side content as the source:

commentary pull --dry-run
commentary pull --output reviewed
commentary pull --backup --yes

Brainstorming Reviews

Create or convert a Brainstorming Review:

commentary review ./docs/spec.md --mode brainstorming --title "Product spec"
commentary brainstorm enable

Inspect and act on accepted consensus:

commentary brainstorm status --json
commentary brainstorm next --consensus-state accepted_for_change --timeout 60s --json
commentary sync --message "Apply brainstorming consensus" --addressed-thread <thread-id>

Set feedback or owner decisions only when that is part of your workflow:

commentary brainstorm signal <thread-id> agree --alias "Docs agent"
commentary brainstorm decide <thread-id> accepted_for_change
commentary brainstorm rule --consensus-mode no_open_blockers --min-response-count 2

What The CLI Does Not Do

The CLI does not create GitHub branches, commits, pull requests, provider comments, or GitHub tokens. It sends literal file content to Commentary through the public API and leaves local Git operations to you.

See Draft reviews, Brainstorming Reviews, and Developer access.

Preparing the document workspace

Branch review

Branch review

Branch review

Commentary CLI

Install

Authentication

Draft Review Workflow

Brainstorming Reviews

What The CLI Does Not Do