> ## 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.

# Work with local plugin and module workspaces

> Override release plugin sources and Minestom module dependencies with local repositories.

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.

<Tip>
  Local overrides are machine-local. They do not change the manifest, and they
  only apply when you pass `--local` or `--with-local`.
</Tip>

## Repository layout

Use the internal sample workspace as the reference shape:

```text theme={null}
~/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 IDs to the local repositories on your machine.

Your manifest stays portable:

```yaml grounds.yaml theme={null}
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.

## Scan for repositories

Start by asking the CLI to discover plugin repositories under `~/grounds`:

```bash theme={null}
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:

```bash theme={null}
grounds workspace scan ~/grounds --yes
```

<Note>
  Scan does not replace existing mappings. If you already pinned custom Velocity
  artifacts or build commands, those entries stay in place.
</Note>

## Pin exact Velocity artifacts

For Velocity plugin repositories, add explicit mappings so the push uses the
deployable shadow JAR from each repository:

```bash theme={null}
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.

## 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:

```bash theme={null}
grounds workspace add plugin-agones ~/grounds/plugin-agones --variant minestom
```

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:

```yaml workspace.yaml theme={null}
repos:
  plugin-agones:
    path: /home/alice/grounds/plugin-agones
    variants:
      minestom:
        enabled: true
        module: gg.grounds:plugin-agones-minestom
        project: :minestom
```

`module` and `project` form one substitution rule. Configure both fields or
neither one. See [Local Minestom modules](/reference/development/minestom-runtime/local-modules)
for the matching manifest and push flow.

## Inspect mappings

List the workspace entries before pushing:

```bash theme={null}
grounds workspace list
```

Use `doctor` when a mapping does not behave as expected:

```bash theme={null}
grounds workspace doctor
```

`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:

```bash theme={null}
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.

You can pass multiple local plugin IDs as a comma-separated value:

```bash theme={null}
grounds push --target=dev --local plugin-agones,plugin-player
```

You can also repeat `--local`:

```bash theme={null}
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`:

```bash theme={null}
grounds push --target=dev --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:

```bash theme={null}
grounds workspace enable plugin-player velocity --disable
```

Enable it again when you want the local Velocity artifact back in the push:

```bash theme={null}
grounds workspace enable plugin-player velocity
```

## Config location

Workspace mappings are stored in the CLI config directory as `workspace.yaml`.
By default, that is:

| OS      | Default 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](/build/cli/configuration) for the full config directory rules.

## Reference

* [Workspace CLI reference](/build/cli/workspace)
* [Push CLI reference](/build/cli/push)
* [Configuration reference](/build/cli/configuration)
* [Build multi-plugin stacks](/build/multi-plugin-stacks)