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 preview subtree manages preview environments — the ephemeral envs created by grounds push --target=staging.

​
Synopsis

grounds preview list   [--include-deleted]
grounds preview show   <id> [--json]
grounds preview pin    <id>
grounds preview unpin  <id>
All preview commands are scoped to the current project (use --project or GROUNDS_PROJECT to switch).

​
preview list

grounds preview list

ID        PUSH      NAME          TYPE          STATUS  PINNED  EXPIRES     URL
abc12345  def67890  my-plugin     plugin-paper  ready   no      2026-05-05  minecraft://my-plugin-prabc12345.mc.grnds.io
…
FlagPurpose
--include-deletedShow envs the janitor has already swept. Their STATUS will read deleted.
--output jsonMachine-readable form. Useful for piping into jq.

​
preview show

grounds preview show abc12345

ID:        abc12345-…
PushID:    def67890-…
Namespace: preview-abc12345
Name:      my-plugin (plugin-paper)
Status:    ready
Pinned:    false
Expires:   2026-05-05T14:23:00Z
URL:       minecraft://my-plugin-prabc12345.mc.grnds.io
Add --json for the raw API response — useful for scripting or debugging.

​
preview pin / unpin

grounds preview pin <id>     # skip TTL janitor
grounds preview unpin <id>   # re-enable TTL sweep
Pinned envs stay alive past their original expiresAt. They don’t get a new TTL — they just don’t have one. Unpin to put it back on the cleanup schedule (the TTL is recomputed from now() + 7d).
Pinning is intentionally manual. The platform doesn’t auto-pin “interesting” envs, so a forgotten demo doesn’t quietly burn cluster resources for weeks.

​
What you can’t do here (yet)

  • Force-delete a non-pinned env (the janitor will get to it within 30 min of expiry, and you can always push a new one).
  • Rename a preview env or change its hostname.
  • Promote a preview to production (that’s a separate grounds promote flow, currently in beta).

​
Equivalents in the portal

The portal’s Previews tab on a project page has the same operations:
  • One row per env with status badge, expiry, public URL, pin indicator.
  • Per-row dropdown: Pin (skip auto-cleanup) / Unpin (re-enable cleanup).
  • Click the URL to open the env in a new tab.
Use whichever surface fits your flow — they hit the same forge endpoints.