CLI harness

The @insforge/cli is the agent’s hands: one terminal interface with JSON output for schema, config, deploys, and diagnostics across your InsForge project.

The @insforge/cli is the interface a coding agent uses to operate your backend. Where a human reaches for the dashboard, the agent reaches for the terminal: it runs a command, reads the output, and decides what to do next. Every command speaks --json, so the agent works from structured data instead of scraping a screen.

Run the CLI with npx @insforge/cli. Do not install it globally, so the agent always uses the version pinned to the project.

Why a CLI for agents

A dashboard is built for a human pointer; a CLI is built for anything that can write text. Pass --json to any command and the agent gets a structured result it can parse; pass --yes and it runs without stopping for a confirmation prompt. Schema, auth config, storage, functions, deploys, branches, and diagnostics are all subcommands of the same tool, so there is one surface to learn instead of a dashboard to navigate. It runs in any terminal, any editor, or CI, with no integration to set up. And after a change, the agent can run npx @insforge/cli diagnose and read back exactly what broke.

Command surface

Area	Commands
Auth & context	login, logout, whoami, current, list
Project	create, link, projects update-version, projects delete
Schema	db migrations new, db migrations up, db migrations list
Config as code	config plan, config apply, config export
Branching	branch create, branch merge, branch reset, branch delete
Build	functions, storage, deployments, secrets, schedules, ai
Diagnose	diagnose, diagnose advisor, diagnose db, diagnose logs, metadata

Run npx @insforge/cli help <command> for the flags on any of these.

Built-in secrets

The secrets commands manage the same store your edge functions read from. Every project ships with reserved keys that you can read but not edit or delete:

Key	What it is
ANON_KEY	Public client key, passed as anonKey when you create an SDK client
API_KEY	Admin API key (ik_...) for privileged server-side and CLI access
JWT_SECRET	Secret for HS256-signed JWTs that InsForge accepts, seeded from the deployment’s JWT_SECRET env var
INSFORGE_BASE_URL	The project’s API base URL

npx @insforge/cli secrets list          # every key, values hidden
npx @insforge/cli secrets get ANON_KEY  # decrypted value of one key

Use secrets add, secrets update, and secrets delete for your own keys, and secrets rotate api-key or secrets rotate anon-key to reissue a project key with an optional grace period. The API key and anon key are also in the dashboard: click Install and open API Keys.

Upgrading and deleting a project

npx @insforge/cli projects update-version
npx @insforge/cli projects delete --project <id>

projects update-version moves the project to the latest InsForge backend version. It targets the linked project by default; pass --project <id> to pick another. The command restarts the instance, so expect a brief downtime. Add --wait to block until the update finishes.

projects delete permanently deletes the project: its database, storage, and every other resource, including its backend branches. Here --project is required and never falls back to the linked project, so a stray ambient value can’t point the deletion at the wrong one. Both commands confirm before acting, but only in interactive mode: --yes and --json each skip the prompt, so projects delete --project <id> --json deletes immediately. Deletion is irreversible. Never pass --yes here, and have a human verify the exact project id before the command runs.

To do either from the dashboard instead, both live under Settings → General.

A typical agent run

# connect
npx @insforge/cli login
npx @insforge/cli link

# read current state
npx @insforge/cli --json metadata

# change schema, safely
npx @insforge/cli db migrations new add-orders-table
npx @insforge/cli db migrations up --all

# check the result
npx @insforge/cli diagnose --json

Let the agent interpret the output

Diagnostics ships an AI flag so the agent can hand its own backend data to a model and get back an explanation:

npx @insforge/cli diagnose --ai "why are auth requests failing after the last migration?"

This pairs the raw signals (advisor findings, DB health, error logs) with a plain-language read, which is what turns “here is a stack trace” into “here is the fix.” See Diagnostics & advisor.

Next steps

• Put auth, SMTP, storage, retention, and deployment settings in version control with config as code.
• Test risky changes on a backend branch before touching production.