Skip to content
CloudGrid Docs

Plug, pickup, pull, and collab

Four verbs move code, ownership, and access around the grid. Knowing which to reach for saves confusion.

Plug

Section titled “Plug”

grid plug puts a node on the grid. It reads the cloudgrid.yaml and .cloudgrid/link.json in the current directory, uploads your source, builds a container, deploys it, and prints the live URL. If the entity is already live, plug updates it in place — same entity, same URL.

Terminal window
grid plug                     # deploy the current directory
grid plug ./deck.pdf          # publish a single file as an inspiration
grid plug --detach            # queue the build and return immediately
grid plug --existing abc123   # bind this folder to an existing entity, then deploy

Pickup

Section titled “Pickup”

grid pickup creates a new, independent copy of an entity in your grid — like a git fork. The copy has its own identity and URL, with permanent lineage back to the original. Changes to one do not affect the other. The copy is minted without the source’s secrets (set your own before you plug).

Terminal window
grid pickup cool-tool
grid pickup cool-tool --name my-cool-tool

Pull

Section titled “Pull”

grid pull downloads an existing entity’s source into a local folder and links that folder to the entity, so a following grid plug updates the same entity in place. Requires push access: you must already own the entity or already be a collaborator on it. Pull continues an entity you can push to; it does not grant that access. If you can only view an entity, get push access first with a collab (see below), then pull.

Terminal window
grid pull my-app                   # download into ./my-app and link
grid pull org/my-app ./work        # into a custom directory

Collab

Section titled “Collab”

Collab is the access step, and it is distinct from both pull and pickup. It gets you push access to the same live entity that someone else owns: you become a collaborator on that entity, not the holder of a copy. It grants permission only and downloads nothing, so once access is granted you run grid pull to fetch the code, and your next grid plug updates the shared entity for the whole team.

Terminal window
grid collab my-app            # ask to collaborate on an entity you can see
grid collab requests          # owner: list who has asked to join
grid collab approve <user>    # owner: grant push access
grid collab deny <user>       # owner: refuse the request

If the owner gates who may join, a collab does not dead-end with an error. It becomes a request for access sent to the owner, and once they approve you run grid collab my-app again to join.

From an AI assistant this is the grid_collab tool. Reaching for a pickup when someone asks to collaborate is the classic mistake: a pickup gives you a separate copy, not push access to the shared entity.

Pickup vs pull

Section titled “Pickup vs pull”

The key difference:

  • pickup creates a new entity — your own copy with its own identity, URL, and lineage back to the source.
  • pull works on the same entity you already have push access to (same identity, same URL). Your next grid plug updates it in place and everyone sees the new version. (Getting that access in the first place is a collab.)

Claim

Section titled “Claim”

An entity dropped anonymously (with no sign-in) can be claimed into your account after you sign in — ownership transfers to you and the drop stops expiring on the anonymous schedule.

Terminal window
grid pickup my-drop --claim-token <token>

From an AI assistant, the grid_pull tool handles claiming via its claim_token parameter. (The CLI routes claiming through grid pickup --claim-token; the MCP routes it through grid_pull.) Because ownership transfers and the entity re-homes into your grid, its public URL changes on claim.