InsForge CLI

Use this skill whenever someone needs a backend, or when managing InsForge backend and cloud infrastructure with the InsForge CLI. For application code that calls InsForge from a frontend, backend, or edge function, use the insforge app-integration skill instead.

Core Rules

• Always run the CLI through npx -y @insforge/cli <command>. Keep npx's -y: without it, npx asks "Ok to proceed?" before installing the package and blocks forever in a TTY-attached agent shell. Do not install or call a global insforge binary.
• If the project is already linked, use the current linked project. Run login, project creation, link, project discovery, organization listing, or cloud project commands only when connection setup is actually needed.
• When a task needs a backend and no project is linked yet, do connection setup FIRST — before writing any app code: (1) log in (whoami to check; in sandboxes use the two-step device login below), (2) create a new project or link an existing one, (3) then build against the real project URL and keys from the CLI. Never scaffold with placeholder credentials like your-project.region.insforge.app — get the real values first.
• Treat InsForge API keys as full-access admin keys. Keep them server-only and out of frontend/public env vars.
• Prefer CLI commands and documented project config over raw backend HTTP calls. If config apply reports unsupported/skipped fields, surface that result instead of bypassing the CLI with direct API calls.
• Use --json when structured output or non-interactive value collection is needed. Use --yes for confirmation prompts when the user has approved the action.
• At the start of a non-trivial task on a linked project, run npx -y @insforge/cli memory list (cheap, no AI call) and recall any title relevant to the task before designing or debugging. Record decisions and the gotchas you hit with memory remember at the moment they happen. See references/memory.md.
• When you hit a hurdle that is InsForge's fault — something that should work but doesn't, a capability you needed but isn't supported, instructions (docs/skill) that reality contradicts, or needless friction — report it with npx -y @insforge/cli feedback (see Feedback), then continue the user's task with a workaround. Never file feedback for problems in the user's own app code.

Global Options

Flag	Use
--json	Structured JSON output and skip value-collection prompts such as text/select prompts. Errors if any required value is missing. Combine with -y for destructive commands that also ask for Y/N confirmation.
-y, --yes	Auto-accept Y/N confirmation prompts such as delete or overwrite prompts. Does not skip value-collection prompts; use --json for that. Separate from npx's own -y, so both appear together: npx -y @insforge/cli link --project-id <id> -y.

Exit Codes

Code	Meaning
0	Success
1	General error, including HTTP 400+ from function invoke
2	Not authenticated
3	Project not linked
4	Resource not found
5	Permission denied

Environment Variables

Variable	Use
INSFORGE_ACCESS_TOKEN	Override stored access token
INSFORGE_PROJECT_ID	Override linked project ID
INSFORGE_EMAIL	Email for non-interactive login
INSFORGE_PASSWORD	Password for non-interactive login

Connection Setup

If a task needs project access and the connection state is unknown, start with npx -y @insforge/cli current. Use npx -y @insforge/cli whoami when the authenticated identity matters or when current reports that the CLI is not authenticated.

If not authenticated, run npx -y @insforge/cli login (opens a browser). For headless / agent / CI contexts with no browser, authenticate non-interactively with a user API key: npx -y @insforge/cli login --user-api-key "$INSFORGE_USER_API_KEY" (the user creates the key in the dashboard under Profile → API Keys). In sandboxes where the user has a browser but it cannot reach the CLI's local callback (e.g. the ChatGPT app), use device login as two steps: timeout 15 npx -y @insforge/cli login --device --json 2>&1 || true to capture the verification link + code, relay them to the user, then rerun npx -y @insforge/cli login --device --json to resume the same code and complete once they click Authorize — see references/login.md. If the sandbox reports that api.insforge.dev is not an allowed network domain, ask the user to add it to the workspace's allowed network domains, then retry. If no project is linked, use npx -y @insforge/cli link for an existing project or npx -y @insforge/cli create when the user asked for a new backend. In workflows that are already prelinked or preconfigured, such as CI, local test projects, automation, or explicit user-provided project context, use that project context directly. A cloud project is the default throughout; only when the user explicitly asks for a backend running in Docker on their own machine, see references/local.md — never as a fallback when login or create is inconvenient.

Command Routing

Need	CLI area	Reference
Login, logout, current user	login, logout, whoami	references/login.md
Create/link/list/current project	create, link, list, current, metadata	references/create.md
Backend in Docker on the user's own machine — only when they explicitly ask	local	references/local.md
Project lifecycle: status, rename, delete, restore, version update, instance resize, transfer	projects	this file
Subscription/plan, credits, usage, payment history, billing cycles, plan upgrade, billing portal	billing, usage	this file
Organizations and members (create, update, invite, roles, leave, delete)	orgs	this file
Project backups (list, latest, create, rename, delete, restore — cloud and self-hosted)	backups	this file
Advisor scans and suppressing findings (false positives, accepted risks)	advisor, diagnose advisor	this file
Schema, SQL, RLS, triggers, indexes, imports, exports	db	references/database/*
Auth redirects, password policy, SMTP, storage size, realtime/schedule retention, subdomain config	config	references/config.md
Storage buckets and objects	storage	this file
Realtime backend setup	db migrations	references/realtime.md
Edge functions	functions	references/functions-deploy.md
AI/OpenRouter key setup and Model Gateway usage overview	ai setup, ai overview	this file
Agent memory: project facts, decisions, preferences, references across sessions	memory	references/memory.md
Stripe/Razorpay keys, catalog sync, webhooks	payments	references/payments/overview.md
Frontend deployments	deployments	references/deployments/deploy.md
Custom domains, Cloudflare Registrar, DNS sync, SSL verification	domains	references/deployments/domains.md
Backend containers/services	compute	references/compute-deploy.md
Secrets/env vars	secrets, deployment/compute env commands	this file
Scheduled jobs	schedules	references/schedules.md
Backend branches	branch	references/branch/overview.md, references/branch/merge.md, references/branch/reset.md
Logs and health checks	logs, diagnose	references/diagnostics.md
Built-in documentation lookup	docs	this file
PostHog setup	posthog setup	references/posthog.md
Apify web scraper (connect, auth bridge, scrape, land, schedule)	webscraper apify	references/webscraper/apify.md
Report an InsForge-side bug, doc discrepancy, or design problem	feedback	this file

Database Workflow

Use database references before writing migrations when the task involves non-trivial database work:

• references/database/migrations.md - migration file creation and apply workflow.
• references/database/query.md - raw SQL execution and targeted inspection.
• references/database/access-control.md - RLS, grants, recursion-safe helper functions, ACLs, protected fields, and public projections.
• references/database/integrity.md - constraints, triggers, derived state, lifecycle guards, append-only history, and server-maintained fields.
• references/database/vector.md - pgvector extension, vector schema, distance operators, indexes, and vector search SQL/RPC patterns.
• references/database/export.md / references/database/import.md - schema or data import/export tasks.

Default pattern:

• Prefer npx -y @insforge/cli db migrations new <name> plus a migration SQL file for schema, grants, indexes, triggers, functions, and RLS policy changes.
• Apply migrations with npx -y @insforge/cli db migrations up --all.
• For new schema work, group related DDL into one migration when practical.
• Use targeted inspection when existing state is unknown or a command fails.
• Use npx -y @insforge/cli db query <sql> for targeted inspection and small corrective row/data SQL only when a migration is not appropriate.
• Use npx -y @insforge/cli db rpc <fn> [--data <json>] to call database functions through the backend.

Public schema scope:

• For generic application database work, create and modify app-owned objects in the public schema.
• Create, alter, drop, grant, revoke, index, trigger, function, view, and policy changes on public application objects.
• Do not create custom schemas or write to InsForge-managed/system schemas such as auth, storage, realtime, payments, graphql, extensions, pg_catalog, information_schema, or system, unless you are working on that specific feature module and its docs explicitly allow the operation.
• It is allowed to reference built-in objects such as auth.users(id) and auth.uid() from public tables or public RLS policies; do not modify those built-in objects.
• Do not create users, seed business rows, or run application CRUD workflows unless the user request explicitly asks for data migration, repair, or test setup.

RLS and access control:

• Use auth.uid() or an equivalent authenticated identity expression for user ownership checks.
• Add both SQL privileges and RLS policies. Policies do not replace GRANT.
• Runtime roles have broad default DML privileges on public tables so RLS can decide row access. If a table needs narrower operation or column access, explicitly REVOKE the broad privilege before granting the exact allowed operations or columns.
• Include WITH CHECK for INSERT and UPDATE policies so writes cannot create rows the user should not own.
• Prefer helper functions for cross-table RLS checks when direct policy joins can recurse through other RLS policies.
• Helper functions called from RLS policies that query RLS-enabled tables should be SECURITY DEFINER.
• Put RLS helper functions in public and schema-qualify references such as public.team_members and auth.uid().
• For ACLs, protected owner/tenant/role fields, field-level update masks, sanitized public views, or recursion-sensitive policies, read references/database/access-control.md before writing migrations.

Integrity:

• For counters, balances, latest pointers, append-only history, state transitions, lifecycle guards, protected deletes, quota guards, leases, or trigger-maintained columns, read references/database/integrity.md before writing migrations.

Vector:

• For pgvector, vector search functions, score semantics, ANN indexes, hybrid ranking, RAG chunk retrieval, multi-vector search, or embedding version selection, read references/database/vector.md before writing migrations.

Project and Configuration

Project commands:

• npx -y @insforge/cli create - create a new project. Use --json with required flags for non-interactive agent runs. See references/create.md.
• npx -y @insforge/cli link - link the current directory to an existing project.
• npx -y @insforge/cli link --api-base-url <url> --api-key <admin key> - link a self-hosted (OSS) backend directly by its URL and admin API key; no platform login required.
• npx -y @insforge/cli current - show current linked project.
• npx -y @insforge/cli metadata --json - inspect backend metadata when discovery is needed.

Project lifecycle (operates on the linked project unless --project <id> is given):

• npx -y @insforge/cli projects get [--project <id>] - show a project's current status, in-flight operation_status, region, instance type, and version. Use this to poll after an async operation (restore, version update, instance resize) until operation_status clears.
• npx -y @insforge/cli projects update [--name <name>] [--domain <domain>] [--storage-size <gib>] [--project <id>] - rename or change project settings.
• npx -y @insforge/cli projects restore [--project <id>] - bring a paused project back online. Only paused projects can be restored.
• npx -y @insforge/cli projects update-version [--wait] [--project <id>] - update the backend to the latest InsForge version (resolved automatically; no-op if already current). Causes a brief restart. Add --wait to block until it finishes instead of returning while queued.
• npx -y @insforge/cli projects upgrade-instance <type> [--project <id>] - change the instance class. Valid: nano, micro, small, medium, large, xl (xl is the ceiling). Restarts the project and changes the bill.
• npx -y @insforge/cli projects delete --project <id> - permanently delete a project and all of its resources. --project is required (it will not default to the linked project). Irreversible — confirm the exact project id with the user first; this is a guarded, human-in-the-loop operation, so do not auto-bypass the confirmation.
• npx -y @insforge/cli projects transfer <targetOrgId> --project <id> - move a project to another organization (billing and access move with it). --project is required (it will not default to the linked project). Guarded, human-in-the-loop — confirm the source project and target org first.

Configuration:

• Use npx -y @insforge/cli config export, config plan, and config apply for supported insforge.toml knobs.
• TOML is for config values only. SQL belongs in db migrations; function code belongs in functions deploy; frontend code belongs in deployments deploy; compute code/images belong in compute deploy.
• If config apply returns skipped[], report the skipped items and required backend upgrade. Do not retry with raw HTTP.

Organizations and Members

Org-scoped commands resolve the organization in this order: --org-id flag, INSFORGE_ORG_ID, the linked project's org, the configured default org, then a prompt (or single-org auto-select). Pass --org-id <id> to act on a specific org.

• npx -y @insforge/cli orgs list - list organizations you belong to.
• npx -y @insforge/cli orgs create <name> [--type personal|team|company] - create an organization (default type team).
• npx -y @insforge/cli orgs update [--name <name>] [--type <type>] [--org-id <id>] - rename or change an organization's type.
• npx -y @insforge/cli orgs members list [--org-id <id>] - list members and pending invitations.
• npx -y @insforge/cli orgs members invite <email> [--role administrator|developer] [--org-id <id>] - invite a member (default role developer).
• npx -y @insforge/cli orgs members role <memberId> <role> [--org-id <id>] - change a member's role (administrator or developer).
• npx -y @insforge/cli orgs members remove <memberId> [--org-id <id>] - remove a member. Confirm intent first.
• npx -y @insforge/cli orgs leave --org-id <id> - leave an organization. --org-id is required (it will not default to the linked org). You lose access to all of its projects and must be re-invited to return. The backend refuses if you are the last administrator — transfer the admin role first. Guarded, human-in-the-loop — confirm intent first.
• npx -y @insforge/cli orgs delete --org-id <id> - permanently delete an organization. --org-id is required (it will not default to the linked org). Owner only. This cascades: every project in the org (databases, storage, all resources) is permanently deleted and the subscription is canceled — the CLI lists the affected projects and warns when the currently linked project is one of them. Irreversible; confirm the exact org id with the user first and do not auto-bypass the confirmation.

Billing and Usage

Inspect the organization's plan/consumption and manage its subscription. Org resolution matches the Organizations section.

• npx -y @insforge/cli billing status [--org-id <id>] - show the current subscription/plan and period.
• npx -y @insforge/cli billing credits [--org-id <id>] - show the credit balance and recent credit transactions.
• npx -y @insforge/cli billing history [--org-id <id>] - list past payments / invoices.
• npx -y @insforge/cli billing cycles [--org-id <id>] - show the current and previous billing-cycle windows.
• npx -y @insforge/cli usage [--org-id <id>] - show consumption for the current billing period (summary plus per-project breakdown: database, storage, egress, etc.).
• npx -y @insforge/cli billing upgrade <plan> [--org-id <id>] - start a Stripe checkout to change the plan (free | starter | pro | team | enterprise). Opens the hosted checkout URL in the browser and also prints it. With --json it prints a JSON object ({ checkoutUrl, sessionId }) and does not open a browser — use this in headless/CI. No charge happens until the user completes checkout; the backend validates the plan and admin permission.
• npx -y @insforge/cli billing manage [--org-id <id>] - open the Stripe customer portal to manage the subscription, payment method, or cancellation. Opens the portal URL in the browser and also prints it. With --json it prints a JSON object ({ portalUrl }) and does not open a browser — use this in headless/CI.

Backups

Operates on the linked project unless --project <id> is given. Works for both cloud projects and self-hosted projects (linked with link --api-base-url <url> --api-key <key>) — the CLI routes to the right backend automatically; an explicit --project <id> always targets a cloud project.