cub unit update
cub unit update
Update a unit
Synopsis
Update an existing unit in a space. Units can be updated with new configuration data, restored to previous revisions, or upgraded from upstream units.
Like other ConfigHub entities, Units have metadata, which can be partly set on the command line and otherwise read from stdin using the flag --from-stdin or --replace-from-stdin.
Unit configuration data can be provided in multiple ways:
- From a local or remote configuration file, or from stdin (by specifying "-")
- By restoring to a previous revision (using --restore)
- By upgrading from the upstream unit (using --upgrade)
- By performing a 3-way merge with another unit (using --merge-source, --merge-base, --merge-end)
Examples:
# Update a unit from a local YAML file
cub unit update --space my-space myunit config.yaml
# Update a unit from a file:// URL
cub unit update --space my-space myunit file:///path/to/config.yaml
# Update a unit from a remote HTTPS URL
cub unit update --space my-space myunit https://example.com/config.yaml
# Update a unit with config from stdin
cub unit update --space my-space myunit -
# Combine Unit JSON metadata from stdin with config data from file
cub unit update --space my-space myunit config.yaml --from-stdin
# Restore a unit to revision 5
cub unit update --space my-space myunit --restore 5
# Restore a unit to 2 revisions ago (relative to head)
cub unit update --space my-space myunit --restore -2
# Restore a unit using a specific revision ID
cub unit update --space my-space myunit --restore 550e8400-e29b-41d4-a716-446655440000
# Restore a unit to the live revision
cub unit update --space my-space myunit --restore LastReleasedRevisionNum
# Restore a unit to the last released revision
cub unit update --space my-space myunit --restore LastReleasedRevisionNum
# Restore a unit to a tagged revision (supports space/tag syntax)
cub unit update --space my-space myunit --restore Tag:release-v1.0
cub unit update --space my-space myunit --restore Tag:production/hotfix-patch
# Restore a unit to the end of a changeset (supports space/changeset syntax)
cub unit update --space my-space myunit --restore ChangeSet:feature-rollout
cub unit update --space my-space myunit --restore ChangeSet:dev-space/bug-fixes
# Upgrade a unit to match its upstream unit
cub unit update --space my-space myunit --upgrade
# Upgrade only as far as a point in the upstream's history, leaving later changes behind
cub unit update --space my-space myunit --upgrade --merge-end ChangeSet:upstream-space/release-42
cub unit update --space my-space myunit --upgrade --merge-end Tag:v1.0
# Promote a change order: it supplies the range, and units outside it are passed over
cub unit update --patch --space my-space --where "UpstreamRevisionNum > 0" \
--upgrade --change-order base-space/release-42 --change-desc "Take release-42"
# Undo that promotion, however many revisions it made, recording it against the change order
# ("cub variant demote" is this over a whole space, and selects the units for you)
cub unit update --patch --space my-space --where "UpstreamRevisionNum > 0" \
--restore Before:ChangeOrder:base-space/release-42 --change-order base-space/release-42 \
--change-desc "Roll release-42 back"
# Update with a change description
cub unit update --space my-space myunit config.yaml --change-desc "Updated database configuration"
# Perform a 3-way merge with another unit
cub unit update --space my-space myunit --merge-source other-unit --merge-base LastReleasedRevisionNum --merge-end HeadRevisionNum
# Merge with specific revisions
cub unit update --space my-space myunit --merge-source upstream-unit --merge-base Tag:v1.0 --merge-end 42
# Merge with the unit itself (self-merge)
cub unit update --space my-space myunit --merge-source Self --merge-base LastReleasedRevisionNum --merge-end HeadRevisionNum
Patch Mode Examples:
# Individual patch with labels
cub unit update --patch --space my-space myunit --label version=1.2
# Patch with data from file plus metadata changes
cub unit update --patch --space my-space myunit --filename patch.json --change-desc "Updated annotations" --label patched=true
# Bulk patch with change description and labels
cub unit update --patch --where "Slug LIKE 'app-%'" --change-desc "Metadata review" --label reviewed=2024-01
# Bulk patch across all spaces with metadata
cub unit update --patch --space "*" --where "UpstreamRevisionNum > 0" --change-desc "Upgrade all" --upgrade
# Bulk restore with change description
cub unit update --patch --where "Slug IN ('unit1', 'unit2')" --restore LastReleasedRevisionNum --change-desc "Restored to last released revision"
# Bulk patch with data from stdin plus metadata (just an example; use cub unit set-target for this case)
echo '{"TargetID": null}' | cub unit update --patch --unit unit1,unit2,unit3 --from-stdin --change-desc "Cleared targets"
cub unit update <slug or id> [config-file] [flags]
Options
--annotation strings annotations in key=value format; can separate by commas and/or use multiple instances of the flag
--change-desc string change description
--change-order string change order to promote, with --upgrade or --resolve: it supplies both ends of the range, so --merge-end is not accepted alongside it; units its source doesn't cover are passed over, and a unit that isn't where it starts is an error. With --restore Before:ChangeOrder:<slug> it is the change order being undone instead: it must have an AbortedReason, the restore must name the same change order, the revisions restored are marked with the change order's restore tag, a unit already carrying that tag is passed over, and the merge pointers of the links that follow each restored unit are advanced onto the restored revision. "cub variant demote" is that over a whole space
--changeset string changeset to associate the unit with (use '-' to remove in patch mode)
--clearance stringArray class of guarded reason this change is cleared for, as KEY, KEY=VALUE[,VALUE...], KEY!=VALUE[,VALUE...], or !KEY to refuse any path carrying KEY (repeatable). A guarded path this does not cover is not written, and the withheld change is reported as a conflict
--delete-gate strings delete gates in key[=true] format; can separate by commas and/or use multiple instances of the flag
--destroy-gate strings destroy gate for the unit (can be repeated or comma-separated)
--dry-run dry run mode: return changed unit(s) but don't update configuration data
--filename string Read the ConfigHub entity JSON from file, URL (https://), or stdin (-); mutually exclusive with --from-stdin
--filter string Filter entity to apply to the list. Specify as 'space/filter' for cross-space filters or just 'filter' for current space. Supports both slugs and UUIDs. The filter will be combined with any --where clause using AND logic. Examples: "production-filters/security-check", "my-filter-uuid", "validation-rules"
--filter-mutation string filter selecting this unit's mutations whose paths the merge must not overwrite, on top of the stored path protection (only used with --merge-source)
--from-stdin Read the ConfigHub entity JSON (e.g., retrieved with cub <entity> get --quiet --json) from stdin; merged with command arguments on create, and merged with command arguments and existing entity on update
--guard stringArray reason to record on the paths this change writes, as KEY=VALUE (repeatable). A later operation must be cleared for it before overwriting those paths. Adds and overwrites only; retiring a guard is cub unit set-guard --remove-guard
-h, --help help for update
--label strings labels in key=value format; can separate by commas and/or use multiple instances of the flag
--merge-base string base revision for 3-way merge (uses same format as --restore); with --merge-external-source, overrides the default selection of the latest MergeExternal revision
--merge-enable-subtraction also subtract the target's local differences from the patch during --upgrade and --merge-source, on top of the stored path protection that preserves overrides by default (no effect on --merge-source Self)
--merge-end string end revision of the source, for a 3-way merge, an --upgrade, or a --resolve (uses same format as --restore)
--merge-external-source string external source identifier for merge-on-update
--merge-source string source unit for 3-way merge (slug or UUID)
--option stringArray bridge options in key=value format; use semicolons to separate multiple options within one flag value (e.g., --option 'key1=val1;key2=val2'); each --option flag instance corresponds to a ConfigType by position
-o, --output string Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
--patch use patch API instead of update API
--protect record the paths this change writes as protected local overrides, so a later merge from upstream does not overwrite them; by default a change claims nothing and each path keeps the protection it already has
--provider string provider type for the unit; None marks the unit as not applied and not included in releases
--quiet No default output.
--replace Replace entity instead of merging when using --from-stdin or --filename
--resolve string resolve links from this unit: Link:* for every link that can resolve, Link:<uuid> or Link:<slug> for one, just <slug> (e.g. space/link-name), or Link:<where expression> to select among them (e.g. "Link:UpdateType = 'MergeUnits'") -- the form to use in a bulk operation, where a uuid cannot be. An AutoUpdate link can be resolved by hand and does nothing when it is already level with its source
--restore string restore to a revision: a tag slug, Tag:slug, ChangeSet:slug, ChangeOrder:slug, Revision:uuid, an integer (revision number), a negative delta from head, or one of HeadRevisionNum/LastReleasedRevisionNum, optionally prefixed with Before:
--squash merge the range as one rebased diff in one revision instead of walking it: by default a merge re-runs the upstream's recorded function invocations against this unit where it can, so each change lands where this unit's own structure puts it, and records one revision per upstream revision that has an effect here; only valid with --upgrade, --merge-source, or --resolve
--tag string UUID of tag to attach to (new) head revision
--timeout string completion timeout as a duration with units, such as 10s or 2m (default "10m0s")
--unit strings target specific units by slug or UUID (can be repeated or comma-separated)
--upgrade upgrade the unit to the latest version of its upstream unit
--verbose Detailed output, additive with default output
--wait wait for completion (default true)
--where string Filter expression using SQL-inspired syntax. Supports conjunctions with AND. String operators: =, !=, <, >, <=, >=, LIKE, NOT LIKE, ILIKE, ~~, !~~, ~, ~*, !~, !~*. Pattern matching with LIKE/ILIKE uses % and _ wildcards. Regex operators (~, ~*, !~, !~*) support POSIX regular expressions. A related entity is referenced by prefix, as in "UpstreamUnit.Slug = 'base'"; when the reference names a list, a * segment matches any element, as in "FromLink.*.Slug = 'upgrade-app'". Examples: "Slug LIKE 'app-%'", "DisplayName ILIKE '%backend%'", "Slug ~ '^[a-z]+-[0-9]+$'"
--where-mutation string where expression selecting this unit's mutations whose paths the merge must not overwrite, on top of the stored path protection (only used with --merge-source). On a --merge-source Self revert, where the stored protection is not consulted, it is the whole of what the revert leaves alone
Options inherited from parent commands
--context string The context to use for this command
--debug Debug output
--space string space ID to perform command on
SEE ALSO
- cub unit - Unit commands