OSS-CLI docs

Everything the tool does, and what each part needs. A GitHub token is the only hard requirement — every other capability is a layer you add when you want it.

Install

macOS

brew install ramanathan1504/oss-cli/oss-cli

Homebrew pulls in OpenJDK 17 and puts oss-cli on your PATH.

Linux

# Java 17
sudo apt install openjdk-17-jre        # Debian / Ubuntu
sudo dnf install java-17-openjdk       # Fedora / RHEL

mkdir -p ~/.local/share ~/.local/bin

# resolves the newest release, so this stays correct
JAR_URL=$(curl -fsSL https://api.github.com/repos/ramanathan1504/oss-cli/releases/latest \
  | grep -o '"browser_download_url": *"[^"]*\.jar"' | cut -d'"' -f4)
curl -fL -o ~/.local/share/oss-cli.jar "$JAR_URL"

printf '#!/bin/sh\nexec java -jar %s "$@"\n' ~/.local/share/oss-cli.jar > ~/.local/bin/oss-cli
chmod +x ~/.local/bin/oss-cli

Windows

winget install EclipseAdoptium.Temurin.17.JRE

# PowerShell
$dir = "$env:LOCALAPPDATA\oss-cli"
New-Item -ItemType Directory -Force -Path $dir | Out-Null

$rel = Invoke-RestMethod https://api.github.com/repos/ramanathan1504/oss-cli/releases/latest
$url = ($rel.assets | Where-Object { $_.name -like "*.jar" })[0].browser_download_url
Invoke-WebRequest -Uri $url -OutFile "$dir\oss-cli.jar"

"@echo off`r`njava -jar `"$dir\oss-cli.jar`" %*" | Out-File -Encoding ascii "$dir\oss-cli.cmd"
$env:Path += ";$dir"

A GitHub token

# macOS — the gh CLI already has one
security add-generic-password -a "$USER" -s github_token -w "$(gh auth token)" -U

# Linux / Windows
export GITHUB_TOKEN="ghp_your_token_here"

Then check everything at once:

oss-cli doctor

First run

# register any repository you want to follow
oss-cli sync --add apache/kafka

# pull issues and PRs, then build the search index
oss-cli sync --all

# review a pull request
oss-cli review 4234 -r apache/kafka

Optional, any time: install Ollama for local answers and semantic search, then run oss-cli setup to point it at your own note folders. Skip both and every command above still works.

Commands

Command	Needs	What it does
`sync --add <repo>`	token	Registers a repository and builds its convention profile
`sync --all`	token	Pulls issues and PRs, then updates the search index
`sync --me`	token	Indexes your own PR history and your note folders
`profile`	token	Language, build, toolchain and enforced conventions
`onboard`	token	What a project expects before you contribute
`review <pr>`	token	Reviews a PR using every source you have connected
`prompt <issue>`	token	Answers locally, or builds an expert prompt when it cannot
`search <query>`	Ollama	Semantic search across everything indexed
`triage <issue>`	Ollama	Full triage audit for one issue
`doctor`	—	Checks every prerequisite and says what to fix

Every command accepts --help.

Reviewing a pull request

oss-cli review 4234

Built as a ladder. Each layer is optional and additive, and the output states which were actually used — so a thin review is never mistaken for a clean one.

Layer	Requires	Adds
Facts	token	Diff, commits, files by area, CI checks, review threads
Conventions	a profile	Deterministic gate checks, no model involved
History	your notes	Your prior work on the changed paths
Verdict	Ollama	Local judgment against the project's rules
Escalation	cloud key	The whole diff read by a cloud model when it is too large

Evidence is cached by head commit, not PR number — a push rewrites the pull request, so re-reviewing unchanged code is instant while a new push re-fetches on its own. No local clone is needed.

oss-cli review 4234 --no-verdict     # facts and conventions only
oss-cli review 4234 --escalate       # send large diffs to a cloud model
oss-cli review 4234 --refresh        # ignore the cache

Joining a project

oss-cli onboard -r apache/logging-log4j2

The same profile review judges against, read from the other direction: what to target before writing anything. Reports rules as instructions rather than plugin names, extracts build commands from the project's own documentation, and lists open issues labelled for newcomers, fewest comments first.

Configuration

Settings live in SQLite, not a dotfile. oss-cli setup writes them.

Key	Meaning
`default.repository`	Used when `-r` is omitted
`drive.paths`	Folders holding your notes, comma separated
`ollama.model.embedding`	Model for the vector index
`ollama.model.guidance`	Model for answers and verdicts
`ollama.context_limit`	Tokens before escalation

Your data lives in ~/.oss-cli. Nothing leaves the machine unless you escalate a prompt to a cloud model.

Troubleshooting

Start here — it checks every prerequisite and names what to fix:

oss-cli doctor

GitHub rejected the token

The stored token expired or was revoked. Create a new one and register it:

security add-generic-password -a "$USER" -s github_token -w "$(gh auth token)" -U

Cannot reach the Ollama daemon

Ollama is not running. Start it — installing a model cannot fix a stopped server:

ollama serve

Issues sync but search finds nothing

The vector index is built during sync and needs Ollama. If it was not running, the issues were saved without vectors. Start Ollama and sync again — indexing is incremental, so only the missing ones are built.