Create and manage InsForge projects using the CLI. Handles authentication, project setup, database management, edge functions, storage, deployments, and secrets. For writing application code with the InsForge SDK, use the insforge (SDK) skill instead.
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.
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.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.config apply reports unsupported/skipped fields, surface that result instead of bypassing the CLI with direct API calls.--json when structured output or non-interactive value collection is needed. Use --yes for confirmation prompts when the user has approved the action.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.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.| 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. |
| 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 |
| 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 |
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.
| 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 |
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:
npx -y @insforge/cli db migrations new <name> plus a migration SQL file for schema, grants, indexes, triggers, functions, and RLS policy changes.npx -y @insforge/cli db migrations up --all.npx -y @insforge/cli db query <sql> for targeted inspection and small corrective row/data SQL only when a migration is not appropriate.npx -y @insforge/cli db rpc <fn> [--data <json>] to call database functions through the backend.Public schema scope:
public schema.public application objects.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.auth.users(id) and auth.uid() from public tables or public RLS policies; do not modify those built-in objects.RLS and access control:
auth.uid() or an equivalent authenticated identity expression for user ownership checks.GRANT.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.WITH CHECK for INSERT and UPDATE policies so writes cannot create rows the user should not own.SECURITY DEFINER.public and schema-qualify references such as public.team_members and auth.uid().references/database/access-control.md before writing migrations.Integrity:
references/database/integrity.md before writing migrations.Vector:
references/database/vector.md before writing migrations.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:
npx -y @insforge/cli config export, config plan, and config apply for supported insforge.toml knobs.db migrations; function code belongs in functions deploy; frontend code belongs in deployments deploy; compute code/images belong in compute deploy.config apply returns skipped[], report the skipped items and required backend upgrade. Do not retry with raw HTTP.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.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 toCategory:other