Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grounds.gg/llms.txt

Use this file to discover all available pages before exploring further.

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

grounds login
What happens:
  1. The CLI requests a device code from Grounds Account.
  2. Your browser opens at the verification URL with the code pre-filled.
  3. You sign in with your Grounds Account (or are already signed in) and approve the device.
  4. The CLI exchanges the code for an access + refresh token.
  5. 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

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

grounds doctor
Five checks, each reports OK or the failure reason:
CheckVerifies
configConfig dir is readable
authCredentials present and the access token can be obtained (refreshes if expired)
api<api>/healthz returns 200
gradleA Gradle wrapper or gradle binary is on PATH
javaA 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
See CI / service-account tokens for how to mint one. GROUNDS_TOKEN overrides credentials from disk. The CLI will not try to refresh it (it’s not a JWT).

​
Credentials on disk

OSPath
Linux$XDG_CONFIG_HOME/grounds/credentials.json (default ~/.config/grounds/credentials.json)
macOS~/Library/Application Support/grounds/credentials.json
Windows%APPDATA%\grounds\credentials.json
The file holds the access token, refresh token, expiry timestamps, and a hint of who you are (email, preferred username decoded from the ID token). Permissions are 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
The same flag selects which set is used by all subsequent commands.

​
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.