The CLI authenticates against Grounds Account using the OAuth 2.0 device authorization grant with PKCE. You don’t need a client secret on your machine.
grounds login
What happens:
- The CLI requests a device code from Grounds Account.
- Your browser opens at the verification URL with the code pre-filled.
- You sign in with your Grounds Account (or are already signed in) and approve the device.
- The CLI exchanges the code for an access + refresh token.
- Tokens are written to your OS-specific config dir.
The access token has a short lifetime (≈5 minutes). The refresh token lives ≈30 days. The CLI transparently refreshes the access token before each API call, so you log in once a month at most.
grounds logout
Deletes the credentials file. It does not revoke the refresh token at the IdP — it just removes the local copy. If you want a hard revoke, use the Devices page in account.grounds.gg.
grounds doctor
Five checks, each reports OK or the failure reason:
| Check | Verifies |
|---|
config | Config dir is readable |
auth | Credentials present and the access token can be obtained (refreshes if expired) |
api | <api>/healthz returns 200 |
gradle | A Gradle wrapper or gradle binary is on PATH |
java | A JVM ≥ 21 is on PATH |
auth will say not logged in if you’ve never run login, or session expired (run 'grounds login') if your refresh token has aged out.
Auth in CI / scripts
For unattended use, don’t run grounds login. Use a project-scoped service-account token instead:
export GROUNDS_TOKEN=gnds_abc123… # opaque, project-scoped
grounds push --target=staging
GROUNDS_TOKEN overrides credentials from disk. The CLI will not try to refresh it (it’s not a JWT).
Credentials on disk
| OS | Path |
|---|
| Linux | $XDG_CONFIG_HOME/grounds/credentials.json (default ~/.config/grounds/credentials.json) |
| macOS | ~/Library/Application Support/grounds/credentials.json |
| Windows | %APPDATA%\grounds\credentials.json |
0600 on POSIX.
Don’t commit this file or copy it to a CI runner. For any non-interactive use, use a service-account token.
Multiple accounts / environments
Use --config <dir> (or GROUNDS_CONFIG_DIR) to keep separate credential stores:
grounds --config ~/.config/grounds-prod login
grounds --config ~/.config/grounds-staging login
API URL override
Set --api-url <url> or GROUNDS_API_URL to talk to a different forge instance (e.g., a self-hosted preview). Default is https://platform.grnds.io. 