murmur set

Creates or fully replaces a catalog resource. The complete resource definition is read from stdin. For markdown kinds (agent personas, flights), pipe markdown. For all other kinds, pipe YAML.

Synopsis

<stdin> | murmur set <kind> <name> [--if-generation N] [--manager NAME] [--force-ownership] [--propose [--rationale TEXT]] [--file-field field.path=filename ...]

Arguments

Name	Type	Required	Description
`kind`	string	yes	The catalog resource kind. Run `murmur describe` to list available kinds and their input formats.
`name`	string	yes	The resource name to create or replace.
`--file-field`	string	no	Inject file content at a dotted field path. Format: `field.path=filename`. Repeatable.
`--if-generation`	integer	no	Commit only if the resource’s current generation equals this value. `0` means the resource must not exist (an atomic create). Must be `>= 0`. Cannot be combined with `--propose`.
`--manager`	string	no	Declare the system responsible for this resource (for example, your automation’s name). It is recorded as the resource’s `managed_by` marker. Later writes that do not declare the same manager are refused unless forced. Leave unset for a manual edit. Cannot be combined with `--propose`.
`--force-ownership`	boolean	no	Write even when another system manages the resource. Without `--manager`, the write releases the resource (its `managed_by` marker is cleared). With `--manager`, that manager becomes the new one. Cannot be combined with `--propose`.
`--propose`	boolean	no	Stage the change as a change-request for review instead of writing it directly.
`--rationale`	string	no	Rationale recorded on the change-request. Requires `--propose`.

Input format

The command queries the server to determine whether the kind expects YAML or markdown input.

YAML kinds (e.g. workspace, environment, pool-config) — pipe a YAML document to stdin.
Markdown kinds (e.g. agent-persona, flight) — pipe a markdown document with YAML frontmatter to stdin. When the input starts with ---, the entire input becomes the resource content. Otherwise it is parsed as YAML.

Stdin is required unless at least one --file-field is given. When --file-field is provided, the file content is injected at the specified field path. This is useful for fields that contain large text content — like provisioning scripts — that are easier to maintain as separate files. Dotted paths set nested fields, and intermediate maps are created as needed. The generation: and managed_by: keys that murmur get emits may stay in the piped document. The server drops them.

This is a full replace. Every field in the existing resource is overwritten by the payload. To update individual fields without replacing the resource, use murmur patch.

Conditional writes

With --if-generation N, the write commits only if the resource’s current generation equals N. murmur get prints the current generation as the document’s first key. On a mismatch the server fails with FAILED_PRECONDITION and writes nothing: re-run murmur get, re-apply your edit, and retry.

Managed resources

A write is a manual edit and declares no manager, so it is refused when the resource is managed by another system (Terraform, or your own automation), because that system may overwrite the change on its next run. murmur get prints the managed_by marker beside the generation. --force-ownership writes anyway. It does not remove the resource from whatever manages it: if the resource is still in Terraform configuration, the next terraform apply reverts the value and reclaims the marker. To keep the edit, remove the resource from configuration (or terraform state rm it) first.

Builtins

Names starting with murmur- (and the name murmur) are reserved for platform builtins and cannot be written. Running murmur set <kind> <builtin-name> with no stdin and no --file-field re-enables a builtin that was disabled with murmur rm.

Output

On success, the command prints a confirmation with the resource’s new generation to stderr:

Set pool-config "default" (generation 1727481600123456)

Re-enabling a builtin prints Re-enabled builtin <kind> "<name>". With --propose, nothing is written. The command prints a summary line to stderr and the new change-request ID to stdout:

Created change-request cr-8f3a2b1c9d0e (PENDING) for recipe/default
cr-8f3a2b1c9d0e

Review pending proposals with murmur get change-request. Apply one with murmur change-request approve <id>.

Examples

Set a pool config

echo 'max_vms: 50' | murmur set pool-config default

Set pool-config "default" (generation 1727481600123456)

Set an agent persona from a markdown file

cat architect.md | murmur set agent-persona architect

Set agent-persona "architect" (generation 1727481600123456)

Read, modify, and write back

murmur get environment staging | yq '.machineTypeRef = "murmur-n2-standard-16"' | murmur set environment staging

Set environment "staging" (generation 1727481600123456)

Write only if nothing changed since the read

murmur get environment staging > staging.yaml
# edit staging.yaml, note its generation: value
murmur set environment staging --if-generation 1727481600123456 < staging.yaml

Create only if the resource does not exist

murmur set environment gpu --if-generation 0 < gpu.yaml

Inject a provisioning script from a file

echo 'provisioning_timeout: 10m' | murmur set recipe python-toolchain --file-field provisioning_script=provision.sh

Set recipe "python-toolchain" (generation 1727481600123456)

Propose a change for review

murmur get recipe default | yq '.provisioningTimeout = "20m"' | murmur set recipe default --propose --rationale "longer provisioning timeout"

Created change-request cr-8f3a2b1c9d0e (PENDING) for recipe/default
cr-8f3a2b1c9d0e

Errors

Code	Meaning	What to do
`UNAUTHENTICATED`	Identity token is missing or expired.	Run `murmur login`, or check your `murmur.local.yaml` configuration.
`INVALID_ARGUMENT`	The kind is not recognized, the payload is invalid, or the name is reserved for builtins.	Run `murmur describe` to check the kind’s schema and input format. Choose a name that does not start with `murmur-`.
`FAILED_PRECONDITION`	A referenced resource does not exist (e.g. a workspace references a nonexistent environment), or the `--if-generation` value does not match the current generation.	Verify that all referenced resources exist with `murmur get`. For a generation mismatch, re-read the resource, re-apply your edit, and retry.
`FAILED_PRECONDITION`	`<kind> "<name>" is managed by "<manager>", which may overwrite this change on its next run; re-run with --force-ownership to write anyway and ...`	Change the resource through the system that manages it, or re-run with `--force-ownership`.
`PERMISSION_DENIED`	Your role does not grant write access to this kind.	Ask a tenant admin for access, or use `--propose` to stage the change for review.

The CLI rejects these flag combinations before contacting the server:

Error	What to do
`--rationale requires --propose`	Add `--propose`, or drop `--rationale`.
`--if-generation cannot be combined with --propose: ...`	Drop one of the two flags. A change-request records its own base version.
`--force-ownership cannot be combined with --propose: ...`	Drop one of the two flags.
`--manager cannot be combined with --propose: ...`	Drop one of the two flags.

Catalog — concept overview
Change requests — review and apply proposed changes
murmur get — read a resource or list resources of a kind
murmur patch — update individual fields without replacing the resource
murmur rm — delete a resource
murmur describe — show schema information for a kind

Getting Started

Core Concepts

Guides

Synopsis

Arguments

Input format

Conditional writes

Managed resources

Builtins

Output

Examples

Set a pool config

Set an agent persona from a markdown file

Read, modify, and write back

Write only if nothing changed since the read

Create only if the resource does not exist

Inject a provisioning script from a file

Propose a change for review

Errors

​Synopsis

​Arguments

​Input format

​Conditional writes

​Managed resources

​Builtins

​Output

​Examples

​Set a pool config

​Set an agent persona from a markdown file

​Read, modify, and write back

​Write only if nothing changed since the read

​Create only if the resource does not exist

​Inject a provisioning script from a file

​Propose a change for review

​Errors

​Related

Synopsis

Arguments

Input format

Conditional writes

Managed resources

Builtins

Output

Examples

Set a pool config

Set an agent persona from a markdown file

Read, modify, and write back

Write only if nothing changed since the read

Create only if the resource does not exist

Inject a provisioning script from a file

Propose a change for review

Errors

Related