> ## Documentation Index
> Fetch the complete documentation index at: https://copilot-api.nick3.top/llms.txt
> Use this file to discover all available pages before exploring further.

# copilot-api auth — manage GitHub accounts

> Add, list, and remove GitHub accounts used by Copilot API. Supports multiple accounts for quota pooling, round-robin distribution, and automatic failover.

The `auth` command manages the GitHub accounts that Copilot API authenticates with. You can add accounts through the GitHub OAuth device flow, list registered accounts with optional quota information, and remove accounts by username or index. Copilot API supports multiple accounts simultaneously — premium-model requests use accounts in order and fall back on quota exhaustion, while free-model requests distribute across accounts in round-robin.

## Subcommands

| Subcommand         | Description                                            |
| ------------------ | ------------------------------------------------------ |
| `auth add`         | Add a new GitHub account via the OAuth device flow.    |
| `auth ls`          | List all registered accounts.                          |
| `auth rm <target>` | Remove an account by GitHub username or 1-based index. |

Running `auth` without a subcommand defaults to `auth add`, which preserves backward compatibility with earlier versions.

***

## auth add

Starts the GitHub OAuth device flow to register a new account. Your browser opens to a GitHub authorization page where you enter a one-time code. Once authorized, the token is saved to your local data directory.

### Usage

```bash theme={null}
npx @nick3/copilot-api@latest auth add [options]
```

### Options

| Option           | Alias | Default      | Description                                                               |
| ---------------- | ----- | ------------ | ------------------------------------------------------------------------- |
| `--account-type` | `-a`  | `individual` | Copilot plan for this account: `individual`, `business`, or `enterprise`. |
| `--verbose`      | `-v`  | `false`      | Enable verbose logging.                                                   |
| `--show-token`   |       | `false`      | Print the GitHub token to the console after authentication completes.     |

### Examples

<CodeGroup>
  ```bash Add an individual account theme={null}
  npx @nick3/copilot-api@latest auth add
  ```

  ```bash Add a business account theme={null}
  npx @nick3/copilot-api@latest auth add --account-type business
  ```

  ```bash Add using the short form (same as auth add) theme={null}
  npx @nick3/copilot-api@latest auth
  ```
</CodeGroup>

***

## auth ls

Lists all accounts registered in your local account registry. Use `--show-quota` to also fetch and display current quota information for each account.

### Usage

```bash theme={null}
npx @nick3/copilot-api@latest auth ls [options]
```

### Options

| Option         | Alias | Default | Description                                                                           |
| -------------- | ----- | ------- | ------------------------------------------------------------------------------------- |
| `--show-quota` | `-q`  | `false` | Fetch and display remaining quota for each account. Requires an API call per account. |
| `--verbose`    | `-v`  | `false` | Enable verbose logging.                                                               |

### Examples

<CodeGroup>
  ```bash List accounts theme={null}
  npx @nick3/copilot-api@latest auth ls
  ```

  ```bash List accounts with quota theme={null}
  npx @nick3/copilot-api@latest auth ls -q
  ```
</CodeGroup>

<Note>
  The index shown in `auth ls` output is 1-based and corresponds to the `<target>` argument used by `auth rm`. The `GET /usage/:accountIndex` API endpoint uses a separate 0-based index.
</Note>

***

## auth rm

Removes a registered account from the local account registry. Provide either the GitHub username (account ID) or the 1-based index shown by `auth ls`.

### Usage

```bash theme={null}
npx @nick3/copilot-api@latest auth rm <target> [options]
```

### Arguments

| Argument   | Description                                                              |
| ---------- | ------------------------------------------------------------------------ |
| `<target>` | GitHub username (for example `octocat`) or 1-based index from `auth ls`. |

### Options

| Option      | Alias | Default | Description                                          |
| ----------- | ----- | ------- | ---------------------------------------------------- |
| `--force`   | `-f`  | `false` | Skip the confirmation prompt and remove immediately. |
| `--verbose` | `-v`  | `false` | Enable verbose logging.                              |

### Examples

<CodeGroup>
  ```bash Remove by username theme={null}
  npx @nick3/copilot-api@latest auth rm octocat
  ```

  ```bash Remove by index theme={null}
  npx @nick3/copilot-api@latest auth rm 2
  ```

  ```bash Remove without confirmation theme={null}
  npx @nick3/copilot-api@latest auth rm octocat --force
  ```
</CodeGroup>