# grok-auth

[Simplified Chinese](https://unpkg.com/grok-auth-cli@latest/README.md)

A pure Node.js CLI for managing multiple Grok authentication accounts. It stores complete `auth.json` snapshots by email address, supports inspecting, switching, and removing accounts, and queries usage through the Grok CLI billing endpoint. Tokens are never printed to the terminal.

Before querying usage or switching accounts, the CLI checks `expires_at`, falling back to the JWT `exp` claim when needed. Authentication is refreshed through the OIDC `refresh_token` flow five minutes before expiration. Rotated access tokens, refresh tokens, and expiration times are saved atomically. If the refresh token is no longer valid, you must sign in to Grok again.

Usage results are cached by account for 120 seconds in `.grok/usage-cache.json`. Only HTTP 401 triggers a forced authentication refresh; HTTP 403 does not. If a refreshed token still receives HTTP 401, authentication refresh is paused for 10 minutes to prevent repeated refresh-token rotation.

The `EXP` column in the interactive `switch` menu shows the actual access-token expiration time, including the local UTC offset. It does not show the authentication file modification time.

## Installation

Node.js 18.17 or later is required. Network requests honor the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables.

```sh
npm install --global grok-auth-cli
```

You can also run it without installing it globally:

```sh
npx --package grok-auth-cli grok-auth list
```

## Commands

```text
grok-auth save
grok-auth list
grok-auth current
grok-auth usage [email or number]
grok-auth switch [email or number]
grok-auth remove <email or number> [--force]
grok-auth version
```

By default, the CLI reads `.grok/auth.json` in the current user's home directory and stores snapshots in `.grok/accounts/`. Use `--grok-home <path>` to specify another directory:

```sh
grok-auth list --grok-home D:\\profiles\\grok
```

When invoked without arguments, the current account is highlighted in green. Running `switch` without an account opens an interactive menu and highlights the active account. Set the `NO_COLOR` environment variable to disable colors. The current `auth.json` is saved automatically before it is replaced. A successful switch prints only `Done.`

## Authentication refresh behavior

- OIDC refresh runs automatically when a token is less than five minutes from expiration.
- Usage queries do not send authentication refresh requests while a token is not near expiration.
- HTTP 401 from Billing triggers one forced authentication refresh and retries the query.
- HTTP 403 from Billing reports an authorization error without refreshing authentication.
- Authentication refresh is paused for 10 minutes if a refreshed token still receives HTTP 401.
- A successful refresh updates `key`, `expires_at`, and `create_time` in the corresponding authentication file.
- A new `refresh_token` is saved when returned by the token endpoint; otherwise, the previous value is retained.

## Local cache

Successful usage configuration is saved to `.grok/usage-cache.json` and cached for 120 seconds. Repeated `usage` commands or `switch` menu openings use the cached value without sending another Billing request while the cache is valid. The cache file does not contain an access token or refresh token.

## Local development and packaging

```sh
npm install
npm test
npm pack
```

This package uses Undici for HTTP requests and standard proxy environment variables.

## License

This project is licensed under the [MIT License](https://unpkg.com/grok-auth-cli@latest/LICENSE).