Collaboration

For the conceptual difference between these verbs, see Plug, pickup, pull, and collab.

grid collab

Get push access to the same live entity that someone else owns. You become a collaborator on that entity, not the holder of a copy. Collab grants permission only and fetches nothing: it does not download the source or link a folder.

grid collab <name>

Argument	Description
name	Entity slug, id, or grid/slug to get push access to.

Option	Description
--grid <slug>	Grid to resolve the entity in. Defaults to the active grid.
--claim-token <token>	Claim link for an anonymous drop.
--json	Print the raw access result as JSON.

The order is collab, then pull, then plug:

grid collab my-app   # get push access
grid pull my-app     # download the source and link the folder
grid plug            # updates the shared entity for everyone

After a successful collab, the CLI says so and points you at the next step: You're a collaborator on my-app. Run grid pull my-app to get the code and start pushing. If you can view the entity but the owner has not given you push access, it suggests grid pickup to make your own copy instead.

If the owner gates who may join, a collab does not end in an error. It becomes a request to the owner. Once they approve it, run grid collab <name> again.

Owners handle requests with three subcommands:

grid collab requests [entity] [--all]         # list who asked to join
grid collab approve <user> [entity]           # grant push access
grid collab deny <user> [entity] [--reason]   # refuse the request

entity defaults to the linked folder.

grid pickup

Make your own copy of an entity: a new, independent entity in your grid with lineage back to the original. Pickup does not give you access to the original; to work on the same entity with its owner, use grid collab. The copy is minted without the source’s secrets (set your own before you plug). After the copy is minted, its source is downloaded and the folder is linked so your next grid plug updates the copy.

grid pickup <id|grid/slug> [dir]

Argument	Description
id|grid/slug	App URL, id, or grid/slug to copy.
dir	Directory to lay the copy into. Defaults to the app name.

Option	Description
--into-org <slug>	Grid to create your copy in (required when you belong to multiple grids).
--name <slug>	Slug for your copy. Defaults to the source name plus a suffix.
--version <id>	Copy an older version of the source instead of HEAD.
--force	Lay the copy into a non-empty directory.
--no-bind	Create the copy only. Skips the source download and link.
--copy	Confirm the copy without prompting.
--claim-token <token>	Claim an anonymous drop: transfers ownership of that entity to you instead of copying.
--json	Print the result as JSON.

grid pull

Download an existing entity’s source, write a cloudgrid.yaml, and link the folder so your next grid plug updates the same entity in place. Use it to continue an entity you own, or one you already have push access to through grid collab. Pull does not grant access: you must own the entity or already be a collaborator on it.

grid pull <name> [target-dir]

Argument	Description
name	Entity slug, UUID, or grid/slug.
target-dir	Local directory to download into. Defaults to ./<slug>.

Option	Description
--no-bind	Record the grant only; skip the local download.
--grid <slug>	Grid override.
--force	Overwrite a non-empty target directory.
--version <id>	Pull an older version instead of the latest.
--json	Raw JSON response.

grid link

Bind the current folder to an existing grid entity without downloading code. An alias of grid wire folder.

grid link [entity]

Repair a stale binding:

grid link repair [--dry-run]   # fix a stale org_slug in link.json

grid rename

Change the display name of an entity. The slug (and URL) stays the same. Works for both runtimes and inspirations.

grid rename <slug> <new-display-name>