> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullfrog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grok subscription

> Run xAI models on your SuperGrok or X Premium subscription instead of paying for API tokens.

Run Pullfrog on the SuperGrok or X Premium subscription you already pay for, with no xAI API bill on top. One command signs you in and stores the credential, with no second CLI to install.

<Note>
  A Grok subscription covers the xAI models: Grok and Grok 4.3. For other providers, see [Model access](/model-access).
</Note>

## Setup

Run this inside a clone of the repository. The CLI uses the [GitHub CLI](https://cli.github.com) to sign you in.

```bash theme={null}
npx pullfrog auth grok
```

The CLI:

1. Requests a device code from xAI, then opens the sign-in URL and shows the code.
2. Waits while you sign in and approve the code. The device-code flow also works over SSH and in containers.
3. Refreshes the new credential once, then saves it to Pullfrog's encrypted store.

The next run on an xAI model uses the subscription. Run the command again to add another account or replace one. With several connections, or an `XAI_API_KEY` beside them, Pullfrog moves to the next credential when one is rejected or out of quota; see [multiple subscriptions and fallback](/keys#multiple-subscriptions-and-fallback).

<Frame>
  <img src="https://mintcdn.com/pullfrog/klps40MoSQ5FJkiz/images/subscription-cards.png?fit=max&auto=format&n=klps40MoSQ5FJkiz&q=85&s=c888cdc3e19f077e18222aeec019c367" alt="The Subscriptions row of the Providers section: Claude Pro/Max, ChatGPT (Codex) and Grok" width="1680" height="532" data-path="images/subscription-cards.png" />
</Frame>

## Scope

On an organization repository, the CLI asks where to store the credential:

| Option | Scope | Who can save it |
| - | - | - |
| **`<owner>` organization** | Every repository in the organization | Organization owner |
| **`<owner>/<repo>` only** | This repository | Repository admin |

A personal account has only the account scope, so the CLI does not ask. To skip the prompt or run outside a checkout, pass the scope as a flag:

```bash theme={null}
npx pullfrog auth grok --org my-org          # organization scope
npx pullfrog auth grok --repo my-org/my-repo # one repository
```

## Credential refresh

Grok access tokens last about six hours, and xAI replaces the refresh token on every use. Pullfrog keeps the stored copy current on its own:

* Before a run, Pullfrog refreshes the stored credential when less than an hour is left on it.
* After a run, Pullfrog saves any token the run refreshed back to its store.

A credential that goes unused for long enough can lapse at xAI. Run `npx pullfrog auth grok` again to replace it.

## Troubleshooting

| Symptom | Fix |
| - | - |
| CLI error: "Grok sign-in timed out" | The device code expires after a few minutes. Run the command again and approve the code sooner. |
| Job log: `GROK_AUTH_JSON was rejected by xAI` | xAI refused the stored refresh token, so Pullfrog skips it and tries the next credential for the model. Run `npx pullfrog auth grok` and replace the old connection. |
| Job log: "subscription auth skipped: could not create /var/lib/pullfrog" | Pullfrog keeps the credential in a directory the agent cannot read, and creating it needs passwordless `sudo`. Allow passwordless `sudo` for the runner user, use a GitHub-hosted runner, or add an `XAI_API_KEY`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.