@insforge/cli 0.1.40 → 0.1.43

package/README.md

@@ -4,45 +4,39 @@ Command line tool for the [InsForge](https://insforge.dev) platform. Manage your
 
 Designed to be both human-friendly (interactive prompts, formatted tables) and agent-friendly (structured JSON output, non-interactive mode, semantic exit codes).
 
-## Installation
-
-```bash
-npm install -g @insforge/cli
-```
-
-Requires Node.js >= 18.
+Requires Node.js >= 18. We recommend running via `npx` so you always get the latest version — no global install needed.
 
 ## Quick Start
 
 ```bash
 # Login via browser (OAuth)
-insforge login
+npx @insforge/cli login
 
 # Or login with email/password
-insforge login --email
+npx @insforge/cli login --email
 
 # Check current user
-insforge whoami
+npx @insforge/cli whoami
 
 # List all organizations and projects
-insforge list
+npx @insforge/cli list
 
 # Link current directory to a project
-insforge link
+npx @insforge/cli link
 
 # Query the database
-insforge db tables
-insforge db query "SELECT * FROM users LIMIT 10"
+npx @insforge/cli db tables
+npx @insforge/cli db query "SELECT * FROM users LIMIT 10"
 ```
 
 ## Authentication
 
-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 `insforge login` first.
+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.
 
 ### Browser Login (default)
 
 ```bash
-insforge login
+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`.
@@ -50,19 +44,19 @@ Opens your browser to the InsForge authorization page using OAuth 2.0 Authorizat
 ### Email/Password Login
 
 ```bash
-insforge login --email
+npx @insforge/cli login --email
 ```
 
 Prompts for email and password interactively, or reads from environment variables in non-interactive mode:
 
 ```bash
-INSFORGE_EMAIL=user@example.com INSFORGE_PASSWORD=secret insforge login --email --json
+INSFORGE_EMAIL=user@example.com INSFORGE_PASSWORD=secret npx @insforge/cli login --email --json
 ```
 
 ### Logout
 
 ```bash
-insforge logout
+npx @insforge/cli logout
 ```
 
 ## Global Options
@@ -80,69 +74,76 @@ All commands support the following flags:
 
 ### Top-Level
 
-#### `insforge whoami`
+#### `npx @insforge/cli whoami`
 
 Show the current authenticated user.
 
 ```bash
-insforge whoami
-insforge whoami --json
+npx @insforge/cli whoami
+npx @insforge/cli whoami --json
 ```
 
-#### `insforge list`
+#### `npx @insforge/cli list`
 
 List all organizations and their projects in a grouped table.
 
 ```bash
-insforge list
-insforge list --json
+npx @insforge/cli list
+npx @insforge/cli list --json
 ```
 
-#### `insforge create`
+#### `npx @insforge/cli create`
 
 Create a new InsForge project interactively.
 
 ```bash
-insforge create
-insforge create --name "my-app" --org-id <org-id> --region us-east
+npx @insforge/cli create
+npx @insforge/cli create --name "my-app" --org-id <org-id> --region us-east
 ```
 
-#### `insforge link`
+#### `npx @insforge/cli link`
 
 Link the current directory to an InsForge project. Creates `.insforge/project.json` with the project ID, API key, and OSS host URL.
 
 ```bash
 # Interactive: select from a list
-insforge link
+npx @insforge/cli link
 
-# Non-interactive
-insforge link --project-id <id> --org-id <org-id>
+# 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>
 ```
 
-#### `insforge current`
+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`).
+
+#### `npx @insforge/cli current`
 
 Show current CLI context (authenticated user, linked project).
 
 ```bash
-insforge current
-insforge current --json
+npx @insforge/cli current
+npx @insforge/cli current --json
 ```
 
-#### `insforge metadata`
+#### `npx @insforge/cli metadata`
 
 Show backend metadata including auth configuration, database tables, storage buckets, edge functions, AI models, and realtime channels.
 
 ```bash
-insforge metadata
-insforge metadata --json
+npx @insforge/cli metadata
+npx @insforge/cli metadata --json
 ```
 
-#### `insforge logs`
+#### `npx @insforge/cli logs`
 
 Fetch backend container logs.
 
 ```bash
-insforge logs <source> [options]
+npx @insforge/cli logs <source> [options]
 ```
 
 **Sources:** `insforge.logs`, `postgREST.logs`, `postgres.logs`, `function.logs`
@@ -152,17 +153,17 @@ insforge logs <source> [options]
 
 **Examples:**
 ```bash
-insforge logs insforge.logs
-insforge logs postgres.logs --limit 50
-insforge logs function.logs --json
+npx @insforge/cli logs insforge.logs
+npx @insforge/cli logs postgres.logs --limit 50
+npx @insforge/cli logs function.logs --json
 ```
 
-#### `insforge docs`
+#### `npx @insforge/cli docs`
 
 Browse InsForge SDK documentation.
 
 ```bash
-insforge docs [feature] [language]
+npx @insforge/cli docs [feature] [language]
 ```
 
 **Features:** `db`, `storage`, `functions`, `auth`, `ai`, `realtime`, `instructions`
@@ -171,359 +172,359 @@ insforge docs [feature] [language]
 **Examples:**
 ```bash
 # List all available docs
-insforge docs
+npx @insforge/cli docs
 
 # Specific feature/language docs
-insforge docs instructions           # Show backend setup instructions
-insforge docs db typescript          # Show TypeScript database SDK docs
-insforge docs auth swift             # Show Swift auth SDK docs
-insforge docs storage rest-api       # Show REST API storage 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
 ```
 
 ---
 
-### Database — `insforge db`
+### Database — `npx @insforge/cli db`
 
-#### `insforge db query <sql>`
+#### `npx @insforge/cli db query <sql>`
 
 Execute a raw SQL query.
 
 ```bash
-insforge db query "SELECT * FROM users LIMIT 10"
-insforge db query "SELECT count(*) FROM orders" --json
-insforge db query "SELECT * FROM pg_tables" --unrestricted
+npx @insforge/cli db query "SELECT * FROM users LIMIT 10"
+npx @insforge/cli db query "SELECT count(*) FROM orders" --json
+npx @insforge/cli db query "SELECT * FROM pg_tables" --unrestricted
 ```
 
-#### `insforge db tables`
+#### `npx @insforge/cli db tables`
 
 List all database tables.
 
 ```bash
-insforge db tables
-insforge db tables --json
+npx @insforge/cli db tables
+npx @insforge/cli db tables --json
 ```
 
-#### `insforge db functions`
+#### `npx @insforge/cli db functions`
 
 List all database functions.
 
 ```bash
-insforge db functions
+npx @insforge/cli db functions
 ```
 
-#### `insforge db indexes`
+#### `npx @insforge/cli db indexes`
 
 List all database indexes.
 
 ```bash
-insforge db indexes
+npx @insforge/cli db indexes
 ```
 
-#### `insforge db policies`
+#### `npx @insforge/cli db policies`
 
 List all RLS policies.
 
 ```bash
-insforge db policies
+npx @insforge/cli db policies
 ```
 
-#### `insforge db triggers`
+#### `npx @insforge/cli db triggers`
 
 List all database triggers.
 
 ```bash
-insforge db triggers
+npx @insforge/cli db triggers
 ```
 
-#### `insforge db rpc <functionName>`
+#### `npx @insforge/cli db rpc <functionName>`
 
 Call a database function via RPC.
 
 ```bash
-insforge db rpc my_function --data '{"param1": "value"}'
+npx @insforge/cli db rpc my_function --data '{"param1": "value"}'
 ```
 
-#### `insforge db export`
+#### `npx @insforge/cli db export`
 
 Export database schema and/or data.
 
 ```bash
-insforge db export --output schema.sql
-insforge db export --data-only --output data.sql
+npx @insforge/cli db export --output schema.sql
+npx @insforge/cli db export --data-only --output data.sql
 ```
 
-#### `insforge db import <file>`
+#### `npx @insforge/cli db import <file>`
 
 Import database from a local SQL file.
 
 ```bash
-insforge db import schema.sql
+npx @insforge/cli db import schema.sql
 ```
 
 ---
 
-### Functions — `insforge functions`
+### Functions — `npx @insforge/cli functions`
 
-#### `insforge functions list`
+#### `npx @insforge/cli functions list`
 
 List all edge functions.
 
 ```bash
-insforge functions list
-insforge functions list --json
+npx @insforge/cli functions list
+npx @insforge/cli functions list --json
 ```
 
-#### `insforge functions code <slug>`
+#### `npx @insforge/cli functions code <slug>`
 
 View the source code of an edge function.
 
 ```bash
-insforge functions code my-function
-insforge functions code my-function --json
+npx @insforge/cli functions code my-function
+npx @insforge/cli functions code my-function --json
 ```
 
-#### `insforge functions deploy <slug>`
+#### `npx @insforge/cli functions deploy <slug>`
 
 Deploy an edge function. Creates the function if it doesn't exist, or updates it.
 
 ```bash
-insforge functions deploy my-function --file ./handler.ts
-insforge functions deploy my-function --file ./handler.ts --name "My Function" --description "Does something"
+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"
 ```
 
-#### `insforge functions invoke <slug>`
+#### `npx @insforge/cli functions invoke <slug>`
 
 Invoke an edge function.
 
 ```bash
-insforge functions invoke my-function --data '{"key": "value"}'
-insforge functions invoke my-function --method GET
-insforge functions invoke my-function --data '{"key": "value"}' --json
+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
 ```
 
-#### `insforge functions delete <slug>`
+#### `npx @insforge/cli functions delete <slug>`
 
 Delete an edge function.
 
 ```bash
-insforge functions delete my-function
-insforge functions delete my-function -y  # skip confirmation
+npx @insforge/cli functions delete my-function
+npx @insforge/cli functions delete my-function -y  # skip confirmation
 ```
 
 ---
 
-### Storage — `insforge storage`
+### Storage — `npx @insforge/cli storage`
 
-#### `insforge storage buckets`
+#### `npx @insforge/cli storage buckets`
 
 List all storage buckets.
 
 ```bash
-insforge storage buckets
-insforge storage buckets --json
+npx @insforge/cli storage buckets
+npx @insforge/cli storage buckets --json
 ```
 
-#### `insforge storage create-bucket <name>`
+#### `npx @insforge/cli storage create-bucket <name>`
 
 Create a new storage bucket.
 
 ```bash
-insforge storage create-bucket images
-insforge storage create-bucket private-docs --private
+npx @insforge/cli storage create-bucket images
+npx @insforge/cli storage create-bucket private-docs --private
 ```
 
-#### `insforge storage delete-bucket <name>`
+#### `npx @insforge/cli storage delete-bucket <name>`
 
 Delete a storage bucket and all its objects.
 
 ```bash
-insforge storage delete-bucket images
-insforge storage delete-bucket images -y   # skip confirmation
+npx @insforge/cli storage delete-bucket images
+npx @insforge/cli storage delete-bucket images -y   # skip confirmation
 ```
 
-#### `insforge storage list-objects <bucket>`
+#### `npx @insforge/cli storage list-objects <bucket>`
 
 List objects in a storage bucket.
 
 ```bash
-insforge storage list-objects images
-insforge storage list-objects images --prefix "avatars/" --limit 50
+npx @insforge/cli storage list-objects images
+npx @insforge/cli storage list-objects images --prefix "avatars/" --limit 50
 ```
 
-#### `insforge storage upload <file>`
+#### `npx @insforge/cli storage upload <file>`
 
 Upload a file to a storage bucket.
 
 ```bash
-insforge storage upload ./photo.png --bucket images
-insforge storage upload ./photo.png --bucket images --key "avatars/user-123.png"
+npx @insforge/cli storage upload ./photo.png --bucket images
+npx @insforge/cli storage upload ./photo.png --bucket images --key "avatars/user-123.png"
 ```
 
-#### `insforge storage download <objectKey>`
+#### `npx @insforge/cli storage download <objectKey>`
 
 Download a file from a storage bucket.
 
 ```bash
-insforge storage download avatars/user-123.png --bucket images
-insforge storage download avatars/user-123.png --bucket images --output ./downloaded.png
+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
 ```
 
 ---
 
-### Deployments — `insforge deployments`
+### Deployments — `npx @insforge/cli deployments`
 
-#### `insforge deployments deploy [directory]`
+#### `npx @insforge/cli deployments deploy [directory]`
 
 Deploy a frontend project. Zips the source, uploads it, and polls for build completion (up to 2 minutes).
 
 ```bash
-insforge deployments deploy
-insforge deployments deploy ./my-app
-insforge deployments deploy --env '{"API_URL": "https://api.example.com"}'
+npx @insforge/cli deployments deploy
+npx @insforge/cli deployments deploy ./my-app
+npx @insforge/cli deployments deploy --env '{"API_URL": "https://api.example.com"}'
 ```
 
-#### `insforge deployments list`
+#### `npx @insforge/cli deployments list`
 
 List all deployments.
 
 ```bash
-insforge deployments list
-insforge deployments list --limit 5 --json
+npx @insforge/cli deployments list
+npx @insforge/cli deployments list --limit 5 --json
 ```
 
-#### `insforge deployments status <id>`
+#### `npx @insforge/cli deployments status <id>`
 
 Get deployment details and status.
 
 ```bash
-insforge deployments status abc-123
-insforge deployments status abc-123 --sync   # sync status from Vercel first
+npx @insforge/cli deployments status abc-123
+npx @insforge/cli deployments status abc-123 --sync   # sync status from Vercel first
 ```
 
-#### `insforge deployments cancel <id>`
+#### `npx @insforge/cli deployments cancel <id>`
 
 Cancel a running deployment.
 
 ```bash
-insforge deployments cancel abc-123
+npx @insforge/cli deployments cancel abc-123
 ```
 
 ---
 
-### Secrets — `insforge secrets`
+### Secrets — `npx @insforge/cli secrets`
 
-#### `insforge secrets list`
+#### `npx @insforge/cli secrets list`
 
 List all secrets (metadata only, values are hidden). Inactive (deleted) secrets are hidden by default.
 
 ```bash
-insforge secrets list
-insforge secrets list --all   # include inactive secrets
-insforge secrets list --json
+npx @insforge/cli secrets list
+npx @insforge/cli secrets list --all   # include inactive secrets
+npx @insforge/cli secrets list --json
 ```
 
-#### `insforge secrets get <key>`
+#### `npx @insforge/cli secrets get <key>`
 
 Get the decrypted value of a secret.
 
 ```bash
-insforge secrets get STRIPE_API_KEY
-insforge secrets get STRIPE_API_KEY --json
+npx @insforge/cli secrets get STRIPE_API_KEY
+npx @insforge/cli secrets get STRIPE_API_KEY --json
 ```
 
-#### `insforge secrets add <key> <value>`
+#### `npx @insforge/cli secrets add <key> <value>`
 
 Create a new secret.
 
 ```bash
-insforge secrets add STRIPE_API_KEY sk_live_xxx
-insforge secrets add STRIPE_API_KEY sk_live_xxx --reserved
-insforge secrets add TEMP_TOKEN abc123 --expires "2025-12-31T00:00:00Z"
+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"
 ```
 
-#### `insforge secrets update <key>`
+#### `npx @insforge/cli secrets update <key>`
 
 Update an existing secret.
 
 ```bash
-insforge secrets update STRIPE_API_KEY --value sk_live_new_xxx
-insforge secrets update STRIPE_API_KEY --active false
-insforge secrets update STRIPE_API_KEY --reserved true
-insforge secrets update STRIPE_API_KEY --expires null   # remove expiration
+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
 ```
 
-#### `insforge secrets delete <key>`
+#### `npx @insforge/cli secrets delete <key>`
 
 Delete a secret (soft delete — marks as inactive).
 
 ```bash
-insforge secrets delete STRIPE_API_KEY
-insforge secrets delete STRIPE_API_KEY -y   # skip confirmation
+npx @insforge/cli secrets delete STRIPE_API_KEY
+npx @insforge/cli secrets delete STRIPE_API_KEY -y   # skip confirmation
 ```
 
-### Schedules — `insforge schedules`
+### Schedules — `npx @insforge/cli schedules`
 
 Manage scheduled tasks (cron jobs).
 
-#### `insforge schedules list`
+#### `npx @insforge/cli schedules list`
 
 List all schedules in the current project.
 
 ```bash
-insforge schedules list
-insforge schedules list --json
+npx @insforge/cli schedules list
+npx @insforge/cli schedules list --json
 ```
 
-#### `insforge schedules create`
+#### `npx @insforge/cli schedules create`
 
 Create a new scheduled task.
 
 ```bash
-insforge schedules create --name "daily-cleanup" --cron "0 0 * * *" --url "https://api.example.com/cleanup" --method POST
-insforge schedules create --name "hourly-sync" --cron "0 * * * *" --url "https://api.example.com/sync" --method GET --headers '{"Authorization": "Bearer xxx"}'
+npx @insforge/cli schedules create --name "daily-cleanup" --cron "0 0 * * *" --url "https://api.example.com/cleanup" --method POST
+npx @insforge/cli schedules create --name "hourly-sync" --cron "0 * * * *" --url "https://api.example.com/sync" --method GET --headers '{"Authorization": "Bearer xxx"}'
 ```
 
-#### `insforge schedules get <id>`
+#### `npx @insforge/cli schedules get <id>`
 
 Get details of a specific schedule.
 
 ```bash
-insforge schedules get <id>
-insforge schedules get 123 --json
+npx @insforge/cli schedules get <id>
+npx @insforge/cli schedules get 123 --json
 ```
 
-#### `insforge schedules update <id>`
+#### `npx @insforge/cli schedules update <id>`
 
 Update an existing schedule.
 
 ```bash
-insforge schedules update <id> --name "weekly-cleanup" --cron "0 0 * * 0"
-insforge schedules update 123 --active false
+npx @insforge/cli schedules update <id> --name "weekly-cleanup" --cron "0 0 * * 0"
+npx @insforge/cli schedules update 123 --active false
 ```
 
-#### `insforge schedules delete <id>`
+#### `npx @insforge/cli schedules delete <id>`
 
 Delete a schedule.
 
 ```bash
-insforge schedules delete <id>
-insforge schedules delete 123 -y
+npx @insforge/cli schedules delete <id>
+npx @insforge/cli schedules delete 123 -y
 ```
 
-#### `insforge schedules logs <id>`
+#### `npx @insforge/cli schedules logs <id>`
 
 Fetch execution logs for a specific schedule.
 
 ```bash
-insforge schedules logs <id>
-insforge schedules logs 123 --limit 100
+npx @insforge/cli schedules logs <id>
+npx @insforge/cli schedules logs 123 --limit 100
 ```
 
 ---
 
 ## Project Configuration
 
-Running `insforge link` creates a `.insforge/` directory in your project:
+Running `npx @insforge/cli link` creates a `.insforge/` directory in your project:
 
 ```
 .insforge/
@@ -540,6 +541,20 @@ Global configuration is stored in `~/.insforge/`:
 └── config.json         # default_org_id, platform_api_url
 ```
 
+## Agent Skills
+
+When you run `npx @insforge/cli create` or `npx @insforge/cli link`, the CLI automatically installs a set of [InsForge agent skills](https://github.com/InsForge/agent-skills) into your project for all supported AI coding agents (Claude Code, Cursor, Windsurf, Cline, Roo, Gemini CLI, GitHub Copilot, Qwen, Qoder, Trae, Kilo, Codex, Augment, Antigravity). These skills teach your coding agent how to work with InsForge — database queries, auth, storage, edge functions, realtime, etc. — so it can generate correct code for your backend without you copy-pasting docs.
+
+It also installs [`find-skills`](https://github.com/vercel-labs/skills) so agents can discover available skills on demand.
+
+Skill files are written to per-agent directories (e.g. `.claude/`, `.cursor/`, `.windsurf/`) and are automatically added to your `.gitignore`. You can re-run `npx @insforge/cli link` at any time to reinstall or update skills.
+
+## Analytics
+
+The CLI reports anonymous usage events to [PostHog](https://posthog.com) so we can understand which features are being used and prioritize improvements. 
+
+Analytics are enabled by default in the published npm package. If you build the CLI from source without setting `POSTHOG_API_KEY` at build time, analytics become a no-op automatically.
+
 ## Environment Variables
 
 | Variable | Description |
@@ -556,19 +571,19 @@ All commands support `--json` for structured output and `-y` to skip confirmatio
 
 ```bash
 # Login in CI
-INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD insforge login --email --json
+INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD npx @insforge/cli login --email --json
 
 # Link a project
-insforge link --project-id $PROJECT_ID --org-id $ORG_ID -y
+npx @insforge/cli link --project-id $PROJECT_ID --org-id $ORG_ID -y
 
 # Query and pipe results
-insforge db query "SELECT * FROM users" --json | jq '.rows[].email'
+npx @insforge/cli db query "SELECT * FROM users" --json | jq '.rows[].email'
 
 # Deploy frontend
-insforge deployments deploy ./dist --json
+npx @insforge/cli deployments deploy ./dist --json
 
 # Upload a build artifact
-insforge storage upload ./dist/bundle.js --bucket assets --key "v1.2.0/bundle.js" --json
+npx @insforge/cli storage upload ./dist/bundle.js --bucket assets --key "v1.2.0/bundle.js" --json
 ```
 
 ## Exit Codes
@@ -578,7 +593,7 @@ insforge storage upload ./dist/bundle.js --bucket assets --key "v1.2.0/bundle.js
 | 0 | Success |
 | 1 | General error |
 | 2 | Authentication failure |
-| 3 | Project not linked (run `insforge link` first) |
+| 3 | Project not linked (run `npx @insforge/cli link` first) |
 | 4 | Resource not found |
 | 5 | Permission denied |
 
@@ -613,8 +628,8 @@ npm run test:integration:real
 ```
 
 Prerequisites:
-- Logged in (`insforge login`) so `~/.insforge/credentials.json` exists
-- Linked project in this repo (`insforge link`) so `.insforge/project.json` exists
+- Logged in (`npx @insforge/cli login`) so `~/.insforge/credentials.json` exists
+- Linked project in this repo (`npx @insforge/cli link`) so `.insforge/project.json` exists
 
 Optional environment variables:
 - `INSFORGE_API_URL`: Platform API URL override (defaults to `https://api.insforge.dev`)