Skip to main content
Local plugin workspaces let you test several independent plugin repositories together without putting machine-specific paths in grounds.yaml. For the internal step-by-step workflow, start with Work with local plugin workspaces. The manifest stays portable and points at release sources. Your local workspace.yaml maps plugin IDs and variants to repositories on your machine. grounds push only uses those local builds when you ask for them with --local or --with-local.
Use workspace overrides for dependency development: app repo in one directory, plugin repos as siblings, and release sources as the default for every teammate and CI run.

​
Config file

Workspace mappings live in the CLI config directory: 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.

​
Manifest shape

Local overrides match entries in grounds.yaml by id and optional variant:
grounds.yaml
source remains the default release source. id and variant give the CLI a stable key for local replacement.

​
Add mappings explicitly

Use workspace add when you know the repository path and artifact layout:
Artifact globs should resolve to the deployable JAR. If multiple JARs match, the resolver ignores common auxiliary JARs such as -sources and -javadoc and prefers shadow/all artifacts.

​
Minestom composite builds

For a minestom variant, the mapping supplies the local repository path to a temporary Gradle composite build. The CLI still writes the generic JAR and shadowJar defaults because all workspace mappings share one schema, but Minestom ignores those values. It runs the server distribution task and resolves the distribution artifact from the selected grounds.yaml flavor instead.
Gradle usually substitutes an included build automatically when its published coordinates match the release module. For an explicit module-to-project substitution, add module and project to the Minestom variant in workspace.yaml; see Local Minestom modules.

​
Scan sibling repos

Use workspace scan to discover local plugin repositories under one or more directories:
Without --yes, the CLI prints the proposed mappings and asks before writing. With --yes, it writes immediately.
Scan does not overwrite existing mappings. If you have custom build commands or artifact paths, they stay in place.

​
Inspect and toggle mappings

workspace list prints each mapping with ID, variant, enabled state, path, artifact, and build command. workspace doctor checks whether configured repo paths exist.

​
Push with local overrides

Use release sources by default:
Override one or more plugins for this push:
Override every enabled workspace entry that appears in grounds.yaml:
Before Gradle runs, the CLI prints the effective source table:
Effective tells you whether the push uses the release source from grounds.yaml or a local artifact from workspace.yaml.

​
Behavior and safety

  • Local overrides apply only to the push where you pass --with-local or --local.
  • The CLI builds local repos before resolving their artifacts.
  • Git metadata is best-effort. Non-git directories still work.
  • Local filesystem paths are passed to Gradle through a generated resolved plugins file; they do not need to appear in grounds.yaml.
  • Local path values are not shown in portal source labels. Portal shows a safe artifact label and records that the effective source was local.