Skip to main content
Local workspaces let you keep grounds.yaml pointed at release plugin or module sources while opting into local builds for a single push. Use this workflow when your app lives in one repository and the plugin or Minestom module dependencies you are changing live in sibling repositories.
Local overrides are machine-local. They do not change the manifest, and they only apply when you pass --local or --with-local.

​
Repository layout

Use the internal sample workspace as the reference shape: 
~/grounds/
  sample-plugin-workspace/
    app/
      grounds.yaml
  plugin-agones/
  plugin-player/
Run grounds push from ~/grounds/sample-plugin-workspace/app. Keep plugin-agones and plugin-player beside the app repository so the CLI can map release plugin or module IDs to the local repositories on your machine. Your manifest stays portable:
grounds.yaml
plugins:
  - id: plugin-agones
    variant: velocity
    source: github:groundsgg/plugin-agones@v0.5.0
  - id: plugin-player
    variant: velocity
    source: github:groundsgg/plugin-player@v0.1.0
The id and variant fields are the matching keys. The source fields remain the default release sources for teammates, CI, and any push that does not opt into local overrides. Minestom server manifests use the same idea under modules.

​
Scan for repositories

Start by asking the CLI to discover plugin repositories under ~/grounds: 
grounds workspace scan ~/grounds
Without --yes, the CLI prints the mappings it found and asks before writing them. Once the proposed mappings look right, write them immediately: 
grounds workspace scan ~/grounds --yes
Scan does not replace existing mappings. If you already pinned custom Velocity artifacts or build commands, those entries stay in place.

​
Pin exact Velocity artifacts

For Velocity plugin repositories, add explicit mappings so the push uses the deployable shadow JAR from each repository: 
grounds workspace add plugin-agones ~/grounds/plugin-agones \
  --variant velocity \
  --artifact velocity/build/libs/plugin-agones-velocity.jar \
  --build './gradlew :velocity:shadowJar'

grounds workspace add plugin-player ~/grounds/plugin-player \
  --variant velocity \
  --artifact velocity/build/libs/plugin-player-velocity.jar \
  --build './gradlew :velocity:shadowJar'
The artifact path is relative to the plugin repository. The build command runs inside that repository before the artifact is resolved.

​
Add Minestom module mappings

For Minestom runtime modules, add a mapping for the minestom variant: 
grounds workspace add plugin-agones ~/grounds/plugin-agones --variant minestom
If Gradle composite substitution needs explicit coordinates, add module and project to workspace.yaml: 
repos:
  plugin-agones:
    path: /home/alice/grounds/plugin-agones
    variants:
      minestom:
        enabled: true
        module: gg.grounds:plugin-agones-minestom
        project: :minestom
When both fields are present, the CLI generates a temporary Gradle init script that includes the local repository and substitutes the release module with the local project.
For Minestom module substitution, the app’s Gradle distribution task builds against the included local repository. The workspace artifact and build fields are used for plugin artifact overrides and are not the source of truth for the Minestom runtime classpath.

​
Inspect mappings

List the workspace entries before pushing: 
grounds workspace list
Use doctor when a mapping does not behave as expected: 
grounds workspace doctor
workspace list shows each plugin or module ID, variant, enabled state, repository path, artifact path, and build command. workspace doctor checks whether configured paths exist and reports missing local repositories.

​
Push one local override

From ~/grounds/sample-plugin-workspace/app, override only plugin-agones for this push: 
grounds push --target=dev --local plugin-agones
The app manifest still reads both plugins from release sources, but the CLI replaces plugin-agones with the local Velocity artifact for this one push. For Minestom manifests, --local selects matching entries from modules. You can pass multiple local plugin IDs as a comma-separated value: 
grounds push --target=dev --local plugin-agones,plugin-player
You can also repeat --local: 
grounds push --target=dev --local plugin-agones --local plugin-player

​
Push every enabled local override

When every enabled workspace mapping should replace its matching manifest entry, use --with-local: 
grounds push --target=dev --with-local
This is the usual internal loop for the sample workspace after both Velocity artifacts are pinned. It also applies to enabled Minestom module mappings. Disabled mappings are ignored.

​
Disable a mapping temporarily

Disable plugin-player when you want --with-local to keep using the release source for that plugin: 
grounds workspace enable plugin-player velocity --disable
Enable it again when you want the local Velocity artifact back in the push: 
grounds workspace enable plugin-player velocity

​
Config location

Workspace mappings are stored in the CLI config directory as workspace.yaml. By default, that is:
OSDefault workspace file
Linux~/.config/grounds/workspace.yaml
macOS~/Library/Application Support/grounds/workspace.yaml
Windows%APPDATA%\grounds\workspace.yaml
The global --config <dir> flag and GROUNDS_CONFIG_DIR environment variable move this file together with the rest of the CLI config. See Configuration for the full config directory rules.

​
Reference