Skip to main content
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

SubcommandDescription
auth addAdd a new GitHub account via the OAuth device flow.
auth lsList 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

npx @nick3/copilot-api@latest auth add [options]

Options

OptionAliasDefaultDescription
--account-type-aindividualCopilot plan for this account: individual, business, or enterprise.
--verbose-vfalseEnable verbose logging.
--show-tokenfalsePrint the GitHub token to the console after authentication completes.

Examples

npx @nick3/copilot-api@latest auth add

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

npx @nick3/copilot-api@latest auth ls [options]

Options

OptionAliasDefaultDescription
--show-quota-qfalseFetch and display remaining quota for each account. Requires an API call per account.
--verbose-vfalseEnable verbose logging.

Examples

npx @nick3/copilot-api@latest auth ls
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.

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

npx @nick3/copilot-api@latest auth rm <target> [options]

Arguments

ArgumentDescription
<target>GitHub username (for example octocat) or 1-based index from auth ls.

Options

OptionAliasDefaultDescription
--force-ffalseSkip the confirmation prompt and remove immediately.
--verbose-vfalseEnable verbose logging.

Examples

npx @nick3/copilot-api@latest auth rm octocat