Back to results
InsForge/CLI(opens in a new tab)
Language: TypeScript
InsForge CLI
- stars
- 22
- watchers
- 0
- forks
- 21
- open issues
- 92
- Last updated
- 10/30/2026
gem-hunterLanguage: TypeScript
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.
# 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"
A hosted project is the default and what these commands assume. If you specifically want a backend running in Docker on your own machine — offline work, a throwaway database, no account — see Local Instances.
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.
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.
npx @insforge/cli login --email
Prompts for email and password interactively, or reads from environment variables in non-interactive mode:
INSFORGE_EMAIL=user@example.com INSFORGE_PASSWORD=secret npx @insforge/cli login --email --json
For a durable machine credential — CI pipelines, agents, or any headless context — authenticate with a uak_ user API key instead of short-lived session tokens:
npx @insforge/cli login --user-api-key uak_xxxxxxxx --json
Create the key in the dashboard (Profile → API Keys). Keys default to a 90-day expiry, or can be created with no expiry for a permanent credential. The key is sent directly as the bearer credential on every request — there is no hourly token expiry or refresh-token rotation to manage, and it works for accounts that sign in via OAuth providers (e.g. Google), where email/password login does not apply.
Alternatively, skip the login step entirely and pass the key per-invocation via the environment:
INSFORGE_ACCESS_TOKEN=uak_xxxxxxxx npx @insforge/cli db query "SELECT 1" --jsonnpx @insforge/cli logoutGlobal flags (available on all commands unless noted otherwise):
| Flag | Description |
|---|---|
--json |
Output in JSON format (useful for scripts and AI agents) |
--api-url <url> |
Override the Platform API URL |
-y, --yes |
Skip confirmation prompts |
--forger |
Play the Forger animation (root command only: insforge --forger) |
--forger is ignored with a warning when combined with a subcommand (e.g. insforge login --forger).
The --project-id <id> flag is command-specific and is supported by link
when you want to link a directory directly to a known project.
The
recordscommand group is registered but hidden (hidden: trueinsrc/index.ts);orgsandprojectsare visible but are intentionally excluded from this reference. Usenpx @insforge/cli listinstead oforgs/projects;recordsis internal and not supported for direct use.
Run a full InsForge backend on your own machine in Docker: Postgres, PostgREST, the backend, and the edge-functions runtime. No account, no repository clone.
One instance per directory. The compose project name includes a hash of the directory path, so every app folder gets its own containers, volumes, and database — including two folders that share a name.
Starts the stack, waits for it to become healthy, links the directory, and seeds
.env.local.
npx @insforge/cli local start npx @insforge/cli local start --storage minio # bundled S3-compatible store npx @insforge/cli local start --pull # re-pull images npx @insforge/cli local start --port-app 8130 # relocate a port npx @insforge/cli local start --json
| Option | Description |
|---|---|
--storage <backend> |
local (filesystem, default), minio, or rustfs. The bundled stores stay on the internal Docker network and enable the S3-compatible gateway at /storage/v1/s3. |
--pull |
Re-pull images even when present locally. |
--port-app, --port-auth, --port-deno, --port-postgres, --port-postgrest |
Host port overrides. Defaults are 7130 / 7131 / 7133 / 5432 / 5430. A port set here is never relocated. |
Afterwards every other command targets the local backend — no login, because the directory is linked with the instance's own API key:
npx @insforge/cli db query "select 1"
npx @insforge/cli storage create-bucket avatars
npx @insforge/cli functions deployWhere the stack comes from. The first start fetches
deploy/setup.sh
from the InsForge repository and runs it into .insforge/checkout/. That script
is what self-hosting uses, so a local instance runs the same compose file, init
SQL, and images as a deployed one — the CLI adds one overlay, which sets the
telemetry stamp and binds the published ports to loopback. Every start re-runs it,
picking up upstream changes; the generated .env is left alone.
Images track :latest. A directory's first start pulls, because Docker will not
re-fetch a tag it already has — without it a machine that pulled months ago runs
that image and reports its version, with nothing to suggest a newer one exists.
Later starts do not pull: an image moving under an instance that has data is how
the backend ends up running migrations its volume did not expect. --pull asks
for it deliberately.
.insforge/checkout/.env is where the instance's secrets are generated, and the
only copy of most of them — the Postgres password, JWT secret, encryption key,
and admin password appear nowhere else. (The API key is also in
.insforge/project.json, the anon key in .env.local.) If the file is missing
while volumes still exist, local start refuses rather than generating new ones:
Postgres reads its password only when the cluster is created, so fresh secrets
would leave the database unreachable.
Ports. The first instance on a machine gets 7130 / 7131 / 7133 / 5432 / 5430.
When those are taken the whole block shifts by ten — a second instance lands on
7140, a third on 7150 — and start prints what moved. Ports a directory has
already used stay put across restarts, so .env.local keeps pointing at the
right place.
Every published port binds to 127.0.0.1 — a development backend has no business
being reachable from the rest of the network. Services reach each other over the
project's internal Docker network, which is not published at all.
npx @insforge/cli local stop # stop; data is kept npx @insforge/cli local stop --delete-data # also destroy the volumes npx @insforge/cli local stop --unlink # restore the previous cloud link
--delete-data is irreversible and classified critical by the human-in-the-loop
guard, so with the guard enabled it requires approval. A plain stop never prompts.
If the directory was linked to a cloud project, local start saves that link to
.insforge/project.cloud.json rather than overwriting it, and local stop --unlink puts it back.
npx @insforge/cli local status npx @insforge/cli local status --show-keys # print keys in full npx @insforge/cli local status --json
Shows health, ports, the backend version, the compose project name, and
per-container state. Keys are masked by default, and --json omits them unless
--show-keys is passed — so its output is safe to paste into an issue.
Requirements. Docker with Compose 2.24.4 or newer, and roughly 1.5 GB
available to the daemon. Any Docker-compatible runtime works (Docker Desktop,
OrbStack, Colima, Rancher Desktop). Without Docker, insforge create gives you a
hosted project instead.
Show the current authenticated user.
npx @insforge/cli whoami npx @insforge/cli whoami --json
List all organizations and their projects in a grouped table.
npx @insforge/cli list npx @insforge/cli list --json
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 create --name "my-app" --template nextjs --auth better-auth # scaffold from a built-in template npx @insforge/cli create --name "my-app" --marketplace <slug> # install a marketplace template
Options:
--name <name>: Project name--org-id <id>: Organization ID--region <region>: Deployment region (us-east, us-west, eu-central, ap-southeast)--template <template>: Built-in template (react, nextjs, chatbot, crm, e-commerce, todo, or empty)--marketplace <slug>: Install a marketplace template by slug (browse: https://insforge.dev/templates)--auth <provider>: Wire a third-party auth provider into the chosen template (currently: better-auth)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).
Show current CLI context (authenticated user, linked project).
npx @insforge/cli current npx @insforge/cli current --json
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
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
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
Manage backend branches of the currently linked project.
List branches of the currently linked project.
npx @insforge/cli branch list npx @insforge/cli branch list --json
Create a branch from the currently linked project.
npx @insforge/cli branch create feature-x npx @insforge/cli branch create feature-x --mode schema-only # full | schema-only (default: full) npx @insforge/cli branch create feature-x --no-switch # do not auto-switch context after creation
Switch this directory's context to a branch (or back to the parent project).
npx @insforge/cli branch switch feature-x
npx @insforge/cli branch switch --parent # switch back to the parent projectMerge a branch back to its parent project.
npx @insforge/cli branch merge feature-x npx @insforge/cli branch merge feature-x --dry-run # compute the diff and print rendered SQL; do not apply npx @insforge/cli branch merge feature-x --save-sql diff.sql # write rendered SQL preview to a file
Reset a branch's database back to T0 (the parent snapshot at branch creation).
npx @insforge/cli branch reset feature-x
Delete a branch.
npx @insforge/cli branch delete feature-x
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.
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
List all database tables.
npx @insforge/cli db tables npx @insforge/cli db tables --json
List all database functions.
npx @insforge/cli db functions
List all database indexes.
npx @insforge/cli db indexes
List all RLS policies.
npx @insforge/cli db policies
List all database triggers.
npx @insforge/cli db triggers
Call a database function via RPC.
npx @insforge/cli db rpc my_function --data '{"param1": "value"}'Export database schema and/or data.
npx @insforge/cli db export --output dump.sql npx @insforge/cli db export --no-data --output schema-only.sql
Import database from a local SQL file.
npx @insforge/cli db import schema.sql
Manage database migration files.
npx @insforge/cli db migrations list # list applied remote migrations npx @insforge/cli db migrations fetch # fetch applied remote migrations into migrations/ npx @insforge/cli db migrations new add-users # create a new local migration file (lowercase, digits, hyphens only) npx @insforge/cli db migrations up --all # apply all pending local migrations npx @insforge/cli db migrations up --to 20260101_add-users # apply up to a version/file
Print the project Postgres connection URL (cloud projects only).
npx @insforge/cli db connection-string
List all edge functions.
npx @insforge/cli functions list npx @insforge/cli functions list --json
View the source code of an edge function.
npx @insforge/cli functions code my-function npx @insforge/cli functions code my-function --json
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"
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
Delete an edge function.
npx @insforge/cli functions delete my-function
npx @insforge/cli functions delete my-function -y # skip confirmationList all storage buckets.
npx @insforge/cli storage buckets npx @insforge/cli storage buckets --json
Create a new storage bucket.
npx @insforge/cli storage create-bucket images npx @insforge/cli storage create-bucket private-docs --private
Delete a storage bucket and all its objects.
npx @insforge/cli storage delete-bucket images
npx @insforge/cli storage delete-bucket images -y # skip confirmationList objects in a storage bucket.
npx @insforge/cli storage list-objects images
npx @insforge/cli storage list-objects images --prefix "avatars/" --limit 50Upload 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"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
Deploy a frontend project. Uploads the source files, starts the build, and polls for completion (up to 5 minutes). Backends without direct deployment fall back to a zip upload.
npx @insforge/cli deployments deploy
npx @insforge/cli deployments deploy ./my-app
npx @insforge/cli deployments deploy --env '{"API_URL": "https://api.example.com"}'To exclude files from the upload, add a .vercelignore file to the deploy directory. It uses .gitignore syntax (including ! negation) and is applied on top of the built-in excludes (node_modules, .git, .env, etc. — these always stay excluded and cannot be re-included).
# .vercelignore *.md drafts/ !IMPORTANT.md
List all deployments.
npx @insforge/cli deployments list npx @insforge/cli deployments list --limit 5 --json
Get deployment details and status.
npx @insforge/cli deployments status abc-123
npx @insforge/cli deployments status abc-123 --sync # sync status from Vercel firstCancel a running deployment.
npx @insforge/cli deployments cancel abc-123
Manage deployment environment variables.
npx @insforge/cli deployments env list # list all deployment env vars npx @insforge/cli deployments env set API_URL https://api.example.com # create or update a variable npx @insforge/cli deployments env delete <id> # delete a variable by ID
Show current deployment metadata and domain URLs.
npx @insforge/cli deployments metadata npx @insforge/cli deployments metadata --json
Show, set, or remove the custom deployment slug.
npx @insforge/cli deployments slug npx @insforge/cli deployments slug my-app npx @insforge/cli deployments slug --remove
Register a domain through the user's Cloudflare account, attach it to the linked InsForge deployment, sync Cloudflare DNS records, and verify SSL/custom domain readiness.
Cloudflare is connected through OAuth and saved locally in ~/.insforge/cloudflare.json:
npx @insforge/cli domains cloudflare login npx @insforge/cli domains cloudflare login --account-id <cloudflare-account-id> # skip account selection
The CLI opens Cloudflare in the browser, receives the OAuth callback on
http://127.0.0.1:8787/callback, stores the returned Cloudflare tokens locally,
and discovers the Cloudflare account selected during authorization. For
non-browser environments, pass --skip-browser and open the printed URL
manually. CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_ACCESS_TOKEN can override the
local OAuth credentials for automation.
Use the split commands when you want to inspect or resume a workflow:
npx @insforge/cli domains search my-app
npx @insforge/cli domains search my-app --tlds com,app,dev # optional local filter
npx @insforge/cli domains check my-app.dev
npx @insforge/cli domains buy my-app.dev
npx @insforge/cli domains attach my-app.dev
npx @insforge/cli domains dns sync my-app.dev
npx @insforge/cli domains verify my-app.dev
npx @insforge/cli domains status my-app.dev --cloudflareCloudflare only allows programmatic registration for TLDs currently supported by its Registrar API. The CLI surfaces Cloudflare's availability reason when a TLD is dashboard-only or not supported by the API.
For agent runs, use explicit purchase confirmations. The global --yes flag does not bypass domain purchase confirmation:
npx @insforge/cli domains buy-and-attach my-app.dev \ --confirm-domain my-app.dev \ --confirm-price 10.11 \ --confirm-currency USD \ --confirm-cloudflare-billing \ --confirm-non-refundable \ --json
If Cloudflare registration is still in progress, retry with:
npx @insforge/cli domains resume my-app.dev
Manage the payments foundation for the linked InsForge project. Provider-specific commands live under payments stripe and payments razorpay. These commands are intended for developers and agents configuring provider keys, syncing mirrored provider state, inspecting customers, and managing provider catalog records. Runtime checkout/order/subscription calls should usually be made from the app via the SDK.
Show key, account, sync, and webhook status for test/live environments.
npx @insforge/cli payments stripe status npx @insforge/cli payments razorpay status npx @insforge/cli payments stripe status --json
Set or remove provider keys. config set validates the keys and automatically syncs provider state when the key or account changes. Use payments <provider> status to inspect key, account, sync, and webhook health.
npx @insforge/cli payments stripe config set --environment test sk_test_xxx npx @insforge/cli payments stripe config set --environment live # prompts securely npx @insforge/cli payments stripe config remove --environment test -y npx @insforge/cli payments razorpay config set --environment test --key-id rzp_test_xxx --key-secret xxx npx @insforge/cli payments razorpay config remove --environment test -y
Manually refresh or retry provider catalog, customers, subscriptions, and transaction projections from configured environments. config set already syncs automatically when keys or accounts change.
npx @insforge/cli payments stripe sync npx @insforge/cli payments stripe sync --environment test npx @insforge/cli payments razorpay sync --environment test npx @insforge/cli payments stripe sync --environment live --json
Create or recreate the InsForge-managed Stripe webhook endpoint for an environment.
npx @insforge/cli payments stripe webhooks configure --environment testShow the webhook URL and secret to use when manually creating the webhook in Razorpay Dashboard.
npx @insforge/cli payments razorpay webhooks setup --environment test
npx @insforge/cli payments razorpay webhooks setup --environment live --jsonRotate the webhook secret for an environment. Existing Razorpay webhook deliveries fail until the new secret is updated in Razorpay Dashboard. The command asks for confirmation; use --yes to skip the prompt. JSON mode requires --yes.
npx @insforge/cli payments razorpay webhooks rotate-secret --environment test
npx @insforge/cli payments razorpay webhooks rotate-secret --environment live --yes --jsonRazorpay webhooks must still be created manually in Razorpay Dashboard. Copy the URL and secret returned by webhooks setup, select the recommended events, and save the webhook for the matching environment.
Inspect mirrored provider catalog records for one environment.
npx @insforge/cli payments stripe catalog --environment test npx @insforge/cli payments razorpay catalog --environment test npx @insforge/cli payments stripe catalog --environment test --json
List mirrored provider customers for admin/debugging workflows.
npx @insforge/cli payments stripe customers --environment test npx @insforge/cli payments razorpay customers --environment test npx @insforge/cli payments stripe customers --environment test --limit 20 --json
List, inspect, create, update, or delete Stripe products.
npx @insforge/cli payments stripe products list --environment test npx @insforge/cli payments stripe products get prod_123 --environment test npx @insforge/cli payments stripe products create --environment test --name "Pro Plan" npx @insforge/cli payments stripe products update prod_123 --environment test --description "Updated" npx @insforge/cli payments stripe products delete prod_123 --environment test -y
List, inspect, create, update, or archive Stripe prices.
npx @insforge/cli payments stripe prices list --environment test npx @insforge/cli payments stripe prices create --environment test --product prod_123 --currency usd --unit-amount 2000 npx @insforge/cli payments stripe prices create --environment test --product prod_123 --currency usd --unit-amount 2000 --interval month npx @insforge/cli payments stripe prices update price_123 --environment test --active false npx @insforge/cli payments stripe prices archive price_123 --environment test
List, create, or update Razorpay items.
npx @insforge/cli payments razorpay items list --environment test npx @insforge/cli payments razorpay items create --environment test --name "Pro Plan" --amount 200000 --currency inr npx @insforge/cli payments razorpay items update item_123 --environment test --active false
List or create Razorpay subscription plans.
npx @insforge/cli payments razorpay plans list --environment test npx @insforge/cli payments razorpay plans create --environment test --period monthly --interval 1 --item-name "Pro Plan" --item-amount 200000 --item-currency inr
Use --notes '{"key":"value"}' when the Razorpay Plan needs native Razorpay notes.
List mirrored provider subscriptions for admin/debugging workflows.
npx @insforge/cli payments stripe subscriptions --environment test npx @insforge/cli payments razorpay subscriptions --environment test npx @insforge/cli payments stripe subscriptions --environment test --subject-type team --subject-id team_123
List mirrored payment transactions for admin/debugging workflows. --subject-type and --subject-id refer to the app billing subject passed to InsForge, such as team:team_123 or user:user_123; they are not provider customer, payment, order, or subscription ids.
npx @insforge/cli payments stripe transactions --environment test npx @insforge/cli payments razorpay transactions --environment test npx @insforge/cli payments stripe transactions --environment test --limit 20 --json
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 --jsonGet the decrypted value of a secret.
npx @insforge/cli secrets get STRIPE_API_KEY npx @insforge/cli secrets get STRIPE_API_KEY --json
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"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
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 confirmationManage scheduled tasks (cron jobs).
List all schedules in the current project.
npx @insforge/cli schedules list npx @insforge/cli schedules list --json
| |
| |
| |
| |
|
| |