InsForge CLI

intent

manage insforge backend-as-a-service projects entirely from the command line. covers auth, project setup, database operations, edge function deployment, file storage, frontend deployments, scheduled tasks, and secret management. use this skill for cli-driven workflows and ci/cd automation. for writing application code that calls insforge services, use the insforge (SDK) skill instead.

inputs

cli tool: insforge CLI installed (npm install -g insforge or local binary)

authentication (one required):

• INSFORGE_ACCESS_TOKEN env var: pre-existing access token (skips login flow)
• browser oauth: insforge login opens browser for interactive auth
• email/password: INSFORGE_EMAIL and INSFORGE_PASSWORD env vars, or insforge login --email flag

project context (one required):

• .insforge/project.json file in working directory (auto-created by create or link)
• INSFORGE_PROJECT_ID env var: override linked project
• org context via INSFORGE_ORG_ID env var (needed for list and multi-project workflows)

external api dependencies (optional, context-specific):

• insforge backend api: requires valid api_key in project.json for admin operations
• edge function target urls: for schedule creation pointing to functions
• external apis: if using schedules with headers referencing secrets

database connection: automatic post-project setup (managed by insforge)

procedure

1. verify session and authentication

inputs: local filesystem, insforge cli

steps:

• run insforge whoami to check current user
• run insforge current to check linked project and org
• examine exit code: 0 = ok, 2 = not authenticated, 3 = project not linked

outputs:

• stdout showing user email, org id, project id (if linked)
• exit code indicating state

decision point: if exit code 2, user not authenticated. if exit code 3, project not linked. see procedure 2 or 3.

2. authenticate if needed

inputs: browser access (for oauth) or email/password credentials (env vars or flags)

steps:

• if no token stored and INSFORGE_ACCESS_TOKEN not set, run insforge login
  • default: opens browser for oauth flow
  • alternative: use --email flag with INSFORGE_EMAIL and INSFORGE_PASSWORD env vars for non-interactive ci/cd
• wait for redirect or success message
• cli stores access token in ~/.insforge/credentials.json

outputs:

• access token stored locally
• stdout: "Logged in as "
• exit code 0 on success

edge cases:

• token expiry: expired tokens trigger re-auth on next command
• mfa enabled: oauth flow handles mfa, password flow does not
• network timeout: retry after 30 seconds
• invalid credentials with --email: exits code 2, error message shown

3. link or create project

inputs: existing project id and org id (for link), or none (for create)

steps for create:

• run insforge create --name <project-name> [--org <org-id>]
• cli prompts for region selection or uses default (us-east)
• .insforge/project.json written to working directory
• default backend resources provisioned (postgres db, basic storage bucket)

steps for link:

• run insforge link [--project-id <id>] [--org-id <id>]
• cli matches local directory to existing insforge project
• .insforge/project.json written with project config

outputs:

• .insforge/project.json containing: project_id, appkey, region, api_key, oss_host
• exit code 0 on success
• stdout: "Project linked" or "Project created"

edge cases:

• project already linked: use insforge link --project-id X to switch
• permission denied on existing project: exit code 5, user lacks access
• org not found: exit code 4, invalid org id

4. manage database schema and data

inputs: .insforge/project.json, sql statements or sql files

steps for query:

• run insforge db query "SELECT * FROM posts" for read operations
• run insforge db query "CREATE TABLE posts (...)" for ddl
• raw sql passed as string argument

steps for inspection:

• run insforge db tables to list all tables
• run insforge db indexes to list indexes
• run insforge db policies to list rls policies
• run insforge db triggers to list triggers
• run insforge db functions to list plpgsql functions

steps for rpc calls:

• run insforge db rpc function_name for parameterless calls (uses get)
• run insforge db rpc function_name --data '{"key":"value"}' for calls with params (uses post)

steps for export:

• run insforge db export --output backup.sql to dump schema and data
• file written to specified path

steps for import:

• run insforge db import backup.sql to restore schema and data
• cli reads sql file and executes statements sequentially

outputs:

• query results: plain text table or --json for structured output
• export: .sql file on disk
• import: no stdout on success, exit code 0
• rpc: response body from function (json if function returns json)

edge cases:

• permission denied: exit code 5, user lacks rls permissions on table
• syntax error: cli echoes postgres error message, exit code 1
• large result set: may timeout or truncate at 10k rows (use pagination in sql)
• export timeout: if db > 100mb, operation may take 5+ minutes
• import failure mid-transaction: cli rolls back, state unchanged

5. deploy and invoke edge functions

inputs: function source code in insforge/functions/{slug}/index.ts, node/typescript runtime

steps for deploy:

• ensure source file exists at insforge/functions/{slug}/index.ts
• run insforge functions deploy slug to package and upload
• cli tails build logs during deploy (2-10 seconds typical)
• function accessible at https://{appkey}.{region}.insforge.app/functions/{slug}

steps for list:

• run insforge functions list to show all deployed functions with status

steps for view source:

• run insforge functions code slug to print function source

steps for invoke:

• run insforge functions invoke slug for parameterless calls (uses get)
• run insforge functions invoke slug --data '{"action":"test"}' for calls with body (uses post)
• run insforge functions invoke slug --method DELETE to override http method

outputs:

• deploy: stdout shows build logs, exit code 0 on success
• list: table with slug, status, runtime, last_deploy_time
• code: source code printed to stdout
• invoke: response body (stdout) or error on http 400+, exit code 1 if http 400+

edge cases:

• function not found: exit code 4
• deploy timeout: if build > 5 minutes, cli cancels and shows error
• invoke on non-existent function: http 404
• invoke http 400+: exits code 1, body shown as error

6. manage file storage buckets and objects

inputs: .insforge/project.json, local files (for upload)

steps for list buckets:

• run insforge storage buckets to show all buckets with region and access level

steps for create bucket:

• run insforge storage create-bucket name [--private] (default: public)
• bucket ready immediately

steps for list objects:

• run insforge storage list-objects bucket-name to list all objects
• use --prefix path/ to filter by prefix
• use --search term to search object keys (substring match)
• use --limit 100 to cap results
• use --sort name|size|modified to order results

steps for upload:

• run insforge storage upload ./file.pdf --bucket my-bucket to upload with auto key
• run insforge storage upload ./file.pdf --bucket my-bucket --key docs/file.pdf to specify key
• file streamed in chunks if > 5mb

steps for download:

• run insforge storage download path/to/object --bucket my-bucket to download to cwd
• run insforge storage download path/to/object --bucket my-bucket --output ./local-file.pdf to save as different name

steps for delete bucket:

• run insforge storage delete-bucket bucket-name to delete bucket and all contents permanently
• requires confirmation unless -y flag used

outputs:

• list buckets: table with name, region, access (public/private)
• list objects: table with key, size, modified_at
• upload: stdout "uploaded to {objectKey}", exit code 0
• download: file written to disk, exit code 0
• delete: stdout "bucket deleted", exit code 0

edge cases:

• bucket not found: exit code 4
• object not found in download: exit code 4
• permission denied (private bucket, no auth): exit code 5
• upload file not found: exit code 4
• delete bucket with 10k+ objects: operation may take 10+ seconds, do not interrupt

7. deploy frontend applications

inputs: built frontend code in directory (e.g., ./dist, ./build, ./.next), .insforge/project.json

steps:

• run npm run build locally to verify build succeeds (do not skip this)
• run insforge deployments deploy ./dist --env '{"VITE_API_URL":"https://..."}' to upload and build on insforge
• cli shows build progress and vercel build logs (takes 1-5 minutes typical)
• deployment assigned url: https://{appkey}-{hash}.{region}.vercel.app

steps for list:

• run insforge deployments list to show all past deployments with status

steps for status:

• run insforge deployments status deployment-id to check current build state
• use --sync flag to fetch latest status from vercel (bypasses cache)

steps for cancel:

• run insforge deployments cancel deployment-id to abort running build (confirmation required unless -y)

outputs:

• deploy: stdout with build logs, exit code 0 on success, deployment url shown
• list: table with id, timestamp, status (building|success|failed), url
• status: state and build logs, exit code 0
• cancel: stdout "deployment cancelled", exit code 0

environment variables by framework:

• vite: prefix VITE_ (e.g., VITE_INSFORGE_URL)
• next.js: prefix NEXT_PUBLIC_ (e.g., NEXT_PUBLIC_INSFORGE_URL)
• create react app: prefix REACT_APP_ (e.g., REACT_APP_INSFORGE_URL)
• astro: prefix PUBLIC_ (e.g., PUBLIC_INSFORGE_URL)
• sveltekit: prefix PUBLIC_ (e.g., PUBLIC_INSFORGE_URL)

edge cases:

• local build fails: fix locally before deploy, do not retry on insforge
• deployment-id not found: exit code 4
• deployment still building: status command returns in-progress state
• cancel on finished deployment: no-op, exit code 0
• env var missing: deployment may fail if frontend code requires it at build time

8. manage scheduled tasks (cron jobs)

inputs: .insforge/project.json, target function url or external api url, 5-field cron expression, optional headers with secret references

steps for list:

• run insforge schedules list to show all schedules with id, name, cron, url, method, active status, next_run_time

steps for get:

• run insforge schedules get schedule-id to show full schedule details including headers and body

steps for create:

• run insforge schedules create --name "Task Name" --cron "*/5 * * * *" --url "https://..." --method POST [--headers '{}'] [--body '{}']
• cron format: 5-field only (minute hour day month day-of-week), 6-field with seconds not supported
• url target must be reachable from insforge (external api or function url)
• headers can reference secrets with syntax ${{secrets.KEY_NAME}}
• schedule active immediately by default

steps for update:

• run insforge schedules update schedule-id --cron "0 9 * * *" [--active true|false] [--url ...] [--method ...] [--headers ...] [--body ...]
• only specified fields updated, others unchanged

steps for delete:

• run insforge schedules delete schedule-id (confirmation required unless -y)
• schedule removed immediately

steps for view logs:

• run insforge schedules logs schedule-id to show execution history (last 20 by default)
• use --limit 50 to show more entries
• use --offset 10 to paginate results
• shows http status, response time, timestamp for each execution

outputs:

• list: table with id, name, cron, url, method, active, next_run
• get: full schedule object in text or --json format
• create: stdout "schedule created", id shown, exit code 0
• update: stdout "schedule updated", exit code 0
• delete: stdout "schedule deleted", exit code 0
• logs: table with timestamp, status, duration_ms, http_status_code

cron expression examples:

• * * * * * every minute
• */5 * * * * 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 month at midnight
• 30 14 * * 1-5 weekdays at 2:30 pm

secret references:

• format: ${{secrets.KEY_NAME}}
• example: --headers '{"Authorization":"Bearer ${{secrets.API_TOKEN}}"}'
• secrets resolved at create/update time, not at execution time
• if secret missing at create time: operation fails with exit code 4

edge cases:

• 6-field cron (with seconds): operation fails, error message explains 5-field required
• referenced secret not found: exit code 4, error message shown
• target url unreachable: schedule still created, but execution fails silently (check logs)
• schedule never runs: verify isActive is true and cron expression valid via get
• execution timeout: http requests must complete within 30 seconds or marked as timeout in logs

9. manage secrets

inputs: .insforge/project.json, secret key and value (string)

steps for list:

• run insforge secrets list to show all active secrets (values hidden)
• use --all to include deleted/inactive secrets

steps for get:

• run insforge secrets get KEY to retrieve decrypted value (stdout, no masking)
• use with caution in ci/cd logs

steps for add:

• run insforge secrets add KEY VALUE to create new secret
• use --reserved flag to mark as reserved (cannot be updated, can be deleted and re-created)
• use --expires "2025-12-31T23:59:59Z" (iso 8601) to set expiry (warning shown when near expiry)

steps for update:

• run insforge secrets update KEY --value NEW_VALUE to change value
• run insforge secrets update KEY --active false to deactivate (soft delete)
• run insforge secrets update KEY --active true to restore deleted secret
• reserved secrets cannot be updated with --value (delete and re-create instead)

steps for delete:

• run insforge secrets delete KEY to soft delete (marks inactive)
• use --all in list to see deleted secrets
• use insforge secrets update KEY --active true to restore

outputs:

• list: table with key, active, created_at, expires_at
• get: plaintext value (stdout)
• add: stdout "secret created", exit code 0
• update: stdout "secret updated", exit code 0
• delete: stdout "secret deleted", exit code 0

edge cases:

• key not found on get: exit code 4
• key already exists on add: exit code 1, use update instead
• value too large (> 64kb): operation fails with exit code 1
• expiry date in past: operation fails, use future date
• reserved secret update: exit code 1, error message explains cannot update reserved

10. retrieve backend logs

inputs: .insforge/project.json, log source name

steps:

• run insforge logs function.logs to view edge function execution logs
• run insforge logs postgres.logs to view database query logs
• run insforge logs insforge.logs to view main backend api logs
• run insforge logs postgrest.logs to view postgrest gateway logs
• use --limit 50 to show more than default 20 entries (max 1000)
• log source names case-insensitive

outputs:

• logs: table with timestamp, level (info|warn|error), message
• exit code 0 on success
• if no logs available: empty output or "no logs" message

edge cases:

• invalid source: exit code 4, shows available sources
• project has no function logs: empty output (function never called)
• log retrieval timeout: retry after 10 seconds
• logs older than 7 days: not available (rotated out)

11. manage project configuration and context

inputs: .insforge/project.json (read-only)

steps for view current:

• run insforge current to display linked project, org, user, and region
• run insforge list to show all projects and orgs the user has access to

steps for logout:

• run insforge logout to delete stored credentials
• user must re-authenticate before next operation

outputs:

• current: text summary with user email, org id, project id, region
• list: table with org_id, org_name, project_id, project_name, region
• logout: stdout "logged out", credentials file deleted

never edit .insforge/project.json manually: use insforge link to switch projects.

edge cases:

• no project linked: current command shows user only, project field empty
• permission error on list: exit code 5, user cannot access that org

decision points

if authentication fails (exit code 2):

• if env vars INSFORGE_EMAIL and INSFORGE_PASSWORD set, issue is credential mismatch. re-check values or retry with insforge login in browser.
• if no env vars, user must run insforge login interactively (requires browser and network access).
• if INSFORGE_ACCESS_TOKEN set, token may be expired. run insforge logout and re-authenticate.

if project not linked (exit code 3):

• if creating new project: run insforge create --name X to initialize.
• if linking existing project: run insforge link --project-id X --org-id Y with existing ids.
• if ids unknown: run insforge list to discover available projects in orgs.

if resource not found (exit code 4):

• verify resource id is correct (typo in name or id).
• run list command for relevant resource type to confirm existence.
• if resource recently deleted, it may not appear immediately (eventual consistency, < 1 minute).

if permission denied (exit code 5):

• user lacks admin role in org or read/write access on specific resource.
• contact org owner or project admin to grant permissions.
• for rls-protected db tables, ensure user satisfies rls policy conditions.

if 6-field cron expression used for schedule:

• operation fails with error message. rewrite cron as 5-field format (pg_cron standard).
• example: 6-field 0 */5 * * * * becomes 5-field */5 * * * *.

if schedule references non-existent secret:

• create secret first via insforge secrets add KEY VALUE.
• then re-run insforge schedules create or update with correct secret reference syntax ${{secrets.KEY_NAME}}.

if frontend deploy fails locally:

• do not retry deploy on insforge. fix build locally first (npm run build).
• common causes: missing env vars with correct framework prefix, missing dependencies, type errors.
• verify build output directory matches framework expectation (dist, build, .next, etc).

if storage bucket not empty and delete is required:

• insforge storage delete-bucket name deletes bucket and all objects atomically. this is permanent.
• no recovery option. if uncertain, use list-objects first to inspect contents.

if db query returns permission denied:

• issue is rls policy, not cli auth. verify current user meets rls policy conditions.
• check policy with insforge db policies to understand allow conditions.
• for insert/update/delete, ensure user id (via auth.uid()) matches required column.

if schedule execution logged as timeout in logs:

• target function or api took > 30 seconds to respond. reduce response time or increase function timeout.
• retry next execution interval to see if issue is transient.

if export operation times out:

• database may be very large (> 100mb). retry with longer timeout or export in smaller batches.
• use insforge db query to export specific tables instead of full schema.

output contract

successful authentication:

• credentials stored in ~/.insforge/credentials.json (unix/mac) or %APPDATA%\insforge\credentials.json (windows)
• subsequent commands use stored token until expiry or logout

successful project link/create:

• .insforge/project.json created in current working directory with schema:

  {
    "project_id": "uuid",
    "appkey": "alphanumeric string",
    "region": "us-east | eu-west | ap-southeast",
    "api_key": "ik_alphanumeric",
    "oss_host": "https://{appkey}.{region}.insforge.app"
  }
  

• file is readable by cli only (chmod 600 on unix), never committed to version control

database operations:

• query: plain text table (default) or json object array (with --json flag)
• export: sql file with create statements and insert statements, readable by any postgres client
• import: no stdout on success, transaction rolls back on error

edge function deployment:

• function available immediately at https://{appkey}.{region}.insforge.app/functions/{slug}
• invocation returns response body (json, text, or binary) and http status code
• exit code 0 on http 200-299, exit code 1 on http 400+

file storage:

• object keys are url-safe paths (e.g., docs/2024/report.pdf)
• objects accessible via https://{appkey}.{region}.insforge.app/storage/v1/object/public/{bucket}/{key} (public bucket)
• private bucket requires signed url or auth header

deployments:

• frontend deployed to vercel, assigned url https://{appkey}-{hash}.{region}.vercel.app
• dns can be configured to point custom domain to deployment url
• deployment immutable once built, rollback via deployments deploy with previous source

schedules:

• schedule persists in insforge backend, fires at next matching cron interval
• execution attempt logged even if target returns error
• logs retained for 7 days

secrets:

• secret value encrypted at rest and in transit
• resolved at schedule/function invocation time, not stored in plaintext anywhere
• soft delete (deactivated) means secret not used for new operations but can be restored

logs:

• logs contain timestamp, log level, message, context (function name, query, error trace)
• logs rotated after 7 days, older logs purged automatically
• max 1000 entries per query

outcome signal

user knows authentication succeeded:

• insforge whoami prints email address and exit code is 0
• insforge current prints org id and project id (or project id empty if not linked)

user knows project is linked:

• .insforge/project.json exists in working directory
• insforge current prints project id and region
• subsequent commands execute without exit code 3

user knows database operation succeeded:

• insforge db query returns result set or "0 rows" (for no results)
• exit code is 0
• for insert/update/delete, stdout shows affected row count

user knows edge function deployed:

• insforge functions list shows function with status active
• function url is reachable (http 200 on invoke with no data)
• logs show function execution in insforge logs function.logs

user knows file uploaded:

• insforge storage upload prints "uploaded to {key}"
• insforge storage list-objects shows object in bucket
• object is download-able via url or insforge storage download

user knows frontend deployed:

• insforge deployments list shows new deployment with status success
• deployment url (vercel.app) is live and returns frontend html
• custom domain resolves to deployment (if configured)

user knows schedule is active:

• insforge schedules get shows isActive: true
• insforge schedules logs shows execution attempts at next cron interval (within 1 minute of scheduled time)
• logs show http status code and response time

user knows secret is stored: