Insforge Cli

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 @insforge/cli . 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.
• 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 @insforge/cli memory list (cheap, no AI call) and recall any title relevant to the task before designing or debugging. Record decisions and gotchas with memory remember at the moment they happen. See references/memory.md.

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. |

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 @insforge/cli current. Use npx @insforge/cli whoami when the authenticated identity matters or when current reports that the CLI is not authenticated.

If not authenticated, run npx @insforge/cli login. If no project is linked, use npx @insforge/cli link for an existing project or npx @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.

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 | | 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) | orgs | this file | | Project backups (list, latest, create, rename, delete, restore) | backups | 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 | ai setup | this file | | Agent memory: project facts, decisions, gotchas 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 |

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 @insforge/cli db migrations new plus a migration SQL file for schema, grants, indexes, triggers, functions, and RLS policy changes.
• Apply migrations with npx @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 @insforge/cli db query for targeted inspection and small corrective row/data SQL only when a migration is not appropriate.
• Use npx @insforge/cli db rpc [--data ] 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 @insforge/cli create - create a new project. Use --json with required flags for non-interactive agent runs. See references/create.md.
• npx @insforge/cli link - link the current directory to an existing project.
• npx @insforge/cli current - show current linked project.
• npx @insforge/cli metadata --json - inspect backend metadata when discovery is needed.

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

• npx @insforge/cli projects get [--project ] - 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 @insforge/cli projects update [--name ] [--domain ] [--storage-size ] [--project ] - rename or change project settings.
• npx @insforge/cli projects restore [--project ] - bring a paused project back online. Only paused projects can be restored.
• npx @insforge/cli projects update-version [--wait] [--project ] - 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 @insforge/cli projects upgrade-instance [--project ] - change the instance class. Valid: nano, micro, small, medium, large, xl (xl is the ceiling). Restarts the project and changes the bill.
• npx @insforge/cli projects delete --project - 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 i

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: InsForge
• Source: InsForge/insforge-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.