insforge-cli

intent

the insforge cli is a command-line tool for managing insforge backend-as-a-service projects. use this skill when the user needs to create or alter database tables and schemas, write row-level security policies via sql, deploy or invoke edge functions, create storage buckets, deploy frontends to hosting, manage secrets and environment variables, set up scheduled tasks (cron jobs), view backend logs, or export/import database backups. the cli bridges local development to insforge's hosted infrastructure. if the user asks for these operations generically (e.g., "create a users table", "deploy my app", "set up a cron job") and you're unsure whether they use insforge, consult this skill. note: for writing frontend application code with the insforge sdk (@insforge/sdk), use the insforge skill instead.

inputs

• insforge cli: must be installed globally via npm install -g @insforge/cli
• authentication: oauth login via browser or email/password via insforge login
• project linking: project must be linked to the current directory via insforge create (new project) or insforge link (existing project)
• environment variables (optional, override stored credentials):
  • INSFORGE_ACCESS_TOKEN: override stored access token
  • INSFORGE_PROJECT_ID: override linked project id
  • INSFORGE_EMAIL: email for non-interactive login
  • INSFORGE_PASSWORD: password for non-interactive login
• external context: knowledge of the user's insforge project structure (tables, functions, buckets, secrets, schedules) , discovered via insforge metadata --json

procedure

1. verify cli installation and authentication

   • input: shell access
   • run insforge whoami to check authentication status
   • output: user email/id if authenticated; exit code 2 if not authenticated
   • if not installed or command not found, run npm install -g @insforge/cli
   • if not authenticated, proceed to step 2

2. authenticate (if needed)

   • input: insforge credentials (oauth, or email + password)
   • run insforge login for oauth (opens browser) or insforge login --email for password-based login
   • output: stored access token in local config; exit code 0 on success
   • for ci/cd, set INSFORGE_EMAIL and INSFORGE_PASSWORD env vars, then run insforge login --email -y

3. verify or link project

   • input: shell access, optional insforge project id and org id
   • run insforge current to check linked project
   • output: current user + linked project id
   • if no project linked, run insforge create (new) or insforge link --project-id <id> --org-id <id> (existing)
   • output: .insforge/project.json created with project metadata

4. discover project configuration

   • input: linked project
   • run insforge metadata --json to inspect backend structure (auth config, database tables, storage buckets, edge functions, ai models, realtime channels)
   • output: json object describing all configured resources
   • use this output to understand the project before building features

5. execute target operation (choose one path below based on user intent)

   path a: database operations

   • input: sql query or schema inspection target
   • run one of:
     • insforge db query "<sql>" to execute raw sql (returns query result or exit code 1 on error)
     • insforge db tables / indexes / policies / triggers / functions to inspect schema (returns text table)
     • insforge db rpc <function_name> [--data <json>] to call a database function (post if data, get if no data)
     • insforge db export --output <file> to dump schema and data (creates sql file)
     • insforge db import <file> to load sql file into database (returns import summary)
   • output: query results, schema inspection, or file artifact
   • exit code: 0 on success; 1 on sql error; 4 if table/function not found; 5 if permission denied

   path b: edge function operations

   • input: function slug (directory name under insforge/functions/)
   • run one of:
     • insforge functions list to show all deployed functions (returns table with slug, status, url, updated_at)
     • insforge functions code <slug> to view function source code (returns file content)
     • insforge functions deploy <slug> to deploy or update a function (reads from insforge/functions/{slug}/index.ts, returns deployment status)
     • insforge functions invoke <slug> [--data <json>] [--method GET|POST] to call the function (returns http response body)
   • output: function list, source code, deployment status, or function response
   • exit code: 0 on success; 1 on http 400+ or invoke error; 4 if function not found

   path c: storage operations

   • input: bucket name, object key, file path
   • run one of:
     • insforge storage buckets to list all buckets (returns table with name, visibility, created_at)
     • insforge storage create-bucket <name> [--private] to create a bucket (default: public, returns bucket metadata)
     • insforge storage delete-bucket <name> to delete bucket and all objects (destructive, returns confirmation)
     • insforge storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort] to list objects (returns table with key, size, updated_at)
     • insforge storage upload <file> --bucket <name> [--key <objectKey>] to upload file (returns object metadata)
     • insforge storage download <objectKey> --bucket <name> [--output <path>] to download file (returns file written to disk)
   • output: bucket list, object list, or file artifact
   • exit code: 0 on success; 1 on storage error; 4 if bucket/object not found; 5 if permission denied

   path d: frontend deployment

   • input: local build directory (e.g., dist/, build/, .next/)
   • verify local build succeeds: npm run build (prevents deploy of broken builds)
   • run insforge deployments deploy [dir] [--env '{"KEY": "value"}'] (reads from dir, returns deployment id and status)
   • output: deployment id, build url, deployment status
   • exit code: 0 on success; 1 on deploy error
   • environment variable prefixes by framework: VITE_ (vite), NEXT_PUBLIC_ (next.js), REACT_APP_ (cra), PUBLIC_ (astro, sveltekit)

   path e: secrets management

   • input: secret key, secret value (sensitive)
   • run one of:
     • insforge secrets list [--all] to list all secrets (values hidden unless --all, returns table with key, active, expires_at)
     • insforge secrets get <key> to retrieve decrypted value (returns plaintext value)
     • insforge secrets add <key> <value> [--reserved] [--expires <iso_date>] to create secret (returns secret metadata)
     • insforge secrets update <key> [--value] [--active true|false] [--expires <iso_date>] to modify secret (returns updated metadata)
     • insforge secrets delete <key> to soft-delete secret (marks inactive, returns confirmation; restore with --active true)
   • output: secret list, value, or metadata
   • exit code: 0 on success; 1 on secret error; 4 if secret not found; 5 if permission denied

   path f: scheduled tasks (cron jobs)

   • input: cron expression (5-field only: minute hour day month day-of-week), target url, http method, optional headers and body
   • run one of:
     • insforge schedules list to show all schedules (returns table with id, name, cron, url, method, active, next_run)
     • insforge schedules get <id> to view schedule details (returns json object)
     • insforge schedules create --name <name> --cron <expr> --url <url> --method <GET|POST> [--headers <json>] [--body <json>] to create schedule (returns schedule id and metadata)
     • insforge schedules update <id> [--name] [--cron] [--url] [--method] [--headers] [--body] [--active true|false] to modify schedule (returns updated metadata)
     • insforge schedules delete <id> to delete schedule (asks for confirmation, returns deletion confirmation)
     • insforge schedules logs <id> [--limit <n>] [--offset <n>] to view execution history (returns log entries with timestamp, status code, duration)
   • output: schedule list, schedule details, or execution logs
   • exit code: 0 on success; 1 on schedule error; 4 if schedule not found

   path g: backend logs

   • input: log source name (insforge.logs, postgREST.logs, postgres.logs, function.logs)
   • run insforge logs <source> [--limit <n>] to fetch backend logs (default limit: 20 entries, returns log lines with timestamp and message)
   • output: log entries (text lines)
   • exit code: 0 on success; 1 on log fetch error

6. handle errors and edge cases

   • input: exit code from any command in steps 1-5
   • if exit code 2: user not authenticated. re-run step 2.
   • if exit code 3: project not linked. re-run step 3.
   • if exit code 4: resource not found (table, function, bucket, secret, schedule, log source). verify resource name and run insforge metadata --json to confirm existence.
   • if exit code 5: permission denied. verify user has admin or appropriate role for the project.
   • if exit code 1: general error (http 400+, sql syntax error, network timeout). check insforge logs for details. for function invokes, http 4xx/5xx from the function itself exits with code 1.
   • if rate limit hit (http 429): wait before retrying. no exponential backoff in cli; implement in wrapper if needed.
   • if auth token expired: stored access token has lifetime. run insforge login to refresh.
   • if empty result set (e.g., no rows returned from db query, no objects in bucket, no schedules created): operation succeeds but returns empty. this is not an error.
   • if network timeout: command hangs or exits with 1. ensure internet connectivity and insforge backend is reachable (check status page).

7. output results to user

   • input: command output from step 5
   • if user requested --json flag: output structured json (useful for scripts and downstream agents)
   • else: output human-readable text (table format, log lines, or confirmation message)
   • exit code: return exit code from step 5-6 to caller

decision points

• if cli not installed: install via npm install -g @insforge/cli
• if user not authenticated (exit code 2): run insforge login. for ci/cd, use email/password via env vars and --email -y flags.
• if project not linked (exit code 3): run insforge create (new project) or insforge link --project-id <id> --org-id <id> (existing project).
• if database operation and need to inspect schema first: run insforge metadata --json or insforge db tables before executing sql.
• if deploying frontend: verify local build succeeds first (npm run build). use correct env var prefix for framework (vite: VITE_, next.js: NEXT_PUBLIC_, etc.). never commit .insforge/project.json to version control.
• if scheduling a cron job and target is an insforge function: use function url format https://{appkey}.{region}.insforge.app/functions/{slug}. verify function exists and is active via insforge functions list.
• if scheduling a cron job and need to use sensitive data (api keys, tokens): store as secrets first via insforge secrets add, then reference in headers as ${{secrets.KEY_NAME}}.
• if need to debug a failed operation: check logs in this order: insforge logs function.logs (for function issues), insforge logs postgres.logs (for database issues), insforge logs insforge.logs (for auth/api issues). use --limit 50 for larger log window.
• if secret references a non-existent secret in schedule headers: operation fails with 404. create the secret first via insforge secrets add KEY VALUE.
• if cron expression is 6-field (includes seconds): not supported. convert to 5-field format (minute hour day month day-of-week only).
• if soft-deleted secret (via insforge secrets delete): marks inactive but not destroyed. restore with insforge secrets update KEY --active true. use insforge secrets list --all to see inactive secrets.
• if storage delete-bucket called: deletes bucket and all objects permanently. no undo; confirm intent first.
• if db rpc called without --data: uses http get. if --data provided: uses http post.
• if user requests structured output for scripts/agents: add --json flag to any command (works with most commands except logs, which default to text). use -y to skip confirmation prompts in non-interactive environments.

output contract

• authentication: exit code 0 on success; exit code 2 if not authenticated
• project linking: .insforge/project.json file created in current directory with keys: project_id, appkey, region, api_key, oss_host
• database operations: query results as text or json (if --json); schema tables; export as .sql file; import returns summary; exit code 0 on success, 1 on sql error, 4 if resource not found, 5 if permission denied
• edge function operations: function list as table; source code as text; deploy returns deployment status; invoke returns http response body (json or text); exit code 0 on success, 1 on http 400+ or invoke error, 4 if function not found
• storage operations: bucket list and object list as tables; upload/download return object metadata or file written to disk; delete returns confirmation; exit code 0 on success, 1 on storage error, 4 if bucket/object not found
• frontend deployment: deployment id, build url, deployment status; exit code 0 on success, 1 on deploy error
• secrets management: secret list as table (values hidden unless retrieved individually); get returns plaintext value; add/update return metadata; delete returns confirmation; exit code 0 on success, 1 on error, 4 if secret not found, 5 if permission denied
• scheduled tasks: schedule list as table; get returns json object; create/update return schedule id and metadata; delete returns confirmation; logs returns entries with timestamp, status code, duration; exit code 0 on success, 1 on error, 4 if schedule not found
• logs: log entries as text lines (one per line, with timestamp); exit code 0 on success, 1 on log fetch error
• non-interactive ci/cd: stdout contains command results; exit code 0 on success, non-zero on failure

outcome signal

• successful authentication: insforge whoami returns current user email/id; insforge current returns linked project id
• successful project linking: .insforge/project.json file exists in current directory; insforge current no longer errors
• successful database operation: query returns expected rows or schema changes; export produces a valid .sql file; import returns row count summary; no exit code 1
• successful function deployment: insforge functions list shows function with status "active"; insforge functions invoke returns http 200 and function output
• successful storage operation: bucket appears in insforge storage buckets; object appears in insforge storage list-objects; file downloads to local disk without error
• successful frontend deployment: deployment id returned; deployment status shows "ready" or "deployed"; build url is accessible in browser
• successful secret creation: insforge secrets list shows secret key (without value); insforge secrets get KEY returns plaintext value
• successful schedule creation: insforge schedules list shows schedule with correct cron expression, url, method; insforge schedules logs <id> shows execution history with 200+ status codes
• successful log retrieval: insforge logs <source> returns log lines without error; log entries have timestamps and readable messages
• non-interactive ci/cd success: exit code 0; no prompts encountered; output contains expected data (e.g., json, table, or confirmation message)

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

| variable | description | |