cub link create
cub link create
Create a new link or bulk create (copy) links
Synopsis
Create a new link between two units or bulk create links by copying existing links.
SINGLE LINK CREATION:
Create a single link between two units. Links define relationships between units and can be used to establish dependencies or connections between resources.
A link can be created:
- Between units in the same space
- Between units across different spaces (by specifying the target space)
BULK LINK CREATION (COPY):
When no positional arguments are provided with --where or --filter plus at least --reverse or --from-downstream-where, bulk create mode is activated. This mode copies existing links and retargets their From and/or To units using downstream UpgradeUnit links.
A copy starts with no merge history and no delete gates of its own: the source link's merged-revision pointers name revisions of the units it connects, which a retargeted copy does not share. An UpgradeUnit copy is set to its new units' current revisions instead. --make-current is rejected here because its values are per-link; pass --upstream-last-merged-revision / --downstream-last-merged-revision if the copies need specific pointers, or run cub link update --make-current on them afterward.
Single Link Examples:
# Create a link between a deployment and its namespace in the same space
cub link create --space my-space --json to-ns my-deployment my-ns --wait
# Create a link for a complex application to its namespace
cub link create --space my-space --json headlamp-to-ns headlamp my-ns --wait
# Create a link between a cloned unit and a namespace
cub link create --space my-space --json clone-to-ns my-clone my-ns --wait
Bulk Create (Copy) Examples:
# Copy outgoing links from prod-v1 units to their downstream copies in prod-v2
cub link create --where "Space.Slug = 'prod-v1' AND ToSpaceID != SpaceID AND UpdateType != 'UpgradeUnit'" \
--from-downstream-where "UpdateType = 'UpgradeUnit' AND Space.Slug = 'prod-v2'"
# Also retarget the To units to their downstream copies
cub link create --where "Space.Slug = 'prod-v1' AND ToSpaceID != SpaceID" \
--from-downstream-where "UpdateType = 'UpgradeUnit' AND Space.Slug = 'prod-v2'" \
--to-downstream-where "UpdateType = 'UpgradeUnit' AND Space.Slug = 'prod-v2'"
# Reverse cross-space UpgradeUnit links (create the link in the To unit's space)
cub link create --where "Space.Slug = 'prod-v2' AND UpdateType = 'UpgradeUnit'" --reverse
cub link create [<link slug> <from unit slug> <to unit slug> [<to space slug>]] [flags]
Options
--allow-exists Allow creation of resources that already exist
--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-downstream-where string where expression to find downstream UpgradeUnit links from each source link's FromUnit; creates one copy per match
--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 create
--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 create (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>
--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.
--reverse swap FromUnit and ToUnit directions of copied links (for cross-space link reversal)
--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")
--to-downstream-where string where expression to find downstream UpgradeUnit link from each source link's ToUnit; exactly one match required
--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