@cloudgrid-io/cli

The CloudGrid CLI. Put apps, agents, and static files on the grid in one command.

v0.8 is in active development. Pre-release builds publish to the @next dist-tag; v0.7.7 remains the @latest published-stable release until cutover.

Install

npm install -g @cloudgrid-io/cli

# pre-release v0.8 builds
npm install -g @cloudgrid-io/cli@next

Requires Node.js 18+.

Quick start

# Authenticate (Google OAuth — invite-only)
cloudgrid login

# Create a new app — server-side entity is registered, local files scaffolded
cloudgrid init app my-dashboard
cd my-dashboard

# Put it on the grid — builds server-side, deploys, prints the outlet URL
cloudgrid plug
# → ✓ Live.
# → Outlet: https://my-dashboard.<org>.cloudgrid.io

To run an app locally with grid-injected resources (Mongo, Redis, AI Gateway):

cloudgrid dev

To put a static file (deck, PDF, single-file React) on the grid as an inspiration:

cloudgrid plug ./deck.pptx

The five core verbs

| Verb | What it does | |---|---| | cloudgrid init <kind> <name> | Create a new entity on the grid as 'charged', scaffold local files. <kind> is app or agent. | | cloudgrid plug | Put the linked node on the grid (build + deploy + go live), or update if already there. Pass a file path to plug an inspiration. | | cloudgrid unplug | Take the node off the grid. --dark powers it down without removing. --hard skips the 7-day grace period. | | cloudgrid grid | List what's on your hub. | | cloudgrid dev | Run the linked node locally with grid-injected resources. Requires a linked directory. |

Plus operational verbs (status, logs, info, rollback, pull, ssh, wire repo, env, secrets) and subcommand groups (space, admin, hooks).

Run cloudgrid --help for the full surface.

Authentication

cloudgrid login

Opens a browser-based device flow against https://api.cloudgrid.io. The JWT is stored in ~/.cloudgrid/credentials with mode 0600.

If you belong to multiple orgs, set the active one with cloudgrid switch <slug>. Show your current state with cloudgrid whoami.

Linked directories

Every directory the CLI knows as a CloudGrid node carries a single gitignored file at .cloudgrid/link.json. It records the entity_id, org_id, and realm/kind of the bound entity. The CLI auto-adds .cloudgrid/ to .gitignore.

A fresh clone of an existing project starts unlinked. To re-bind:

cloudgrid plug --existing <entity-id>

CI / non-interactive use

Three environment variables stand in for .cloudgrid/link.json in CI:

- run: cloudgrid plug
  env:
    CLOUDGRID_TOKEN: ${{ secrets.CLOUDGRID_TOKEN }}
    CLOUDGRID_ORG_ID: o_abc123
    CLOUDGRID_ENTITY_ID: e_7f3a8b2c

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 init, plug, dev, login after a clean completion. Captures the verb and elapsed time. No payload from the source tree.
• feedback — only when you run cloudgrid feedback "<message>".

Every event is JWT-bound (your user id), times out at 250ms, 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.

See decision 016 for the full payload contract.

Disabling telemetry

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

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

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

More

• Full CLI spec: docs/strategy/cli-ux-spec-v17.md
• Platform overview and cloudgrid.yaml reference: root README
• AI Gateway SDK: @cloudgrid-io/ai