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 LiveRevisionNum
# Restore a unit to the last applied revision
cub unit update --space my-space myunit --restore LastAppliedRevisionNum
# 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
# 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 LiveRevisionNum --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 LiveRevisionNum --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 LiveRevisionNum --change-desc "Restored to live 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
--changeset string changeset to associate the unit with (use '-' to remove in patch mode)
--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 to select which mutations are affected during merge operations (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
-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-end string end revision for 3-way merge (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
--quiet No default output.
--replace Replace entity instead of merging when using --from-stdin or --filename
--resolve string resolve non-automatically resolved links: Link:* for all, Link:<uuid> or Link:<slug> for a specific link, or just <slug> (e.g., space/link-name)
--restore string restore to a revision: UUID (revision ID), integer (revision number), Tag:slug, ChangeSet:slug, or one of LiveRevisionNum/LastAppliedRevisionNum/PreviousLiveRevisionNum
--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. Examples: "Slug LIKE 'app-%'", "DisplayName ILIKE '%backend%'", "Slug ~ '^[a-z]+-[0-9]+$'"
--where-mutation string where expression to filter which mutations are affected during merge operations (only used with --merge-source)
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