Chan CLI used for writing and maintaining a CHANGELOG


stars 🌟issues ⚠️updated 🛠created 🐣size 🏋️‍♀️
Minified + gzip package size for @geut/chan in KB


Chan CLI

Build Status npm version

Chan is a likeable CLI tool used for writing and maintaining a CHANGELOG empowering the user to use a coloquial/friendly style. See more here: keepachangelog.com


Getting started


$ npm install -g @geut/chan


Create a CHANGELOG.md file in your project root folder with:

$ chan init

To add entries to your CHANGELOG use the command that describes better your change (added, changed, fixed, etc)

$ chan added "New feature in my API to print foo in the console."

This command will modify your CHANGELOG creating a new entry called added under the Unreleased section.

chan follows the keepachangelog.com format/style.

Release your changes:

$ chan release 0.0.1

And you will get something like:

# Changelog
All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## 0.0.1 - 2019-01-11
### Added
- New feature in my API to print foo in the console.

[Unreleased]: https://github.com/my-org/my-repo/compare/v0.0.1..HEAD

chan init [dir]

Creates a CHANGELOG.md if it does not exists. Chan will work with this file.


[dir] (string)

Allows you to run init in a specific directory: chan init packages/package-one.

-o, --overwrite (boolean)

Overwrite the current CHANGELOG.md

chan <action> <msg>

Create new entries with the <msg> in your changelog under the release: Unreleased

<action> could be:

  • added Writes your changelog indicating new stuff.

  • fixed Writes your changelog indicating fixed stuff.

  • changed Writes your changelog indicating updated stuff.

  • security Writes your changelog indicating security upgrades.

  • removed Writes your changelog indicating removed stuff.

  • deprecated Writes your changelog indicating deprecated stuff.


-p, --path (string)

Define the path of the CHANGELOG.md (cwd by default).

-g, --group (string)

Prefix change with provided group value.


chan added --group=packages/package-one 'New stuff added'

will add to you changelog unreleased changes:

### Added
- packages/package-one
  - New stuff added.

This could be a good option to work with a monorepo and root changelog.

chan release <semver>

Marks the unreleased changes as a new release in your changelog.

Keep a changelog defines that each release can have a compare preview url like: https://help.github.com/articles/comparing-commits-across-time/

By default, chan will try to generate it automatically from your .git local directory, but you can change this behaviour. Check the next options.


<semver> (string)

Valid semver version.

-p, --path (string)

Define the path of the CHANGELOG.md (cwd by default).

--yanked (boolean)

Marks the release as a yanked version.

--git-url (string)

You can provide the git url of your project so chan can tries to find the git provider to generate the url compare for your releases.

Example: https://github.com/geut/chan will generate releases with the url: https://github.com/geut/chan/compare/v0.0.1..HEAD

Also, this kind of configurations can be defined in the package.json.

--git-template (string)

If --git-url is not enough you can define the template url to compare your releases.

Example: https://otherhost.com/geut/chan/compare/[prev]...[next] will generate releases with the url: https://otherhost.com/geut/chan/compare/v0.0.1..HEAD

--git-branch (string)

Defines which branch chan is going to use to compare the unreleased version.

Example: chan release 0.0.1 --git-branch master will generate releases with the url: https://github.com/geut/chan/compare/v0.0.1..master

--allow-yanked (boolean)

Allow yanked releases. When this option is true and the release doesn't have new changes it will released as a yanked version.

--allow-prerelease (boolean)

Allow prerelease versions.

--merge-prerelease (boolean)

Merge the prerelease versions into the next stable version.

--ghrelease (boolean)

Creates a github release.

By default it opens the browser with the github release to edit and accept.

If you define the env GITHUB_TOKEN it will publish the release directly, best option for CI.

chan gh-release <semver>

Creates a github release.


--git-url (string)

Define the url of the repository project.

chan show <semver>

Shows the release notes for a specific version.

Global options

--stdout (boolean)

Define the output as STDOUT

--verbose (boolean)

Show more info on error

--help (boolean)

Show help

--version (boolean)

Show version number


You can configure the chan options using the package.json or a rc file (.chanrc, .chanrc.json):


  "git-url": "https://github.com/geut/chan"


  "chan": {
    "git-url": "https://github.com/geut/chan"


:bug: If you found an issue we encourage you to report it on github. Please specify your OS and the actions to reproduce it.


:busts_in_silhouette: Ideas and contributions to the project are welcome. You must follow this guideline.

A GEUT project

If you find any bugs or have a feature request, please open an issue on github!

The npm package download data comes from npm's download counts api and package details come from npms.io.