Skip to content

fragments: peer CLI on reuse-configuration; --fragment name-or-id #5023

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
shannonbradshaw wants to merge 4 commits into
base: main
Choose a base branch
from
+15 −11
Open

fragments: peer CLI on reuse-configuration; --fragment name-or-id #5023

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4e03b4a
reuse-configuration: surface CLI as peer to UI for applying fragments
shannonbradshaw Apr 26, 2026
cad2c60
Note interactive fragment selection when --fragment omitted
shannonbradshaw Apr 26, 2026
32f05c0
--fragment accepts name or id; widen interactive scope wording
shannonbradshaw Apr 26, 2026
755afe2
cli pages: --fragment accepts name or id
shannonbradshaw Apr 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/cli/configure-machines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,18 +167,18 @@ viam resource disable --part=<part-id> \

Fragments are reusable configuration blocks that can define a set of components, services, and their attributes.
Apply the same fragment across multiple machines to keep their configuration consistent.
Add a fragment to a machine part by specifying its fragment ID:
Add a fragment to a machine part by specifying its name or ID:

```sh {class="command-line" data-prompt="$"}
viam machines part fragments add --part=<part-id> --fragment=<fragment-id>
viam machines part fragments add --part=<part-id> --fragment=<fragment-name-or-id>
```

If you omit the `--fragment` flag, the CLI prompts you to select a fragment interactively.

Remove a fragment:

```sh {class="command-line" data-prompt="$"}
viam machines part fragments remove --part=<part-id> --fragment=<fragment-id>
viam machines part fragments remove --part=<part-id> --fragment=<fragment-name-or-id>
```

See [Reuse machine configuration](/fleet/reuse-configuration/) for details on creating and managing fragments.
Expand Down
8 changes: 4 additions & 4 deletions docs/cli/reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1261,28 +1261,28 @@ viam machines part remove-resource --part=<part id> --name=<resource name>
Attach a configuration fragment to a part.

```sh {class="command-line" data-prompt="$"}
viam machines part fragments add --part=<part id> [--fragment=<fragment id>]
viam machines part fragments add --part=<part id> [--fragment=<fragment name or id>]
```

<!-- prettier-ignore -->
| Argument | Description | Required? |
| -------- | ----------- | --------- |
| `--part` | Part ID for which the command is being issued. | **Required** |
| `--fragment` | Fragment ID to add. If omitted, the CLI prompts interactively. | Optional |
| `--fragment` | Fragment name or ID to add. If omitted, the CLI prompts interactively. | Optional |

### `machines part fragments remove`

Detach a configuration fragment from a part.

```sh {class="command-line" data-prompt="$"}
viam machines part fragments remove --part=<part id> [--fragment=<fragment id>]
viam machines part fragments remove --part=<part id> [--fragment=<fragment name or id>]
```

<!-- prettier-ignore -->
| Argument | Description | Required? |
| -------- | ----------- | --------- |
| `--part` | Part ID for which the command is being issued. | **Required** |
| `--fragment` | Fragment ID to remove. | Optional |
| `--fragment` | Fragment name or ID to remove. If omitted, the CLI prompts interactively. | Optional |

### `machines part motion print-config`

Expand Down
12 changes: 8 additions & 4 deletions docs/fleet/reuse-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,8 @@ Click **Save** after adding and configuring your resources.

## Apply a fragment to a machine

### In the Viam app

1. Navigate to your machine's **CONFIGURE** tab.
1. Click **+** and select **Configuration block**.
1. Search for your fragment by name and select it.
Expand All @@ -65,15 +67,17 @@ Click **Save** after adding and configuring your resources.

The fragment's resources now appear on the machine's configuration page. The machine downloads and applies the configuration on its next sync.

To apply a fragment to many machines, use the CLI in a loop or script:
### With the CLI

```sh {class="command-line" data-prompt="$"}
viam machines part fragments add --part=<part-id> --fragment=<fragment-id>
viam machines part fragments add --part=<part-id> --fragment=<fragment-name-or-id>
```

To find your part ID, run `viam machines part list --machine=<machine-id>`. To find your fragment ID, copy it from the fragment's page in the Viam app (it appears in the URL and under the fragment name).
To find your part ID, run `viam machines part list --machine=<machine-id>`. Pass either the fragment's name (visible on its page in the Viam app) or its ID (in the URL of the page). Names created in the Viam app contain only letters, numbers, and dashes, so they don't need shell quoting.

If you omit `--fragment`, the CLI prompts you to pick a fragment interactively from the ones available to you.

See [automate with scripts](/cli/automate-with-scripts/) for examples of scripting fleet operations.
To apply a fragment across many machines, see [Automate with scripts](/cli/automate-with-scripts/).

### Avoid resource name conflicts with a prefix

Expand Down
Loading