shiplog-cli 0.1.0

Turn merged GitHub pull requests into clean, customer-facing changelogs.

Shiplog CLI

Turn merged GitHub pull requests into clean, customer-facing changelogs.

Shiplog reads merged PRs from a repository, runs each one through the Shiplog AI transform, and emits a publish-ready changelog grouped by category (New / Improved / Fixed / Infrastructure).

Install

pip install shiplog

Requires Python 3.9+.

Quick start

# 1. Save your API key (get one at https://shiplogbeta.arksoft.xyz)
shiplog login

# 2. Generate a changelog — auto-detects the repo from git origin
cd your-project
shiplog generate

# 3. Or name any repo explicitly
shiplog generate owner/repo --days 30 -o CHANGELOG.md

Authentication

Shiplog API key

The CLI sends your API key with every generation request. Save it once:

shiplog login sk_live_abc123...

Or set SHIPLOG_API_KEY in your environment. Without a key, the CLI works in demo mode (limited to 5 generations per day).

Other auth commands:

shiplog whoami    # show current key
shiplog logout    # remove saved key

GitHub token

For the generate command, Shiplog needs read access to the repo's pull requests. It resolves a GitHub token in this order:

1. --token flag
2. $GITHUB_TOKEN / $GH_TOKEN
3. gh auth token (if the GitHub CLI is installed and logged in)

Public repos work without a token but are subject to tighter rate limits.

Usage

Generate a changelog from a repo

The repo argument is optional — inside a git repo, Shiplog uses the origin remote automatically:

# Run inside your repo — no arguments needed
shiplog generate

# Or name any repo explicitly
shiplog generate owner/repo

# Everything merged in the last 30 days, written to a file
shiplog generate --days 30 -o CHANGELOG.md

# Since a specific date, only PRs merged into main, as JSON
shiplog generate owner/repo --since 2026-06-01 --base main --format json

Bot-authored PRs (dependabot, renovate, …) are skipped by default so the changelog stays customer-facing. Generation runs in parallel and automatically retries on rate limits, so large repos finish fast without dropping entries.

Options:

Flag	Description
--token	GitHub token (overrides env / gh CLI)
--base	Only PRs merged into this base branch
--since YYYY-MM-DD	Only PRs merged since this date
--days N	Only PRs merged in the last N days
--limit N	Max PRs to include (default 20)
--format markdown|json	Output format (default markdown)
--output, -o	Write to a file instead of stdout
--title	Custom heading for the changelog
--no-group	List chronologically instead of by category
--no-links	Omit PR number links
--include-bots	Include bot PRs (off by default)
--concurrency N	Parallel generation requests (default 8)

Transform a single PR (no GitHub needed)

Handy for testing or one-off entries — mirrors the website demo.

shiplog single "fix: pagination offset bug in list endpoint" \
  --body "Closes #412. Switched to cursor-based pagination."

Add --format markdown or --format json for machine-readable output.

Configuration

Env var	Purpose
SHIPLOG_API_KEY	Shiplog API key (alternative to shiplog login)
SHIPLOG_API_BASE	Override the generation API URL
SHIPLOG_CONFIG_DIR	Override config directory (default ~/.config/shiplog)
GITHUB_TOKEN / GH_TOKEN	GitHub auth

How it works

GitHub PRs ──▶ Shiplog API (/api/generate) ──▶ {category, title, body} ──▶ Markdown / JSON

The generation API is a Cloudflare Worker. Authenticated users get metered access based on their plan. Anonymous users get a small demo allowance.