InsForge CLI

Command-line tool for managing InsForge Backend-as-a-Service projects.

Critical: Session Start Checks

First, ensure the CLI is installed. Run insforge whoami — if the command is not found, install it:

npm install -g @insforge/cli

Then verify authentication and project:

insforge whoami    # verify authentication
insforge current   # verify linked project

If not authenticated: insforge login

If no project linked: insforge create (new) or insforge link (existing)

Global Options

Exit Codes

Environment Variables

Commands

Authentication

• insforge login — OAuth (browser) or --email for password login. See references/login.md
• insforge logout — clear stored credentials
• insforge whoami — show current user

Project Management

• insforge create — create new project. See references/create.md
• insforge link — link directory to existing project
• insforge current — show current user + linked project
• insforge list — list all orgs and projects
• insforge metadata — show backend metadata (auth config, database tables, storage buckets, edge functions, AI models, realtime channels). Use --json for structured output. Run this first to discover what's configured before building features.

Database — insforge db

• insforge db query — execute raw SQL. See references/db-query.md
• insforge db tables / indexes / policies / triggers / functions — inspect schema
• insforge db rpc [--data ] — call database function (GET if no data, POST if data)
• insforge db export — export schema/data. See references/db-export.md
• insforge db import — import from SQL file. See references/db-import.md

Edge Functions — insforge functions

• insforge functions list — list deployed functions
• insforge functions code — view function source
• insforge functions deploy — deploy or update. See references/functions-deploy.md
• insforge functions invoke [--data ] [--method GET|POST] — invoke function

Storage — insforge storage

• insforge storage buckets — list buckets
• insforge storage create-bucket [--private] — create bucket (default: public)
• insforge storage delete-bucket — delete bucket and all its objects (destructive)
• insforge storage list-objects [--prefix] [--search] [--limit] [--sort] — list objects
• insforge storage upload --bucket [--key ] — upload file
• insforge storage download --bucket [--output ] — download file

Deployments — insforge deployments

• insforge deployments deploy [dir] — deploy frontend app. See references/deployments-deploy.md
• insforge deployments list — list deployments
• insforge deployments status [--sync] — get deployment status (--sync fetches from Vercel)
• insforge deployments cancel — cancel running deployment

Secrets — insforge secrets

• insforge secrets list [--all] — list secrets (values hidden; --all includes deleted)
• insforge secrets get — get decrypted value
• insforge secrets add [--reserved] [--expires ] — create secret
• insforge secrets update [--value] [--active] [--reserved] [--expires] — update secret
• insforge secrets delete — soft delete (marks inactive; restore with --active true)

Schedules — insforge schedules

• insforge schedules list — list all scheduled tasks (shows ID, name, cron, URL, method, active, next run)
• insforge schedules get — get schedule details
• insforge schedules create --name --cron --url --method [--headers ] [--body ] — create a cron job (5-field cron format only)
• insforge schedules update [--name] [--cron] [--url] [--method] [--headers] [--body] [--active] — update schedule
• insforge schedules delete — delete schedule (with confirmation)
• insforge schedules logs [--limit] [--offset] — view execution logs

Logs — insforge logs

• insforge logs [--limit ] — fetch backend container logs (default: 20 entries)

> Source names are case-insensitive: postgrest.logs works the same as postgREST.logs.

Documentation — insforge docs

• insforge docs — list all topics
• insforge docs instructions — setup guide
• insforge docs — feature docs (db / storage / functions / auth / ai / realtime × typescript / swift / kotlin / rest-api)

> For writing application code with the InsForge SDK, use the insforge (SDK) skill instead, and use the insforge docs to get specific SDK documentation.

Non-Obvious Behaviors

Functions invoke URL: invoked at {oss_host}/functions/{slug} — NOT /api/functions/{slug}. Exits with code 1 on HTTP 400+.

Secrets delete is soft: marks the secret inactive, not destroyed. Restore with insforge secrets update KEY --active true. Use --all with secrets list to see inactive ones.

Storage delete-bucket is hard: deletes the bucket and every object inside it permanently.

db rpc uses GET or POST: no --data → GET; with --data → POST.

Schedules use 5-field cron only: minute hour day month day-of-week. 6-field (with seconds) is NOT supported. Headers can reference secrets with ${{secrets.KEY_NAME}}.

Common Workflows

Set up database schema

insforge db query "CREATE TABLE posts (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT,
  author_id UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT now()
)"
insforge db query "ALTER TABLE posts ENABLE ROW LEVEL SECURITY"
insforge db query "CREATE POLICY \"public_read\" ON posts FOR SELECT USING (true)"
insforge db query "CREATE POLICY \"owner_write\" ON posts FOR INSERT WITH CHECK (auth.uid() = author_id)"

> FK to users: always auth.users(id). RLS current user: auth.uid().

Deploy an edge function

# Default source path: insforge/functions/{slug}/index.ts
insforge functions deploy my-handler
insforge functions invoke my-handler --data '{"action": "test"}'

Deploy frontend

Always verify the local build succeeds before deploying. Local builds are faster to debug and don't waste server resources.

# 1. Build locally first
npm run build

# 2. Deploy
insforge deployments deploy ./dist --env '{"VITE_API_URL": "https://my-app.us-east.insforge.app"}'

Environment variable prefix by framework:

Pre-deploy checklist:

• [ ] npm run build succeeds locally
• [ ] All required env vars configured with correct framework prefix
• [ ] Edge function directories excluded from frontend build (if applicable)
• [ ] Never include node_modules, .git, .env, .insforge, or build output in the zip
• [ ] Build output directory matches framework's expected output (dist/, build/, .next/, etc.)

Backup and restore database

insforge db export --output backup.sql
insforge db import backup.sql

Schedule a cron job

# Create a schedule that calls a function every 5 minutes
insforge schedules create \
  --name "Cleanup Expired" \
  --cron "*/5 * * * *" \
  --url "https://my-app.us-east.insforge.app/functions/cleanup" \
  --method POST \
  --headers '{"Authorization": "Bearer ${{secrets.API_TOKEN}}"}'

# Check execution history
insforge schedules logs <id>

Cron Expression Format

InsForge uses 5-field cron expressions (pg_cron format). 6-field expressions with seconds are NOT supported.

┌─────────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌─────────── day of month (1-31)
│ │ │ ┌───────── month (1-12)
│ │ │ │ ┌─────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Secret References in Headers

Headers can reference secrets stored in InsForge using the syntax ${{secrets.KEY_NAME}}.

{
  "headers": {
    "Authorization": "Bearer ${{secrets.API_TOKEN}}",
    "X-API-Key": "${{secrets.EXTERNAL_API_KEY}}"
  }
}

Secrets are resolved at schedule creation/update time. If a referenced secret doesn't exist, the operation fails with a 404 error.

Best Practices

1. Use 5-field cron expressions only
• pg_cron does not support seconds (6-field format)
• Example: /5 * for every 5 minutes

1. Store sensitive values as secrets
• Use ${{secrets.KEY_NAME}} in headers for API keys and tokens
• Create secrets first via the secrets API before referencing them

1. Target InsForge functions for serverless tasks
• Use the function URL format: https://your-project.region.insforge.app/functions/{slug}
• Ensure the target function exists and has status: "active"

1. Monitor execution logs
• Check logs regularly to ensure schedules are running successfully
• Look for non-200 status codes and failed executions

Common Mistakes

Recommended Workflow

1. Create secrets if needed     -> `insforge secrets add KEY VALUE`
2. Create/verify target function -> `insforge functions list`
3. Create schedule              -> `insforge schedules create`
4. Verify schedule is active    -> `insforge schedules get <id>`
5. Monitor execution logs       -> `insforge schedules logs <id>`

Debug with logs

insforge logs function.logs          # function execution issues
insforge logs postgres.logs          # database query problems
insforge logs insforge.logs          # API / auth errors
insforge logs postgrest.logs --limit 50

Best Practices

1. Start with function.logs for function issues
• Check execution errors, timeouts, and runtime exceptions

1. Use postgres.logs for query problems
• Debug slow queries, constraint violations, connection issues

1. Check insforge.logs for API errors
• Authentication failures, request validation, general backend errors

Common Debugging Scenarios

Non-interactive CI/CD

INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD insforge login --email -y
insforge link --project-id $PROJECT_ID --org-id $ORG_ID -y
insforge db query "SELECT count(*) FROM users" --json

Project Configuration

After create or link, .insforge/project.json is created:

{
  "project_id": "...",
  "appkey": "...",
  "region": "us-east",
  "api_key": "ik_...",
  "oss_host": "https://{appkey}.{region}.insforge.app"
}

oss_host is the base URL for all SDK and API operations. api_key is the admin key for backend API calls.

> Never commit this file to version control or share it publicly.

> Do not edit this file manually. Use insforge link to switch projects.