@insforge/cli

@insforge/cli

Command line tool for the InsForge platform. Manage your databases, edge functions, storage, deployments, payments, secrets, and more — directly from the terminal.

Designed to be both human-friendly (interactive prompts, formatted tables) and agent-friendly (structured JSON output, non-interactive mode, semantic exit codes).

Requires Node.js >= 18. We recommend running via npx so you always get the latest version — no global install needed.

Quick Start

# Login via browser (OAuth)
npx @insforge/cli login

# Or login with email/password
npx @insforge/cli login --email

# Check current user
npx @insforge/cli whoami

# List all organizations and projects
npx @insforge/cli list

# Link current directory to a project
npx @insforge/cli link

# Query the database
npx @insforge/cli db tables
npx @insforge/cli db query "SELECT * FROM users LIMIT 10"

Authentication

If you run any command without being logged in, the CLI will automatically open your browser and start the login flow — no need to run npx @insforge/cli login first.

Browser Login (default)

npx @insforge/cli login

Opens your browser to the InsForge authorization page using OAuth 2.0 Authorization Code + PKCE. A local callback server receives the authorization code and exchanges it for tokens. Credentials are stored in ~/.insforge/credentials.json.

Email/Password Login

npx @insforge/cli login --email

Prompts for email and password interactively, or reads from environment variables in non-interactive mode:

INSFORGE_EMAIL=[e-mail] INSFORGE_PASSWORD=secret npx @insforge/cli login --email --json

Logout

npx @insforge/cli logout

Global Options

All commands support the following flags:

Flag	Description
--json	Output in JSON format (useful for scripts and AI agents)
--project-id <id>	Override the linked project ID
--api-url <url>	Override the Platform API URL
-y, --yes	Skip confirmation prompts

Commands

Top-Level

npx @insforge/cli whoami

Show the current authenticated user.

npx @insforge/cli whoami
npx @insforge/cli whoami --json

npx @insforge/cli list

List all organizations and their projects in a grouped table.

npx @insforge/cli list
npx @insforge/cli list --json

npx @insforge/cli create

Create a new InsForge project interactively.

npx @insforge/cli create
npx @insforge/cli create --name "my-app" --org-id <org-id> --region us-east

npx @insforge/cli link

Link the current directory to an InsForge project. Creates .insforge/project.json with the project ID, API key, and OSS host URL.

# Interactive: select from a list
npx @insforge/cli link

# Non-interactive (platform login)
npx @insforge/cli link --project-id <id> --org-id <org-id>

# OSS / self-hosted: link via host URL + API key (no platform login required)
npx @insforge/cli link \
  --api-base-url https://<app-key>.<region>.insforge.app \
  --api-key <your-project-api-key>

For OSS or self-hosted deployments, you can link directly using the host URL and API key — the CLI skips the platform OAuth flow and writes the credentials straight into .insforge/project.json. The host URL format is https://{app_key}.{region}.insforge.app (e.g. https://uhzx8md3.us-east.insforge.app).

npx @insforge/cli current

Show current CLI context (authenticated user, linked project).

npx @insforge/cli current
npx @insforge/cli current --json

npx @insforge/cli metadata

Show backend metadata including auth configuration, database tables, storage buckets, edge functions, AI models, and realtime channels.

npx @insforge/cli metadata
npx @insforge/cli metadata --json

npx @insforge/cli logs

Fetch backend container logs.

npx @insforge/cli logs <source> [options]

Sources: insforge.logs, postgREST.logs, postgres.logs, function.logs

Options:

• --limit <n>: Number of log entries to return (default: 20)

Examples:

npx @insforge/cli logs insforge.logs
npx @insforge/cli logs postgres.logs --limit 50
npx @insforge/cli logs function.logs --json

npx @insforge/cli docs

Browse InsForge SDK documentation.

npx @insforge/cli docs [feature] [language]

Features: db, storage, functions, auth, ai, realtime, instructions Languages: typescript, swift, kotlin, rest-api

Examples:

# List all available docs
npx @insforge/cli docs

# Specific feature/language docs
npx @insforge/cli docs instructions           # Show backend setup instructions
npx @insforge/cli docs db typescript          # Show TypeScript database SDK docs
npx @insforge/cli docs auth swift             # Show Swift auth SDK docs
npx @insforge/cli docs storage rest-api       # Show REST API storage docs

AI — npx @insforge/cli ai

Configure local development for the InsForge Model Gateway. The setup command fetches the linked project's active OpenRouter key from the InsForge backend and writes it as the server-only OPENROUTER_API_KEY variable.

npx @insforge/cli ai setup
npx @insforge/cli ai setup --env-file .env
npx @insforge/cli ai setup --json

By default the CLI writes .env.local and adds .env*.local to .gitignore when needed. For deployments such as Vercel, add OPENROUTER_API_KEY to the provider's server/runtime environment. Do not rename the key to NEXT_PUBLIC_, VITE_, or PUBLIC_; those prefixes expose values to browser code.

Database — npx @insforge/cli db

npx @insforge/cli db query <sql>

Execute a raw SQL query.

npx @insforge/cli db query "SELECT * FROM users LIMIT 10"
npx @insforge/cli db query "SELECT count(*) FROM orders" --json
npx @insforge/cli db query "SELECT * FROM pg_tables" --unrestricted

npx @insforge/cli db tables

List all database tables.

npx @insforge/cli db tables
npx @insforge/cli db tables --json

npx @insforge/cli db functions

List all database functions.

npx @insforge/cli db functions

npx @insforge/cli db indexes

List all database indexes.

npx @insforge/cli db indexes

npx @insforge/cli db policies

List all RLS policies.

npx @insforge/cli db policies

npx @insforge/cli db triggers

List all database triggers.

npx @insforge/cli db triggers

npx @insforge/cli db rpc <functionName>

Call a database function via RPC.

npx @insforge/cli db rpc my_function --data '{"param1": "value"}'

npx @insforge/cli db export

Export database schema and/or data.

npx @insforge/cli db export --output schema.sql
npx @insforge/cli db export --data-only --output data.sql

npx @insforge/cli db import <file>

Import database from a local SQL file.

npx @insforge/cli db import schema.sql

Functions — npx @insforge/cli functions

npx @insforge/cli functions list

List all edge functions.

npx @insforge/cli functions list
npx @insforge/cli functions list --json

npx @insforge/cli functions code <slug>

View the source code of an edge function.

npx @insforge/cli functions code my-function
npx @insforge/cli functions code my-function --json

npx @insforge/cli functions deploy <slug>

Deploy an edge function. Creates the function if it doesn't exist, or updates it.

npx @insforge/cli functions deploy my-function --file ./handler.ts
npx @insforge/cli functions deploy my-function --file ./handler.ts --name "My Function" --description "Does something"

npx @insforge/cli functions invoke <slug>

Invoke an edge function.

npx @insforge/cli functions invoke my-function --data '{"key": "value"}'
npx @insforge/cli functions invoke my-function --method GET
npx @insforge/cli functions invoke my-function --data '{"key": "value"}' --json

npx @insforge/cli functions delete <slug>

Delete an edge function.

npx @insforge/cli functions delete my-function
npx @insforge/cli functions delete my-function -y  # skip confirmation

Storage — npx @insforge/cli storage

npx @insforge/cli storage buckets

List all storage buckets.

npx @insforge/cli storage buckets
npx @insforge/cli storage buckets --json

npx @insforge/cli storage create-bucket <name>

Create a new storage bucket.

npx @insforge/cli storage create-bucket images
npx @insforge/cli storage create-bucket private-docs --private

npx @insforge/cli storage delete-bucket <name>

Delete a storage bucket and all its objects.

npx @insforge/cli storage delete-bucket images
npx @insforge/cli storage delete-bucket images -y   # skip confirmation

npx @insforge/cli storage list-objects <bucket>

List objects in a storage bucket.

npx @insforge/cli storage list-objects images
npx @insforge/cli storage list-objects images --prefix "avatars/" --limit 50

npx @insforge/cli storage upload <file>

Upload a file to a storage bucket.

npx @insforge/cli storage upload ./photo.png --bucket images
npx @insforge/cli storage upload ./photo.png --bucket images --key "avatars/user-123.png"

npx @insforge/cli storage download <objectKey>

Download a file from a storage bucket.

npx @insforge/cli storage download avatars/user-123.png --bucket images
npx @insforge/cli storage download avatars/user-123.png --bucket images --output ./downloaded.png

Deployments — npx @insforge/cli deployments

npx @insforge/cli deployments deploy [directory]

Deploy a frontend project. Zips the source, uploads it, and polls for build completion (up to 2 minutes).

npx @insforge/cli deployments deploy
npx @insforge/cli deployments deploy ./my-app
npx @insforge/cli deployments deploy --env '{"API_URL": "https://api.example.com"}'

npx @insforge/cli deployments list

List all deployments.

npx @insforge/cli deployments list
npx @insforge/cli deployments list --limit 5 --json

npx @insforge/cli deployments status <id>

Get deployment details and status.

npx @insforge/cli deployments status abc-123
npx @insforge/cli deployments status abc-123 --sync   # sync status from Vercel first

npx @insforge/cli deployments cancel <id>

Cancel a running deployment.

npx @insforge/cli deployments cancel abc-123

Payments — npx @insforge/cli payments

Manage the Stripe payments foundation for the linked InsForge project. These commands are intended for developers and agents configuring Stripe keys, syncing catalog state, inspecting mirrored customers, and managing products/prices. Runtime checkout and customer portal calls should usually be made from the app via the SDK.

npx @insforge/cli payments status

Show Stripe key, account, sync, and webhook status for test/live environments.

npx @insforge/cli payments status
npx @insforge/cli payments status --json

npx @insforge/cli payments config

List, set, or remove Stripe secret keys.

npx @insforge/cli payments config
npx @insforge/cli payments config set test sk_test_xxx
npx @insforge/cli payments config set live        # prompts securely
npx @insforge/cli payments config remove test -y

npx @insforge/cli payments sync

Sync Stripe products, prices, customers, and subscriptions from configured environments.

npx @insforge/cli payments sync
npx @insforge/cli payments sync --environment test
npx @insforge/cli payments sync --environment live --json

npx @insforge/cli payments webhooks configure <environment>

Create or recreate the InsForge-managed Stripe webhook endpoint for an environment.

npx @insforge/cli payments webhooks configure test

npx @insforge/cli payments catalog --environment <environment>

Inspect mirrored Stripe products and prices for one environment.

npx @insforge/cli payments catalog --environment test
npx @insforge/cli payments catalog --environment test --json

npx @insforge/cli payments customers --environment <environment>

List mirrored Stripe customers for admin/debugging workflows.

npx @insforge/cli payments customers --environment test
npx @insforge/cli payments customers --environment test --limit 20 --json

npx @insforge/cli payments products

List, inspect, create, update, or delete Stripe products.

npx @insforge/cli payments products list --environment test
npx @insforge/cli payments products get prod_123 --environment test
npx @insforge/cli payments products create --environment test --name "Pro Plan"
npx @insforge/cli payments products update prod_123 --environment test --description "Updated"
npx @insforge/cli payments products delete prod_123 --environment test -y

npx @insforge/cli payments prices

List, inspect, create, update, or archive Stripe prices.

npx @insforge/cli payments prices list --environment test
npx @insforge/cli payments prices create --environment test --product prod_123 --currency usd --unit-amount 2000
npx @insforge/cli payments prices create --environment test --product prod_123 --currency usd --unit-amount 2000 --interval month
npx @insforge/cli payments prices update price_123 --environment test --active false
npx @insforge/cli payments prices archive price_123 --environment test

npx @insforge/cli payments subscriptions

List mirrored Stripe subscriptions for admin/debugging workflows.

npx @insforge/cli payments subscriptions --environment test
npx @insforge/cli payments subscriptions --environment test --subject-type team --subject-id team_123

npx @insforge/cli payments history

List mirrored payment history for admin/debugging workflows.

npx @insforge/cli payments history --environment test
npx @insforge/cli payments history --environment test --limit 20 --json

Secrets — npx @insforge/cli secrets

npx @insforge/cli secrets list

List all secrets (metadata only, values are hidden). Inactive (deleted) secrets are hidden by default.

npx @insforge/cli secrets list
npx @insforge/cli secrets list --all   # include inactive secrets
npx @insforge/cli secrets list --json

npx @insforge/cli secrets get <key>

Get the decrypted value of a secret.

npx @insforge/cli secrets get STRIPE_API_KEY
npx @insforge/cli secrets get STRIPE_API_KEY --json

npx @insforge/cli secrets add <key> <value>

Create a new secret.

npx @insforge/cli secrets add STRIPE_API_KEY sk_live_xxx
npx @insforge/cli secrets add STRIPE_API_KEY sk_live_xxx --reserved
npx @insforge/cli secrets add TEMP_TOKEN abc123 --expires "2025-12-31T00:00:00Z"

npx @insforge/cli secrets update <key>

Update an existing secret.

npx @insforge/cli secrets update STRIPE_API_KEY --value sk_live_new_xxx
npx @insforge/cli secrets update STRIPE_API_KEY --active false
npx @insforge/cli secrets update STRIPE_API_KEY --reserved true
npx @insforge/cli secrets update STRIPE_API_KEY --expires null   # remove expiration

npx @insforge/cli secrets delete <key>

Delete a secret (soft delete — marks as inactive).

npx @insforge/cli secrets delete STRIPE_API_KEY
npx @insforge/cli secrets delete STRIPE_API_KEY -y   # skip confirmation

Schedules — npx @insforge/cli schedules

Manage scheduled tasks (cron jobs).

npx @insforge/cli schedules list

List all schedules in the current project.

npx @insforge/cli schedules list
npx @insforge/cli schedules list --json

npx @insforge/cli schedules create

Create a new scheduled task.

npx @insforge/cli schedules create --name "daily-cleanup" --cron "0 0 * * *" --url "https://api.example.com/cleanup" --method POST
npx @insforge/cli schedules create --name "hourly-sync" --cron "0 * * * *" --url "https://api.example.com/sync" --method GET --headers '{"Authorization": "Bearer xxx"}'

npx @insforge/cli schedules get <id>

Get details of a specific schedule.

npx @insforge/cli schedules get <id>
npx @insforge/cli schedules get 123 --json

npx @insforge/cli schedules update <id>

Update an existing schedule.

npx @insforge/cli schedules update <id> --name "weekly-cleanup" --cron "0 0 * * 0"
npx @insforge/cli schedules update 123 --active false

npx @insforge/cli schedules delete <id>

Delete a schedule.

npx @insforge/cli schedules delete <id>
npx @insforge/cli schedules delete 123 -y

npx @insforge/cli schedules logs <id>

Fetch execution logs for a specific schedule.

npx @insforge/cli schedules logs <id>
npx @insforge/cli schedules logs 123 --limit 100

Project Configuration

Running npx @insforge/cli link creates a .insforge/ directory in your project:

.insforge/
└── project.json    # project_id, org_id, appkey, region, api_key, oss_host

Add .insforge/ to your .gitignore — it contains your project API key.

Global configuration is stored in ~/.insforge/:

~/.insforge/
├── credentials.json    # access_token, refresh_token, user profile
└── config.json         # default_org_id, platform_api_url

Agent Skills

When you run npx @insforge/cli create or npx @insforge/cli link, the CLI automatically installs a set of InsForge agent skills into your project for all supported AI coding agents (Claude Code, Cursor, Windsurf, Cline, Roo, Gemini CLI, GitHub Copilot, Qwen, Qoder, Trae, Kilo, Codex, Augment, Antigravity). These skills teach your coding agent how to work with InsForge — database queries, auth, storage, edge functions, realtime, etc. — so it can generate correct code for your backend without you copy-pasting docs.

It also installs find-skills so agents can discover available skills on demand.

Skill files are written to per-agent directories (e.g. .claude/, .cursor/, .windsurf/) and are automatically added to your .gitignore. You can re-run npx @insforge/cli link at any time to reinstall or update skills.

For bare agent harnesses that follow the open agents.md standard (a single AGENTS.md at the project root) rather than the per-agent skill directories, the CLI also writes an AGENTS.md into your project. It contains a delimited <!-- INSFORGE:START -->…<!-- INSFORGE:END --> block with InsForge context (where credentials live, when to reach for the SDK vs. the CLI, and a few correctness patterns). If you already have an AGENTS.md, the block is appended once and refreshed in place on subsequent runs, leaving your own content untouched. Unlike the per-agent skill files, AGENTS.md is not gitignored, so you can commit and share it.

Analytics

The CLI reports anonymous usage events to PostHog so we can understand which features are being used and prioritize improvements.

We capture only non-sensitive metadata: the command name, subcommand, outcome (success, applied, aborted, dry_run, no_changes, all_skipped, error), flag shape (e.g. dry_run, json_mode), section names from insforge.toml schema (e.g. auth.smtp), region, and an OSS-vs-cloud flag. We never send SQL, TOML file contents, credentials, environment variable values, or any free text you type.

If you build the CLI from source without setting POSTHOG_API_KEY at build time, analytics become a no-op automatically.

Environment Variables

Variable	Description
INSFORGE_ACCESS_TOKEN	Override the stored access token
INSFORGE_PROJECT_ID	Override the linked project ID
INSFORGE_API_URL	Override the Platform API URL
INSFORGE_EMAIL	Email for non-interactive login
INSFORGE_PASSWORD	Password for non-interactive login

Non-Interactive / CI Usage

All commands support --json for structured output and -y to skip confirmation prompts:

# Login in CI
INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD npx @insforge/cli login --email --json

# Link a project
npx @insforge/cli link --project-id $PROJECT_ID --org-id $ORG_ID -y

# Query and pipe results
npx @insforge/cli db query "SELECT * FROM users" --json | jq '.rows[].email'

# Deploy frontend
npx @insforge/cli deployments deploy ./dist --json

# Upload a build artifact
npx @insforge/cli storage upload ./dist/bundle.js --bucket assets --key "v1.2.0/bundle.js" --json

Exit Codes

Code	Meaning
0	Success
1	General error
2	Authentication failure
3	Project not linked (run npx @insforge/cli link first)
4	Resource not found
5	Permission denied

Development

git clone <repo-url>
cd insforge-CLI
npm install
npm run build
npm link        # makes `insforge` available globally

npm run dev     # watch mode for development

Testing

Unit tests

npm run test:unit

Real project integration tests

Run locally:

INTEGRATION_TEST_ENABLED=true \
INTEGRATION_LOG_SOURCE=insforge.logs \
npm run test:integration:real

Prerequisites:

• Logged in (npx @insforge/cli login) so ~/.insforge/credentials.json exists
• Linked project in this repo (npx @insforge/cli link) so .insforge/project.json exists

Optional environment variables:

• INSFORGE_API_URL: Platform API URL override (defaults to https://api.insforge.dev)
• INTEGRATION_LOG_SOURCE: Log source for logs test (default insforge.logs)

Current real-project checks:

• whoami --json
• metadata --json
• logs <source> --json
• docs instructions --json

Releasing

Bump the version, push the tag, and create a GitHub Release — the CI will publish to npm automatically.

# Bump version (creates commit + tag)
npm version patch   # 0.1.3 → 0.1.4
# or
npm version minor   # 0.1.3 → 0.2.0

# Push commit and tag
git push && git push --tags

Then go to GitHub → Releases → Draft a new release, select the tag (e.g. v0.1.4), and publish. The publish workflow will run npm publish automatically.

License

Apache-2.0