Core lifecycle

These commands cover the full create-deploy-manage cycle.

grid new

Scaffold a new app or agent locally — a cloudgrid.yaml plus a starter service. It does not create a server-side entity; the first grid plug mints the entity from the manifest and writes .cloudgrid/link.json.

grid new [slug]

Argument	Description
slug	Name for the project (3–40 chars, lowercase alphanumeric and hyphens). Becomes the URL component. Defaults to the folder name.

Option	Description
--grid <slug>	Override the active grid this project will target.
--type <type>	Seed a web service of this type: node, nextjs, python, or static.
--needs <list>	Pre-declare resources, comma-separated: database, cache, kv, queue, pubsub, vector, ai, disk.
--agent	Scaffold with an agent: block (an app with an agent: block is an agent).
--dir <path>	Target directory. Defaults to the current folder.
--internal	Mark as internal-only (expose: false; not publicly exposed).
--no-agents	Skip the generated AGENTS.md / CLAUDE.md block.
--yes	Non-interactive: accept inferred defaults, no prompts.
--json	Machine-readable output.

Add a service to an existing entity’s cloudgrid.yaml:

grid new service <name> --type <type>

What it creates: cloudgrid.yaml (the service manifest), a starter service under services/<name>/, an AGENTS.md / CLAUDE.md bootstrap block (unless --no-agents), and a .gitignore entry for .cloudgrid/. No server entity and no .cloudgrid/link.json yet — those come from the first grid plug.

grid new my-dashboard
grid new triage-bot --agent
grid new api --type nextjs --needs database,ai

Note

grid init is a deprecated alias of grid new, kept for back-compat. Prefer grid new.

grid plug

Build, deploy, and take the entity live. If it is already live, update it in place.

grid plug [target]

Argument	Description
target	Optional. File or directory to plug. Defaults to the current directory.

Option	Description
--existing <id>	Bind the folder to an existing entity before deploying.
--no-deploy	Register only; the entity stays charged without building.
--detach	Queue the deploy and exit immediately (background build).
--auto	Auto-init from folder detection without prompts.

Behavior: reads cloudgrid.yaml and .cloudgrid/link.json from the current directory, uploads source to the build pipeline, builds a container image, deploys it, and prints the live outlet URL. If no link.json exists, plug can create the entity on the fly (interactively, or with --auto).

grid plug                     # deploy from the current directory
grid plug --detach            # deploy in the background
grid plug --existing abc123   # bind to an existing entity first
grid plug --no-deploy         # register without deploying

grid unplug

Take a node off the grid.

grid unplug [name]

Argument	Description
name	Entity slug or UUID. Defaults to the linked entity in the current directory.

Option	Description
--dark	Power down without removing. Stopped but re-pluggable. No confirmation prompt.
--hard	Archive immediately (skip the 7-day grace period). Requires confirmation.
--skip-confirm	Skip the confirmation prompt.

Modes:

• Default — archive with a 7-day grace period. Data is recoverable during the window.
• --dark — stopped and reversible (“powered down”). Re-plug to bring it back.
• --hard — archived immediately, no grace period.

grid unplug                   # archive the linked entity (7-day grace)
grid unplug my-app --dark     # power down, keep recoverable
grid unplug my-app --hard     # archive immediately

grid status

Show the grid dashboard, an entity’s detail, or a deploy snapshot.

grid status [name-or-trace]

Argument	Description
name-or-trace	Entity slug/UUID for a drill-down, or a trace id (d_...) for a deploy snapshot.

Option	Description
--json	Machine-readable JSON output.
-o, --output <format>	Output format: json, yaml, table, csv.

Modes: no argument gives the grid-wide dashboard; an entity name gives detailed status (state, URL, last deploy, health); a trace id gives a snapshot of a specific deploy.

grid status              # grid dashboard
grid status my-app       # entity detail
grid status d_abc123     # deploy snapshot

grid dev

Run the linked entity locally with grid-injected resources (shared database, cache, secrets, env).

grid dev [service-name] [-- command]

Argument	Description
service-name	Run only this service (for multi-service entities).
-- command	Escape hatch: run an arbitrary command with grid env injected.

Option	Description
--force	Overwrite an existing .cloudgrid-dev.lock file.
--fixed-ports	Refuse ephemeral port fallback (fail if the declared port is taken).
--status	Read-only: show lock-file status without starting services.

Behavior: reads cloudgrid.yaml, starts all declared services, injects shared-service credentials from the grid, manages port allocation, and writes a .cloudgrid-dev.lock for coordination.

grid dev                     # start all services
grid dev web                 # start only the "web" service
grid dev -- npm run custom   # run a custom command with grid env
grid dev --status            # check lock-file status