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 --patch --where "DisplayName LIKE 'app-%'" --label env=prod,team=backend

  # Update links across all spaces (requires --space "*")
  cub link update --patch --space "*" --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
      --downstream-last-merged-revision int   set DownstreamLastMergedRevisionNum explicitly: the downstream revision the last merge produced
      --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"
      --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 link's resolve writes, as KEY=VALUE (repeatable). A later operation must be cleared for it before overwriting those paths; refused on UpgradeUnit and MergeUnits links, whose guards propagate from upstream. Pass an empty value to clear
  -h, --help                                  help for update
      --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
      --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
      --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
      --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
      --update-type string                    link update type (NeedsProvides, MergeUnits, UpgradeUnit, None, Insert, Upsert, or TransformPaths); the default is a NeedsProvides link that updates itself
      --upstream-last-merged-revision int     set UpstreamLastMergedRevisionNum explicitly: the upstream revision the link is treated as merged through
      --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

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 link - Link commands