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

Exit Codes

Environment Variables

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