---
id: usage
title: CLI Usage
sidebar_label: Usage
---

> This usage documentation assumes you have already followed the [cli installation steps](installation).

A quick note: Below we'll just show `all-contributors` to keep things simple, but if you're having any difficulties, then give the `yarn all-contributors` route a try 😺

## Commands

<AUTOGENERATED_TABLE_OF_CONTENTS>

### `all-contributors init`

Run this when you first start using the all-contributors-cli. This command asks a few questions and sets up the project for all-contributors.
This setup includes creating a `.all-contributorsrc` configuration file and creating a contributor table in the `files` you specify (usually your `README.md`).

### `all-contributors add`

Use `add` to add new contributors to your project, or add new ways in which they
have contributed. They will be added to your configuration file, and the
contributors file will be updated just as if you used the [generate command](#all-contributors-generate).

```console
# Add new contributor <username>, who made a contribution of type <contribution>
all-contributors add <username> <contribution>
# Example:
all-contributors add jfmengels code,doc
```

Where `username` is the user's GitHub or Gitlab username, and `contribution` is a
`,`-separated list of contributions. See the [Emoji Key (Contribution Types Reference)](../emoji-key)
for a list of valid `contribution` types.

> **GitLab Users**: See the [additional requirements for GitLab users](#gitlab-users)

### `all-contributors check`

Use `check` to compare contributors from GitHub with the ones credited in your
`.all-contributorsrc` file, to make sure that credit is given where
it's due.

> Due to GitHub API restrictions, this command only works for projects with less
> than 500 contributors (Unless you set a `PRIVATE_TOKEN` as mentioned [below in GitHub users](#github-users)).

### `all-contributors generate`

Use `generate` to read the `contributors` list from your `.all-contributorsrc` file
and update the contributor tables specified by the `files` key.

Please note the command must be able to find the following tags in those files, to update the table:

```markdown
<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
<!-- ALL-CONTRIBUTORS-LIST:END -->
```

Also, note that it needs to find the following tags to update the badge:

```markdown
<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
<!-- ALL-CONTRIBUTORS-BADGE:END -->
```

## GitHub Users

In some cases you may see the error message `GitHub API rate limit exceeded for xxx`. You may need to set an environment variable named `PRIVATE_TOKEN` to circumvent this [GitHub rate limit](https://developer.github.com/v3/rate_limit/).

> Private token is your Personal Access Token (PAT) to authenticate with the GitHub API.

## GitLab Users

Please note that if you are using a self-hosted GitLab instance,
some commands will need you to set an environment variable named `PRIVATE_TOKEN` first.

> Private token is the personal access token to authenticate with the GitLab API.

```console
# set private token on Linux
export PRIVATE_TOKEN=your_private_token
# set private token on Windows
set PRIVATE_TOKEN=your_private_token
```

## What's next

- [Configuring the CLI](configuration)
