Gramma - command-line grammar checker

Gramma is an interactive tool that helps you find and fix grammatical mistakes in files and text strings. You can also use it in a non-interactive way, as a simple linter for automation processes.

Gramma works on Linux, Windows, and macOS.

Gramma supports many languages. You can find a full list here.

Gramma works out-of-the-box, communicating with grammarbot.io, but can also be easily configured to work with other compatible APIs, including local or remote LanguageTool server.


npm version CircleCI dependencies status node version Package quality npm license
Example

Contents

  1. Installation
  2. Usage
  3. Configuration
  4. Managing a local server
  5. JS API
  6. License

Installation

Via NPM

It is the recommended way if you have Node.js and NPM already installed (or you are willing to do it).

Global installation:

npm i gramma -g

Local installation (as a dev tool for your project):

npm i gramma -D

Via binary package

If you prefer a single binary file (Node.js included), you can download it for the most popular platforms:

After downloading and unpacking the binary, add it to your PATH or create a symlink to your executable directory (depending on the platform).

Installing local server

If you don’t want to use a public API, you can install a local LanguageTool server:

gramma server install

For this to work, you have to install Java 1.8 or higher (you can find it here or here). You can check if you have it installed already by running:

java -version

That’s it - Gramma will now use and manage the local server automatically.

Usage

Check file

Interactive fix:

gramma check [file]

Just print potential mistakes and return status code:

gramma check -p [file]

Examples:

gramma check path/to/my_file.txt
gramma check -p path/to/other/file.txt

Check string

Interactive fix:

gramma listen [text]

Just print potential mistakes and return status code:

gramma listen -p [text]

Examples:

gramma listen "This sentence will be checked interactively."
gramma listen -p "Suggestions for this sentence will be printed."

Git commit with grammar check

Equivalent to git commit -m [message]:

gramma commit [text]

Equivalent to git commit -am [message]:

gramma commit -a [text]

Examples:

gramma commit "My commit message"
gramma commit -a "Another commit message (files added)"

Command-line options

Note: This section describes options for grammar-checking commands only. Other command-specific options are described in their respectful sections of this document.

You can enable or disable multiple rules in one command by using a corresponding option multiple times. You can also compound boolean options if you use their short version.

Example:

gramma listen "I like making mistkaes!" -pn -d typos -d typography -e casing -l en-GB

Configuration

Introduction

With Gramma, you can use a global and local configuration file. Gramma will use a proper config file following their priority:

  1. Command-line options
  2. Local config
  3. Global config
  4. Default config

Gramma will automatically generate configuration files when you add something to your config via gramma config command.

If you want to manually initialize local config with default options, you can run the following command in your project’s root directory:

gramma init

By doing so, your project will not depend on your user’s setting. It is useful when you want to share your project with others, for example via Git repository.

You can check the path to the global configuration file (as well as other paths used by Gramma) via the following command:

gramma paths

Gramma creates the local configuration in your working directory under .gramma.json name.

You can change your settings by manually editing configuration files or running:

gramma config <setting> <value> [-g]

-g (--global) flag is optional and controls whether the global or the local config will be altered.

Note: All examples below use the global config. If you want to use a local one, skip the -g flag.

Checker settings

Adding a word to the dictionary

Usually, you will add custom words to the local or global dictionary via interactive menu during the fix process, but you can also make it via separate command:

gramma config dictionary <your_word> -g

Changing default language

gramma config language <language_code> -g

Available languages (click to expand)

Note: By default, Gramma uses US English (en-US).

Enabling and disabling rules

Enabling a specific rule:

gramma config enable <rule_name> -g

Disabling a specific rule:

gramma config disable <rule_name> -g

Available rules (click to expand)

You can find a description of each rule here.

Note: By default, all rules are enabled.

Customizing API server

Defining custom API endpoint

If you want to use remote LanguageTool server, or use one already installed in your system (not installed via gramma server install), you can define a custom API endpoint:

gramma config api_url <custom_api_endpoint> -g

Example

gramma config api_url http://my-custom-api-url.xyz/v2/check -g

Running local server only when needed

If you do not want the local server to run all the time, you can configure Gramma to run it only when needed (run -> check -> close). It is useful when you run Gramma only from time to time and want to lower the memory consumption:

gramma config server_once true -g

Note: This setting requires the -g flag because all local API server settings are stored in the global config.

Adding API key

Note: This option applies to grammarbot.io and languagetoolplus.com API only.

If you use our default API (grammarbot.io), it comes with some limitations - 100 checks per day (which is fine for most users). You can increase that limit to 250 by registering on grammarbot.io/signup (it’s free).

You can also buy a paid option on grammarbot.io or languagetoolplus.com, which both offer some additional checks.

In both cases, when you register, you will receive an API key that you can use in Gramma:

gramma config api_key <your_api_key> -g

Managing a local server

If you have configured a custom API server, Gramma will manage the server automatically - nevertheless, there might be situations when you want to manage server manually. Gramma simplifies this by exposing basic server commands:

Starting server

gramma server start

Note: When you use this command, Gramma will ignore server_once config option. This is expected behavior - I assume that if you use this command, you want the server to actually run, not stop after the first check.

Stopping server

gramma server stop

Getting server PID

gramma server pid

Opening built-in GUI

gramma server gui

JS API

In addition to command-line usage, you can use two exposed methods if you want to handle mistakes by yourself.

check() method

Returns a promise with a check result.

const { check } = require("gramma")

check("Some text to check.").then(console.log)

You can also pass a second argument - an options object. Available options:

Default options object (click to expand)
{
  "api_url": "http://api.grammarbot.io/v2/check",
  "api_key": "",
  "dictionary": [],
  "language": "en-US",
  "rules": {
    "casing": true,
    "colloquialisms": true,
    "compounding": true,
    "confused_words": true,
    "false_friends": true,
    "gender_neutrality": true,
    "grammar": true,
    "misc": true,
    "punctuation": true,
    "redundancy": true,
    "regionalisms": true,
    "repetitions": true,
    "semantics": true,
    "style": true,
    "typography": true,
    "typos": true
  }
}

You can find all available values for each setting in the configuration section of this document.

Example with all options set:

const { check } = require("gramma")

check("Some text to check.", {
  api_url: "http://my-custom-language-tool-server.xyz/v2/check",
  api_key: "SOME_API_KEY",
  dictionary: ["npm", "gramma"],
  language: "pl-PL",
  rules: {
    typography: false,
    casing: false,
  },
}).then(console.log)

replaceAll() method

Replaces words with provided ones. It takes an array of objects in the following format:

const exampleReplacements = [
  { offset: 6, length: 3, change: "correct phrase" },
  { offset: 20, length: 7, change: "another phrase" },
]

You can find proper offset and length values in the object returned by check() method.

Example usage:

const { check, replaceAll } = require("gramma")

/** Your custom function **/
const prepareReplacements = (matches) => {
  // your code...
}

const fix = async (text) => {
  const { matches } = await check(text)
  const replacements = prepareReplacements(matches)

  return replaceAll(text, replacements)
}

const main = () => {
  const correctText = await fix("Some text to check")
  console.log(correctText)
}

main()

License

Project is under open, non-restrictive ISC license.