grounds push

Build with Gradle, upload to forge, deploy to a target.

grounds push is the command you’ll run dozens of times a day. It’s a thin wrapper over the Gradle plugin: the CLI invokes ./gradlew groundsPush with the right arguments and inherits its stdout.

Synopsis

grounds push [--target=dev|staging] [--flavor <key>] [--project <id>] [--local <id>[,<id>]] [--with-local]
grounds push retry <pushId>
grounds push list [--target T] [--status S] [--limit N]

push

grounds push --target=dev       # default
grounds push --target=staging
grounds push --flavor=minestom
grounds push --local plugin-chat
grounds push --local plugin-chat,plugin-permissions
grounds push --with-local

Runs ./gradlew groundsPush --target=<t> in the current directory. The Gradle plugin handles:

• Resolving the JAR (auto-detects shadowJar or jar).
• Reading and validating grounds.yaml.
• Uploading JAR + manifest to forge.
• Streaming build + deploy logs back to your terminal.
• Exiting with a non-zero code on any terminal failure.

The CLI exits with the same code Gradle exits with.

By default, grounds push uses the release sources declared in grounds.yaml. Local plugin builds are opt-in through workspace overrides.

Local plugin overrides

Use --local when one or more entries in grounds.yaml: plugins should come from your local workspace instead of the release source:

grounds push --target=dev --local plugin-agones
grounds push --target=dev --local plugin-agones,plugin-player
grounds push --target=dev --local plugin-agones --local plugin-player

--local accepts both comma-separated IDs and repeated flags. IDs must match the structured plugin id in grounds.yaml.

Use --with-local when every enabled workspace mapping present in grounds.yaml should be replaced by its local artifact:

grounds push --target=dev --with-local

Before Gradle runs, the CLI prints the effective source table:

Bundle sources:
ID              Variant   Effective   Value
plugin-agones   velocity  local       /home/alice/grounds/plugin-agones/velocity/build/libs/plugin-agones-velocity.jar
plugin-player   velocity  release     github:groundsgg/plugin-player@v0.1.0

The table is the confirmation step. It shows which plugins use local artifacts and which still use release sources.

Minestom distribution pushes

For type: minestom-server, the CLI uses the Minestom path instead of delegating to the Gradle groundsPush task. It reads build.task, builds the configured distribution, normalizes build.artifact, and uploads the tar artifact to Forge.

grounds.yaml

name: minigame-agones
type: minestom-server
baseImage: minestom
build:
  task: :examples:minigame-agones:distTar
  artifact: examples/minigame-agones/build/distributions/*.tar
modules:
  - id: plugin-agones
    variant: minestom
    source: github:groundsgg/plugin-agones@v0.6.0:plugin-agones-minestom.jar

Run the push from the directory that contains gradlew and grounds.yaml:

grounds push --target=dev

If the manifest uses flavors, select the Minestom flavor explicitly:

grounds push --flavor=minestom --target=dev

Minestom module entries use the same --local and --with-local flags as plugin stacks. When local mappings apply, the CLI prints the effective source table before running Gradle:

Bundle sources:
ID              Variant   Effective   Value
plugin-agones   minestom  local       /home/alice/grounds/plugin-agones

See Local Minestom Modules for the workspace mapping details.

push retry

grounds push retry <pushId>

Re-runs the pipeline for a previously failed push. Forge re-uses the server-stored JAR and manifest, so this doesn’t re-upload — it goes straight from pending to building. Use it when:

• A build failed because of a transient infra issue (image pull, registry hiccup).
• A deploy failed and you want to try again without rebuilding.

The retry creates a new push row with its own ID; the original is preserved for history.

push list

grounds push list                          # last 20 in current project
grounds push list --target=staging
grounds push list --status=ready
grounds push list --limit=50
grounds push list --output=json | jq .

Flag	Purpose
--target	Filter by target: dev, staging, production.
--status	Filter by state: pending, building, build_failed, build_succeeded, deploying, deploy_failed, ready.
--limit	Max rows to fetch (default 20, server cap 200).
--output	table (default), json, or yaml.

Common flags

These are all global flags and apply to every subcommand:

Flag	Env	Purpose
--project <id>	GROUNDS_PROJECT	Pin the project for this call
--api-url <url>	GROUNDS_API_URL	Override the forge endpoint
--config <dir>	GROUNDS_CONFIG_DIR	Override config dir
--output <fmt>	—	table / json / yaml
--verbose / -v	—	Debug logs to stderr
--no-color	NO_COLOR=1	Disable ANSI colors

Reading the output

A successful push looks like:

→ uploading my-cool-plugin-0.1.0.jar (4.2 MB)
✔ uploaded — pushId=018f9c12-…
[build] step 1/5 …
[build] step 5/5 done
✔ build_succeeded — image registry.platform.grnds.io/my-cool-plugin@sha256:…
[deploy] reconciling deployment my-cool-plugin in user-hendrik
[deploy] pod scheduled
[deploy] pod ready
✔ ready — connect at my-cool-plugin-hendrik.mc.grnds.io

If the pod ends up CrashLoopBackOff, you’ll see deploy logs streamed before the CLI gives up and prints deploy_failed. Tail the live deployment logs separately at any time:

grounds logs deployment my-cool-plugin

Exit codes

For a practical failure investigation flow, see Debug pushes and deployments.

Code	Meaning
0	ready reached
1	Generic failure (validation, network, config)
2	build_failed
3	deploy_failed
130	Cancelled by user (Ctrl-C)

Anything non-zero is safe to fail a CI step on.