CloudGrid CLI

Build, ship, and run apps and agents on CloudGrid from your terminal. A directory or a URL becomes a live, addressable thing in about 30 seconds — deploy, tail logs, share, read feedback, all without leaving your shell.

The command is grid.

Contents

• Install
• Quickstart
• Examples
• Commands
• Flags
• Environment
• Telemetry
• Updating
• Uninstall
• Troubleshooting
• Support
• License

Install

macOS / Linux — curl

curl -fsSL https://raw.githubusercontent.com/cloudgrid-io/cli/main/install.sh | sh

macOS / Linux — Homebrew

brew install cloudgrid-io/tap/grid

Cross-platform (incl. Windows) — npm

npm install -g @cloudgrid-io/cli

Requires Node.js 22+.

Node 22 is what CloudGrid builds and tests on — every Dockerfile in the platform is node:22, and every CI job runs node-version: 22. The floor names that rather than sitting below it. Node 18 left maintenance in April 2025 and Node 20 in April 2026; neither receives security patches.

On an older Node, npm install -g @cloudgrid-io/cli prints an EBADENGINE warning and installs anyway — npm only refuses when you have set engine-strict=true. The install appearing to succeed is not a signal the CLI will run. Install Node 22 or later.

Verify: grid --version and grid doctor.

The package installs a single command, grid. The older cloudgrid, gridctl and cg names are retired and are not installed.

Quickstart

grid login          # Google OAuth in the browser
grid whoami         # confirm user + active grid
grid plug           # build + deploy the current directory, prints the live URL
grid open           # open it in the browser

No account needed to try a one-off share: grid plug ./index.html drops a public link.

Examples

# Scaffold and deploy a Node app
grid new app my-api --type node
cd my-api && grid plug

# Deploy the current directory and tail its logs
grid plug
grid logs --since 10m

# Publish beyond the grid as an unlisted link, then read feedback
grid visibility set my-api --inside grid --outside link
grid feedback

# Switch grid, list what's on it
grid use atomic
grid get entities

Commands

Visibility is two axes — --inside is who in the grid is an audience (private | spaces | grid), --outside is reach beyond it (none | link | public).

Run grid <command> --help for the full flag set of any command, and grid --help for the complete list.

Flags

Global:

• -V, --version — print the CLI version
• -v, --verbose — detailed output
• -h, --help — help for any command

Common per-command:

• --grid <slug> — pick/override the grid
• --json / -o <format> — machine-readable output (table | json | yaml | wide)
• --no-clipboard / --no-notify — suppress clipboard copy / OS notification on plug
• --since <dur> / --tail <n> — logs window

Environment

• CLOUDGRID_GRID — the active grid for this shell only. Accepts a slug or a grid id, and overrides ~/.cloudgrid/config.yaml without changing it.
• CLOUDGRID_HOME — where config and credentials live (default ~/.cloudgrid).
• CLOUDGRID_TOKEN — authenticate non-interactively instead of grid login.
• CLOUDGRID_TELEMETRY — see Telemetry.

grid use writes to one file in your home directory, so it applies to every shell on the machine — including other terminals and any agent session running in parallel. When two shells need different grids, set CLOUDGRID_GRID rather than running grid use in each:

# This shell targets acme; every other shell keeps whatever `grid use` set.
export CLOUDGRID_GRID=acme
grid plug

# Or for a single command, without exporting anything:
CLOUDGRID_GRID=acme grid plug

Precedence, highest first: --grid → CLOUDGRID_GRID → grid use.

Scripts that need a specific grid should use CLOUDGRID_GRID or --grid. A script that calls grid use repoints the grid for everything else you have open, and does not put it back.

Telemetry

The CLI sends three event types to the CloudGrid API while the platform is in pre-release:

• error — when a verb fails. Captures the v2 error code, HTTP status, request id, and the bare verb (no flags, no positional args).
• success — on new, plug, dev, login after a clean completion. Captures the verb and elapsed time. No payload from the source tree.
• feedback — only when you run grid feedback "<message>".

Every event is JWT-bound (your user id), times out at 250 ms, and never blocks the verb. File paths, command flags, env-var values, JWTs, and credentials are not collected. The feedback verb's --include-log flag is the only freeform path — it ships the scrubbed last 200 lines of ~/.cloudgrid/logs/cli.log.

Disabling telemetry

# One-shot, env var (highest priority — overrides config):
CLOUDGRID_TELEMETRY=0 grid plug

# Persistent, written to ~/.cloudgrid/config.yaml:
grid login --no-telemetry

Re-enable with CLOUDGRID_TELEMETRY=1 or by removing telemetry: false from your config file.

Updating

npm update -g @cloudgrid-io/cli      # npm
brew upgrade grid                    # homebrew

grid doctor warns when a newer version is available.

Uninstall

npm uninstall -g @cloudgrid-io/cli   # npm
brew uninstall grid                  # homebrew
rm -rf ~/.cloudgrid                  # remove stored credentials + config

Troubleshooting

• grid: command not found — ensure the npm global bin (or Homebrew bin) is on $PATH; re-run the installer.
• Auth errors / 401 — grid login again; check grid whoami shows the expected grid, switch with grid use <slug>.
• Deploy fails — run grid doctor; check grid logs and grid status <name> for the trace.

Support

• Skills + MCP: cloudgrid-io/skills
• Issues: cloudgrid-io/cli/issues

License

MIT. See LICENSE.