Pick up an app: make your OWN COPY of any app you can see (like a git fork) into a grid you can build in. It mints a NEW entity with lineage back to the source and WITHOUT the source's secrets (set your own before you plug). Plugging your copy creates/updates YOUR entity — the original is never touched. Requires sign-in. This is a FORK, not a "collab": it never grants you access to anyone else's live entity. Getting PUSH ACCESS to the SAME entity is a different operation — the grid_collab tool (or the CLI grid collab <entity>) — so do NOT reach for grid_pickup when the user asks to collab; reach for grid_collab. To edit the ORIGINAL entity in place (as its owner or a collaborator), use grid_pull instead.

Pull an app to continue/edit it IN PLACE — like git clone of the SAME entity: your next grid_plug (with its target_entity_id) updates that entity, and the team sees the new version. Requires PUSH ACCESS: you must own it or be a collaborator. If you can only view it, you CANNOT edit or plug it — say so, and offer the two real options: (1) make your own separate copy (a fork) with grid_pickup, or (2) GET push access to the SAME entity with grid_collab (or the CLI grid collab <entity>) — "collab" is a distinct access-control operation that grants permission only and fetches nothing, so once it is granted you run grid_pull again to get the code (and if the owner gates access, grid_collab becomes a request they approve). A drop plugged outside any grid is claimed into the grid you choose by passing its claim_token; only the drop's owner can claim it. Requires sign-in. Calls the API directly (both editions).

Collab: GET PUSH ACCESS to the SAME live entity that someone else owns — you become a collaborator on THAT entity, not a copy. This grants PERMISSION ONLY and fetches nothing: after it succeeds, run grid_pull to get the code, then grid_plug (with its target_entity_id) updates the SHARED entity in place (the team sees the new version and can roll it back). This is NOT a fork — it never mints a new entity and never carries forked_from lineage; if you want your OWN separate copy instead, that is grid_pickup. If the owner GATES who may join, this does NOT dead-end: it sends the owner a request for access on your behalf, and once they approve, access is live immediately — no need to re-run grid_collab. Use this — not grid_pickup — whenever the user asks to "collab" on, "join", or "get push/write access to" an app they don't own. Requires sign-in. Calls the API directly (both editions).

Create a new grid (workspace) for the signed-in user — they become its admin. Use when the account has no grid yet (grid_plug returns needs_grid_create, or a plug fails with NO_ACTIVE_ORG): suggest a short slug from the user's name or app, CONFIRM it with the user (the slug is permanent and appears in URLs), create, then call grid_plug with grid: . A brand-new grid provisions in the background (~30s); grid_plug waits for readiness before deploying, so call it right away — no manual delay or polling needed. Never send the user to the console to create a grid by hand. Requires sign-in. Calls the API directly (both editions).

Leave a one-paragraph summary of what you built this session and why, for the local edition's optional QA session log, which the CloudGrid team reads. Call it BEFORE a plug, or in a session that ends without one — a successful plug posts the log on that same call, so pass grid_plug's session_note instead. The log is dark unless the operator of this machine has set CLOUDGRID_QA_SLACK_WEBHOOK.

Plug an app, website, game, or HTML page into CloudGrid at a live public URL. Serves requests to deploy, publish, host, ship, launch, go live, or share a working link: "give me a link", "share it with friends", "make it live", "put it online", "host this". Pass one source: html (a self-contained page) or artifact_files (a multi-file or database-backed runtime app; cloudgrid.yaml declares its needs), or path (local folder, file, or .zip). No target_entity_id (or grid+slug) creates a new URL; with one it updates it in place. To edit a page without its HTML, call grid_get_app_source first, then deploy with target_entity_id. Signed out it returns needs_auth: call grid_login, then re-call; there is no guest publish. needs_grid: ask which grid. needs_grid_create: confirm a slug, then grid_create_grid. Never put an API key in page source. A runtime app returns building: poll grid_check_deploy until live. End with the live URL.

Retrieve the CURRENT deployed HTML of an inspiration/drop inline as text, so you can edit it and re-plug the SAME URL when you no longer have its source in context (e.g. the user asks to 'change the color' of a page — even in a fresh chat with only its URL). Pass the entity_id from the grid_plug result or the public url (or grid+slug); the session's last drop is only a fallback. Given just a URL with no session, it resolves the entity_id via the pickup contract and also returns the entity's kind, single_html, capabilities (replug/fork), and replug_handle — read those to decide whether to edit in place (single-HTML + capabilities.replug), fall back for a multi-file app/agent (use source_download_url + the local edition/CLI), or offer a copy (grid_pickup) when it isn't yours. For a multi-file or runtime (app/agent) source, use source_download_url, or grid_pull to get the files and link the folder. Reads the HTML from the API server-side; read-only, creates nothing.

Start a CLI-free CloudGrid sign-in. Use when the user wants to log in, sign in, or authenticate, or when a plug returned needs_auth. Returns a URL to open in the browser; then call grid_login_status to finish. Uses CloudGrid's existing OAuth.

Finish a sign-in started by grid_login. Polls once: if you have completed the browser sign-in, it saves your session; otherwise it tells you to finish and try again.

Change who can see a CloudGrid inspiration OR runtime app/agent. Simple modes: private (only the user), grid (everyone in their grid), link (anyone with the URL — add indexed: true to be findable by search engines). Finer control via the TWO AXES instead: inside (who in the grid: private | spaces | grid) and outside (reach beyond it: none | link | public), with require_signin for a members-only link and spaces for selected spaces. 'authenticated' is retired (it maps to a sign-in-required link). Use when the user wants to make something private, restrict who sees it, or open it up. Pass the app's entity_id (from the grid_plug result) or its url: some hosts start a new session for every tool call, so the drop made earlier in the conversation is only a fallback. Kind-aware routing across both surfaces. Requires sign-in. Calls the API directly.

Check whether an async runtime-app build (a deploy, which here means a plug) has finished and the app is live. Call this after grid_plug returns status "building" — repeat every ~15s until it reports success or failed, and do NOT tell the user the app is live until it does. Always pass the entity_id from the grid_plug result (or the app url): some hosts start a new session for every tool call, so the session's last plug is not always available. Pass poll_url when the grid_plug result has one. Requires sign-in (builds are owned). Calls the API directly — works on every edition, including hosted.

List the signed-in user's grids, each with slug, name, role, and provisioning status. Requires sign-in. To plug onto a brand-new grid, call grid_plug right away: it waits for the grid to be ready itself, so do not poll render_ready or wait before plugging.

A short orientation for building with CloudGrid: the account this session is signed in as and its active grid, how to choose between a single-page plug and a runtime app (and what each provides: managed database, Redis, pgvector, disk, an AI gateway with no API key), the sign-in and grid steps a first plug goes through, and the index of workflows to load with grid_get_template. Read-only, under 3,000 characters; useful once per session before the first plug. The full operating playbook is grid_get_template({kind:"doc", name:"playbook"}).

Load a specific CloudGrid workflow, template, example, rule, troubleshooting note, or reference doc by name — deterministic retrieval from the bundled corpus, no network. Workflows and templates come from the index grid_start returns, e.g. grid_get_template({kind:"workflow", name:"presentation"}) then grid_get_template({kind:"template", name:"deck"}). Reference docs: cloudgrid-yaml (the manifest schema and needs: vocabulary), capability-map (which template fits a request), playbook (the full operating rules).

Report a genuine CloudGrid failure to the CloudGrid team — ONLY with the user's explicit consent. When a build/deploy or platform call fails unexpectedly, ASK the user first; call this only after they say yes. What is sent: the short message (what failed), the context you pass (the tool, inputs, grid, original request, error code/detail), and the client name and platform — only the message and context the user agreed to send, nothing else from the conversation. Redaction is key-name-only: a value is dropped only when its KEY looks secret, so a secret embedded in a value (e.g. inside HTML) is NOT redacted — do not put secrets in message or context. Never sends anything the user didn't agree to.

Create a minimal hello page and plug it into the user's grid, returning the live URL. If the user has more than one grid and grid is not given, this returns needs_grid with the list — ASK the user which grid, then call again with grid set. Never guess the grid. Requires sign-in.

Scaffold a new CloudGrid app or agent folder (cloudgrid.yaml + a web service), optionally pre-declaring resources. Wraps grid new (scaffolds locally; no server entity until you grid_plug). Language note: the nextjs starter is TypeScript (writes tsconfig.json + app/.tsx), but CloudGrid templates are plain JavaScript. When you fill a template, treat the template's files as the source of truth — delete the scaffolded tsconfig.json and app/.tsx, then write the template's .js files. Never leave both .tsx and .js for the same route.

Tail recent logs for an entity. Does not stream; returns a snapshot. Wraps grid logs.

Set an entity's visibility and print its URL. Defaults to link (anyone with the URL). Wraps grid visibility set.

List recent feedback events for the active grid. Read-only. Wraps grid feedback list.

Show the signed-in user and active grid. Wraps grid whoami.

Switch the active grid. Wraps grid use.

Sign out and clear local credentials. Wraps grid logout.

Grid dashboard, entity detail, or deploy snapshot. Wraps grid status.

Show metadata for a CloudGrid entity. Wraps grid info.

List CloudGrid grids, entities, or spaces. Wraps grid get <grids|entities|spaces> --json.

Show a grid's detail: role, members, spaces, tier, wildcard-TLS state. Wraps grid describe grid <slug> --json.

Continue/edit an EXISTING entity locally: download its source + cloudgrid.yaml and link the folder so your next grid plug updates it IN PLACE. Requires push access (owner or collaborator). Wraps grid pull. To make your own separate copy (a fork) instead, use grid_pickup. To GET push access to an entity you can currently only view, that is a different operation — grid_collab (CLI equivalent: grid collab <entity>), which grants permission only; run the pull again once it is granted.

Rename a CloudGrid entity's display name (slug stays the same). Wraps grid rename.

Take an entity off the grid. Destructive. Wraps grid unplug.

Archive a CloudGrid inspiration. Destructive. Wraps grid delete entity.

Rollback an entity to a previous version. Wraps grid rollback.

List published versions for an entity. Wraps grid versions.

Manage environment variables for an entity. Wraps grid env.

Set or list secret names for an entity. Never returns secret values. Wraps grid secrets.

Scaffold service folders declared in cloudgrid.yaml (idempotent). Wraps grid scaffold.

Run CloudGrid diagnostics on the local environment. Wraps grid doctor.

Return the public URL for an entity. Does not open a browser. Wraps grid open --print.