insta-cli

InstaCloud CLI (insta) — a thin client of the platform control-plane API. Manages project / branch / secrets / deploy / governance — built for developers and agents.

Tech stack: Node 20 + TypeScript (ESM) + commander. Every command is a wrapper around the platform API.

Installation

One-line install (native binary, no node required) — macOS / Linux / WSL:

curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh | sh
#   Installs to ~/.insta/bin/insta (override with INSTA_INSTALL_DIR); verifies SHA256SUMS.
#   Pin a version: curl -fsSL .../install.sh | INSTA_VERSION=v0.1.0 sh
# Windows: download insta-windows-x64.exe from the releases page.

Build from source (requires node):

npm install
npm run build         # -> dist/index.js (bin: insta; pure JS, requires node to run)
node dist/index.js --help

Build your own binaries (Bun cross-compilation)

The binaries that install.sh installs are cross-compiled with Bun by CI (tag v* → .github/workflows/release.yml) and published to GitHub releases. You can also build them locally: requires Bun. The npm package still ships JS (dist/index.js) — binaries are a separate distribution channel.

npm run compile            # compile for the current platform only -> dist/bin/insta
npm run build:binaries     # cross-compile all platforms -> dist/bin/insta-<os>-<arch>(.exe) + SHA256SUMS
#   The version (baked into `insta --version`) defaults to package.json, or pass it: bash scripts/build-binaries.sh 1.2.3

Artifacts look like insta-darwin-arm64 / insta-linux-x64 / insta-windows-x64.exe (file reports native Mach-O/ELF/PE executables). dist/ is gitignored; binaries are not committed — CI publishes them to releases.

Quickstart

# Point at the control plane (defaults to http://localhost:8080; override with $INSTA_API_URL or --api-url)
insta login --email [email protected] --password ****** --api-url http://localhost:8080
insta project create my-app          # create an empty project and link the current directory (no services by default)
insta services add postgres db       # add services on demand (postgres/storage/compute)
insta services add compute api       # compute is used to deploy images
insta secrets                        # write the current branch's credentials to ./.env (secret seam)
insta deploy --image <registry/img>  # deploy a container image to the current branch's compute service
insta status                         # login state + linked project/branch

Commands

| Command | Description | |------|------| | insta login [--email --password --api-url] | Log in (email/password; tokens auto-refresh) | | insta login --oauth <github\|google> | Browser OAuth login (starts a local loopback port; the token is carried back automatically after browser authorization) | | insta logout / insta status [--json] | Log out / show status | | insta org list [--json] / org create <name> | Organizations (each user may own only one free org) | | insta project create <name> [--org] | Create an empty project and link it (no services by default) | | insta project list [--org] [--json] / link <id> / delete | Project management | | insta services add <postgres\|storage\|compute> <name> | Provision a service on demand (postgres/compute get a default access domain) | | insta services list [--json] / services remove <type> <name> | List / remove services | | insta services scale compute <name> <number> [region] | Set the compute machine count (paid tiers; rejected on free) | | insta services upgrade <compute\|postgres> <name> <spec> | Upgrade the spec (paid tiers; upgrade only, no downgrade) | | insta branch create <name> [--from] | Create a branch environment (materializes the project's current services; up to 10 branches per project) | | insta branch list [--json] / switch <name> / delete <name> | Branch management | | insta secrets [--branch -o --print --json] | Secret seam: write credentials to .env | | insta secrets list [--branch] | List secret names only | | insta deploy --image <url> [--branch --group --port] | Deploy an image | | insta manifest [--json] | Agent-readable environment manifest | | insta metrics <db\|compute> [group] [--branch --from --to --step --json] | Resource metrics (compute=Fly; db limited) | | insta logs <db\|compute> [group] [--branch --limit --region --instance --json] | Runtime logs (compute=Fly; db limited) | | insta events [--branch --limit --json] | Audit + agent event timeline | | insta usage [--from --to --json] | Resource usage aggregated by meter (includes costUsd) | | insta billing [--org --json] | Current billing-cycle summary (tier / quota / used / overage / status) | | insta billing upgrade <pro\|enterprise> [--org --no-open --json] | Subscribe to a paid tier via Stripe Checkout; returns and opens the payment link | | insta billing portal [--org --no-open --json] | Open the Stripe Customer Portal (change plan / card / cancel) | | insta approvals list [--status] [--json] | Governance approval list | | insta approvals approve <id> [--always] / deny <id> | Approve / deny (admin) | | insta policy get [--json] / policy set <action> <decision> | Governance policy (actions include service.add/remove/scale/upgrade) |

When a governance-gated operation (secrets.read/deploy/project.delete/branch.delete/service.add/service.remove/service.scale/service.upgrade) hits an approval, the CLI prompts approval required — run: insta approvals approve <id>.

Configuration locations

• Global: ~/.insta/config.json (apiUrl + access/refresh token + user)
• Project: ./.insta/project.json (projectId / orgId / current branch)

Local end-to-end run

The platform provides a dev:fake mode (fake provider adapters, no Neon/Fly/Tigris credentials required):

# 1) Start Postgres + the platform dev server (see ../platform)
docker run -d --name pg -e POSTGRES_PASSWORD=insta -e POSTGRES_DB=insta_dev -p 55432:5432 postgres:16-alpine
cd ../platform && DATABASE_URL='postgres://postgres:insta@localhost:55432/insta_dev' PORT=8899 npm run dev:fake

# 2) Run the full flow with the CLI (signup goes through /auth/signup + /auth/verify-email; in dev mode the verification code is printed in the server logs)
INSTA_API_URL=http://localhost:8899 insta login --email [email protected] --password ...

OAuth browser login

insta login --oauth github          # or google
# CLI starts a local loopback port → opens the browser to /auth/cli/authorize → Better Auth runs provider authorization →
# the platform reads the session cookie to exchange for a bearer token → carries it back to the loopback port → CLI stores it as login state

The platform must have an OAuth app configured for that provider (GITHUB_OAUTH_CLIENT_ID/SECRET or GOOGLE_*), and the app's callback URL must be {INSTA_API_BASE_URL}/api/auth/callback/<provider> (not the loopback address).

metrics / logs / usage are supported (usage is aggregated at the collection layer). Multiple compute services (services add compute) and services scale/upgrade are implemented; image building will come later. Multiple postgres/storage services (>1 per project) are currently constrained by the credential seam and remain future work.