Skip to content
CloudGrid Docs

Plug, pickup, and fork

Four verbs move code and ownership 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 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. Use it to take over or collaborate on something that already exists on the grid.

Terminal window
grid pickup my-app                 # download into ./my-app and link
grid pickup org/my-app ./work      # into a custom directory
grid pickup my-app --version v_abc # an older version

Fork

Section titled “Fork”

grid fork creates a new, independent entity in your grid — a copy with permanent lineage back to the original. The source and the fork are independent from that point; changes to one do not affect the other.

Terminal window
grid fork cool-tool
grid fork cool-tool --into-org my-grid --name my-cool-tool

Pickup vs fork

Section titled “Pickup vs fork”

The key difference:

  • pickup gives you access to the same entity (same identity, same URL).
  • fork creates a new entity with its own identity and URL, linked back to the source by lineage.

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_claim tool does the same. Because ownership transfers and the entity re-homes into your grid, its public URL changes on claim.

Download

Section titled “Download”

grid download fetches the source bundle from the last deploy without linking the folder or writing a cloudgrid.yaml. Use it when you just want the code.

Terminal window
grid download my-app