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:
CODEBLOCK0
Then verify authentication and project:
CODEBLOCK1
If not authenticated: insforge login
If no project linked: insforge create (new) or insforge link (existing)
Global Options
Flag
Description
INLINECODE4
Structured JSON output (for scripts and agents)
INLINECODE5
Skip confirmation prompts |
Exit Codes
Code
Meaning
0
Success
1
General error (e.g., HTTP 400+ from function invoke) |
| 2 | Not authenticated |
| 3 | Project not linked |
| 4 | Resource not found |
| 5 | Permission denied |
Environment Variables
Variable
Description
INLINECODE6
Override stored access token
INLINECODE7
Override linked project ID |
| INSFORGE_EMAIL | Email for non-interactive login |
| INSFORGE_PASSWORD | Password for non-interactive login |
Commands
Authentication
- insforge login — OAuth (browser) or --email for password login. See references/login.md
INLINECODE18 — 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.
For writing application code with the InsForge SDK, use the insforge (SDK) skill instead, and use the insforge docs <feature> <language> 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
CODEBLOCK2
FK to users: always auth.users(id). RLS current user: auth.uid().
Deploy an edge function
CODEBLOCK3
Deploy frontend
Always verify the local build succeeds before deploying. Local builds are faster to debug and don't waste server resources.
InsForge uses 5-field cron expressions (pg_cron format). 6-field expressions with seconds are NOT supported.
CODEBLOCK7
Expression
Description
INLINECODE102
Every minute
INLINECODE103
Every 5 minutes |
| 0 * * * * | Every hour (at minute 0) |
| 0 9 * * * | Daily at 9:00 AM |
| 0 9 * * 1 | Every Monday at 9:00 AM |
| 0 0 1 * * | First day of every month at midnight |
| 30 14 * * 1-5 | Weekdays at 2:30 PM |
Secret References in Headers
Headers can reference secrets stored in InsForge using the syntax ${{secrets.KEY_NAME}}.
CODEBLOCK8
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
2. 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
3. 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 INLINECODE113
4. Monitor execution logs
- Check logs regularly to ensure schedules are running successfully
- Look for non-200 status codes and failed executions
Common Mistakes
Mistake
Solution
Using 6-field cron (with seconds)
Use 5-field format only: INLINECODE114
Referencing non-existent secret
Create the secret first via secrets API |
| Targeting non-existent function | Verify function exists and is active before scheduling |
| Schedule not running | Check isActive is true and cron expression is valid |
Recommended Workflow
CODEBLOCK9
Debug with logs
CODEBLOCK10
Best Practices
1. Start with function.logs for function issues
- Check execution errors, timeouts, and runtime exceptions
bash
insforge db query CREATE TABLE posts (
id UUID DEFAULT genrandomuuid() 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 \ownerwrite\ ON posts FOR INSERT WITH CHECK (auth.uid() = authorid)
Initial release of insforge-cli — a command-line tool for InsForge backend infrastructure management.
- Supports authentication, project management, database queries and schema management, edge/serverless functions, storage buckets, frontend deployments, secrets management, scheduled tasks (cron jobs), and backend logs.
- Provides structured command outputs, comprehensive environment variable overrides, and detailed exit codes for automation.
- Includes safeguards and notes for destructive actions, soft delete behavior, and invocation URL formats.
- Commands are organized by category and documented with common use cases and workflows.
- Additional documentation available via built-in docs command.
