cub link update
cub link update
Update a link or multiple links
Synopsis
Update a link or multiple links using bulk operations.
Single link update:
cub link update my-link from-unit to-unit [to-space]
Individual patch with --patch:
Update a single link using JSON merge patch. Requires --patch flag with link slug.
Examples:
# Patch individual link with JSON
echo '{"Labels": {"env": "prod"}}' | cub link update my-link --patch --from-stdin
# Patch individual link with labels
cub link update my-link --patch --label env=prod,team=backend
Bulk update with --patch:
Update multiple links at once based on search criteria. Requires --patch flag with no positional arguments.
Examples:
# Update labels for multiple links using JSON patch
echo '{"Labels": {"env": "prod"}}' | cub link update --patch --where "DisplayName LIKE 'app-%'" --from-stdin
# Update labels for multiple links using --label flag
cub link update --space my-space --patch --where "DisplayName LIKE 'app-%'" --label env=prod,team=backend
# Update links across the organization: without --space, --where spans every space
cub link update --patch --where "ToSpaceID = 'old-space-id'" --from-stdin
# Update specific links by slug
echo '{"Labels": {"updated": "true"}}' | cub link update --patch --link my-link,another-link --from-stdin
Resetting merged-revision pointers with --make-current:
--make-current sets a link's UpstreamLastMergedRevisionNum and DownstreamLastMergedRevisionNum to the current head revisions of the units it connects, declaring the link caught up without merging anything. Use it to repair a link whose pointers name a revision that no longer exists, which otherwise fails every write to that link. Because the values come from each link's own units, a bulk --make-current patches the matched links one at a time.
Examples:
# Repair one link
cub link update upgrade-my-unit --space my-space --patch --make-current
# Repair every UpgradeUnit link in a space
cub link update --patch --space my-space --where "UpdateType = 'UpgradeUnit'" --make-current
Setting merged-revision pointers explicitly:
--upstream-last-merged-revision and --downstream-last-merged-revision set the two pointers to values you choose, rather than to the units' heads. Use them to move a pointer BACKWARD, which --make-current cannot do: an UpgradeUnit link whose UpstreamLastMergedRevisionNum has run ahead of the data actually merged into the downstream unit treats the skipped upstream changes as local overrides and silently drops them from every later upgrade. Rewinding the pointer to the last upstream revision that was really merged restores the merge base.
On an UpgradeUnit link the server rewrites a pointer of 0 to the corresponding unit's head, so 0 cannot be used to mean "never merged" there. Both flags work with and without --patch, and on cub link create. They are mutually exclusive with --make-current and --reverse, which write the same two fields.
Examples:
# Rewind the merge base to upstream revision 36
cub link update upgrade-deployment --space my-space --patch --upstream-last-merged-revision 36
# Set both pointers at once
cub link update upgrade-deployment --space my-space --patch \
--upstream-last-merged-revision 36 --downstream-last-merged-revision 63
cub link update [<link slug or id> <from unit slug> <to unit slug> [<to space slug>]] [flags]
Options
--annotation strings annotations in key=value format; can separate by commas and/or use multiple instances of the flag
--auto-update enable automatic downstream unit updates when upstream changes; a link created with no --update-type gets this without asking
--clearance stringArray class of guarded reason this link's merges are cleared for, as KEY, KEY=VALUE[;VALUE...], KEY!=VALUE[;VALUE...], or !KEY to refuse any path carrying KEY (repeatable). Pass an empty value to clear
--delete-gate strings delete gates in key[=true] format; can separate by commas and/or use multiple instances of the flag
--display-name string friendly name for the entity, which need not be unique or URL-safe; an entity without one is shown by its slug
--downstream-last-merged-revision int set DownstreamLastMergedRevisionNum explicitly: the downstream revision the last merge produced
--downstream-path stringArray value a TransformPaths link writes to the downstream unit, as [<key>=]<resource-type>:<resource-name>:<path>=[<data-type>:][<evaluator>:]<expression> (repeatable). The evaluator is template, the default, or cel; the data type is string, the default, int or bool. The upstream values the expression refers to are recorded as its parameters. The key identifies the entry when two versions of the link are merged
--downstream-setter stringArray function a TransformPaths link runs on the downstream unit, as [<key>=]<function> [<argument>...] (repeatable), the function written as on the cub function do command line. An argument prefixed template: or cel: is evaluated before the function runs, and may refer to the upstream values, as in template:{{.Params.tag}}; those it refers to are recorded as the setter's parameters
--dry-run report what the command would write, and write nothing
--filename string Read the ConfigHub entity's fields, as YAML or JSON, from file, URL (https://), or stdin (-), as --from-stdin does; 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"
--from-backing-units patch each Link selected with what its backing Unit holds that it has not taken yet; the patch the other flags make is applied after it
--from-stdin Read the ConfigHub entity's fields, as YAML or JSON, from stdin; merged with command arguments on create, and merged with command arguments and existing entity on update. A field the entity does not have, or one only the server sets, is refused; cub <entity> explain lists the fields
--guard stringArray reason to record on the paths this link's resolve writes, as KEY=VALUE (repeatable). A later operation must be cleared for it before overwriting those paths, the link's next resolve included, so --clearance has to cover it; refused on UpgradeUnit and MergeUnits links, whose guards propagate from upstream. Pass an empty value to clear
-h, --help help for update
--hidden-reason string hide the entity, giving the reason as a name such as Archived: lists and bulk operations leave it out unless --include-hidden names the reason (use '-' to clear, which shows the entity again)
--include-hidden string[="*"] Also select hidden entities, to list or to act on: those hidden for the given HiddenReasons, comma-separated, as in --include-hidden=BackingUnit, or for any reason when given no value or "*". ConfigHub/YAML Units, which hold the configuration of other entities, are hidden with the reason BackingUnit. A --where naming entities by Slug or ID selects them whether hidden or not
--label strings labels in key=value format; can separate by commas and/or use multiple instances of the flag
--link strings target specific links by slug or UUID for bulk patch (can be repeated or comma-separated)
--make-current set link revision numbers to current unit revisions; on create this skips the initial merge, on update it re-points the link at what the units now hold
--manual-binding stringArray binding stated for the link, as [<key>[:<attribute-name>]=]<needed <resource-type>:<resource-name>:<path>>[=[<data-type>:]<provided <resource-type>:<resource-name>:<path>>] (repeatable): the place in the downstream unit that needs a value, then the place in the upstream unit that provides it. The data type is string by default. An Insert link's one binding gives only the needed place, optionally followed by =<data-type>
--merge-enable-subtraction also subtract the downstream unit's local differences from the patch when resolving this link, on top of the stored path protection that preserves overrides by default
--no-auto-update disable automatic downstream unit updates; a link that does not update itself instead reports Stale when its upstream moves past it
--no-merge-enable-subtraction return this link to the default: no subtraction step
--no-protect return this link to the default: its resolve claims nothing it writes
--no-squash return this link to the default: its resolve walks the range
-o, --output string Output format. One of: json, yaml, name, wide, mutations, jq=<expr>, yq=<expr>, custom-columns=<spec>
--patch use patch API for individual or bulk operations
--permission strings permission in format Action:UserIDOrUsername, Action:group:GroupSlugOrID or Action:serviceaccount:ServiceAccountSlugOrID to add, or the same prefixed with - to remove (e.g., Manage:user@example.com, View:group:platform, View:serviceaccount:deploy-bot, -View:user@example.com, can be repeated)
--protect record the paths this link's resolve writes as protected local overrides, so a later merge from upstream does not overwrite them; refused on UpgradeUnit and MergeUnits links
--quiet No default output.
--replace Replace entity instead of merging when using --from-stdin or --filename
--reverse swap FromUnit and ToUnit directions (requires --patch); cross-space links are reversed by creating reversed copies and deleting the originals
--set stringArray set a field of the Link by its path, as <path>=<value> (repeatable). A path is field names separated by dots; a list element is addressed as ?<key>=<value> or by position, as in Stages.?Name=prod.WhereSpace, and is added if it is not there. A list of plain values separates them with ';'; an object or a list of objects is given as YAML or JSON. A reference is given as it is elsewhere, by slug, <space>/<slug> or ID. With --patch, only a path with no list element in it
--squash merge this link's range as one rebased diff in one revision instead of walking it: by default a resolve re-runs the upstream's recorded function invocations against the downstream unit where it can, and records one revision per upstream revision that has an effect; only meaningful for UpgradeUnit and MergeUnits links
--timeout string completion timeout as a duration with units, such as 10s or 2m (default "10m0s")
--transform-invocation string Invocation slug (or space/slug, or UUID) whose function transforms upstream data before it is inserted or upserted; only valid with --update-type Insert or Upsert
--unset stringArray clear a field of the Link by its path, or remove the list element the path ends at (repeatable)
--upstream-getter stringArray function a TransformPaths link runs on the upstream unit for a value, as <name>=<function> [<argument>...] (repeatable), the function written as on the cub function do command line. An argument prefixed template: or cel: is evaluated before the function runs; the getter runs before there are upstream values, so it cannot refer to them
--upstream-last-merged-revision int set UpstreamLastMergedRevisionNum explicitly: the upstream revision the link is treated as merged through
--upstream-path stringArray value a TransformPaths link reads from the upstream unit, as <name>=<resource-type>:<resource-name>:<path> (repeatable). The name is what an expression or a setter refers to it by, as .Params.<name> in a template and params.<name> in CEL
--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 mutations of the downstream unit whose paths this link's merges must not overwrite; unioned with the unit's stored path protection, so it protects more and never re-opens a path the unit claimed
--where-resource string where expression to select upstream resources for propagation
--with-backing-units give each Link the bulk operation writes a backing Unit if it has none: a ConfigHub/YAML Unit holding its configuration, kept in step with it
Options inherited from parent commands
--component string the Component of --variant, when that names the variant alone; --variant <component>/<variant> says the same in one flag
--context string The context to use for this command
--debug Debug output
--space string space to operate in, by slug or UUID. Omitted, a list or bulk operation spans the organization and a single entity is named as <space>/<slug>; "*" means the same as omitting it
--variant string variant to operate in, as <component>/<variant>, or as <variant> with --component: the space naming that Component whose Variant label is <variant>. The same scope as --space, named by what it is rather than by the space's slug; the two cannot be combined
SEE ALSO
- cub link - Link commands