Skip to main content
Local workspaces let you keep grounds.yaml pointed at release sources while opting into local builds for a single push. Use this workflow when your app lives in one repository and its plugin or Minestom module dependencies 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:
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 IDs to the local repositories on your machine. Your manifest stays portable:
grounds.yaml
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.

​
Scan for repositories

Start by asking the CLI to discover plugin repositories under ~/grounds:
Without --yes, the CLI prints the mappings it found and asks before writing them. Once the proposed mappings look right, write them immediately:
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:
The artifact path is relative to the plugin repository. The build command runs inside that repository before the artifact is resolved.

​
Map a Minestom module

Minestom servers use a complete application distribution, not a plugin folder. For a local Minestom module, map the repository by its minestom variant:
The CLI substitutes the module through a Gradle composite build during a Minestom push. Add explicit coordinates only when the repository’s Gradle project path or published coordinates do not match automatically:
workspace.yaml
module and project form one substitution rule. Configure both fields or neither one. See Local Minestom modules for the matching manifest and push flow.

​
Inspect mappings

List the workspace entries before pushing:
Use doctor when a mapping does not behave as expected:
workspace list shows each plugin 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:
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. You can pass multiple local plugin IDs as a comma-separated value:
You can also repeat --local:

​
Push every enabled local override

When every enabled workspace mapping should replace its matching manifest entry, use --with-local:
This is the usual internal loop for the sample workspace after both Velocity artifacts are pinned. 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:
Enable it again when you want the local Velocity artifact back in the push:

​
Config location

Workspace mappings are stored in the CLI config directory as workspace.yaml. By default, that is: 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