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