InsForge CLI 命令行工具 - 管理后端即服务项目，支持数据库、函数、存储

insforge-cli by insforge/agent-skills

2,300 周安装量

12 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/insforge/agent-skills --skill insforge-cli

开发云服务开发运维

🇨🇳中文介绍

InsForge CLI

用于管理 InsForge 后端即服务项目的命令行工具。

重要：始终使用 npx（不要全局安装）

切勿全局安装 CLI（npm install -g @insforge/cli）。始终通过 npx 运行命令：

npx @insforge/cli <命令>

这确保了始终使用最新版本，且无需处理全局安装问题（权限、PATH、node 版本不匹配）。

会话开始 — 验证身份验证和项目：

npx @insforge/cli whoami    # 验证身份验证
npx @insforge/cli current   # 验证链接的项目

如果未通过身份验证：npx @insforge/cli login 如果未链接项目：npx @insforge/cli create（新建）或 npx @insforge/cli link（现有）

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

find-skills 技能搜索工具 - Vercel Labs 开源智能体技能包管理器

733,500 周安装

Vercel React 最佳实践指南 | 58条Next.js性能优化规则与代码重构

252,100 周安装

Vercel Web界面规范检查工具 - 自动检测代码是否符合Web设计指南

202,600 周安装

agent-browser 浏览器自动化工具 - Vercel Labs 命令行网页操作与测试

133,200 周安装

标志	描述
`--json`	结构化 JSON 输出（用于脚本和代理）
`-y, --yes`	跳过确认提示

代码	含义
0	成功
1	常规错误（例如，函数调用返回 HTTP 400+）
2	未通过身份验证
3	项目未链接
4	资源未找到
5	权限被拒绝

变量	描述
`INSFORGE_ACCESS_TOKEN`	覆盖存储的访问令牌
`INSFORGE_PROJECT_ID`	覆盖链接的项目 ID
`INSFORGE_EMAIL`	用于非交互式登录的邮箱
`INSFORGE_PASSWORD`	用于非交互式登录的密码

npx @insforge/cli create — 创建新项目。参见 references/create.md
npx @insforge/cli link — 将目录链接到现有项目
npx @insforge/cli current — 显示当前用户 + 链接的项目
npx @insforge/cli list — 列出所有组织和项目
npx @insforge/cli metadata — 显示后端元数据（身份验证配置、数据库表、存储桶、边缘函数、AI 模型、实时频道）。使用 --json 获取结构化输出。首先运行此命令以在构建功能前发现已配置的内容。

npx @insforge/cli db query <sql> — 执行原始 SQL。参见 references/db-query.md
npx @insforge/cli db tables / indexes / policies / triggers / functions — 检查架构
npx @insforge/cli db rpc <fn> [--data <json>] — 调用数据库函数（无数据则 GET，有数据则 POST）
npx @insforge/cli db export — 导出架构/数据。参见 references/db-export.md
npx @insforge/cli db import <file> — 从 SQL 文件导入。参见 references/db-import.md

npx @insforge/cli functions list — 列出已部署的函数
npx @insforge/cli functions code <slug> — 查看函数源代码
npx @insforge/cli functions deploy <slug> — 部署或更新。参见 references/functions-deploy.md
npx @insforge/cli functions invoke <slug> [--data <json>] [--method GET|POST] — 调用函数

npx @insforge/cli storage buckets — 列出存储桶
npx @insforge/cli storage create-bucket <name> [--private] — 创建存储桶（默认：公开）
npx @insforge/cli storage delete-bucket <name> — 删除存储桶及其所有对象（破坏性操作）
npx @insforge/cli storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort] — 列出对象
npx @insforge/cli storage upload <file> --bucket <name> [--key <objectKey>] — 上传文件
npx @insforge/cli storage download <objectKey> --bucket <name> [--output <path>] — 下载文件

npx @insforge/cli deployments deploy [dir] — 部署前端应用。参见 references/deployments-deploy.md
npx @insforge/cli deployments list — 列出部署
npx @insforge/cli deployments status <id> [--sync] — 获取部署状态（--sync 从 Vercel 获取）
npx @insforge/cli deployments cancel <id> — 取消正在运行的部署

npx @insforge/cli secrets list [--all] — 列出密钥（值隐藏；--all 包含已删除的）
npx @insforge/cli secrets get <key> — 获取解密后的值
npx @insforge/cli secrets add <key> <value> [--reserved] [--expires <ISO date>] — 创建密钥
npx @insforge/cli secrets update <key> [--value] [--active] [--reserved] [--expires] — 更新密钥
npx @insforge/cli secrets delete <key> — 软删除（标记为不活跃；使用 --active true 恢复）

npx @insforge/cli schedules list — 列出所有计划任务（显示 ID、名称、cron、URL、方法、活跃状态、下次运行时间）
npx @insforge/cli schedules get <id> — 获取计划任务详情
npx @insforge/cli schedules create --name --cron --url --method [--headers <json>] [--body <json>] — 创建 cron 作业（仅支持 5 字段 cron 格式）
npx @insforge/cli schedules update <id> [--name] [--cron] [--url] [--method] [--headers] [--body] [--active] — 更新计划任务
npx @insforge/cli schedules delete <id> — 删除计划任务（需确认）
npx @insforge/cli schedules logs <id> [--limit] [--offset] — 查看执行日志

来源	描述
`insforge.logs`	主后端日志
`postgREST.logs`	PostgREST API 层日志
`postgres.logs`	PostgreSQL 数据库日志
`function.logs`	边缘函数执行日志

npx @insforge/cli docs — 列出所有主题
npx @insforge/cli docs instructions — 设置指南
npx @insforge/cli docs <feature> <language> — 功能文档（db / storage / functions / auth / ai / realtime × typescript / swift / kotlin / rest-api）

npx @insforge/cli db query "CREATE TABLE posts (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT,
  author_id UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT now()
)"
npx @insforge/cli db query "ALTER TABLE posts ENABLE ROW LEVEL SECURITY"
npx @insforge/cli db query "CREATE POLICY \"public_read\" ON posts FOR SELECT USING (true)"
npx @insforge/cli db query "CREATE POLICY \"owner_write\" ON posts FOR INSERT WITH CHECK (auth.uid() = author_id)"

框架	前缀	示例
Vite	`VITE_`	`VITE_INSFORGE_URL`
Next.js	`NEXT_PUBLIC_`	`NEXT_PUBLIC_INSFORGE_URL`
Create React App	`REACT_APP_`	`REACT_APP_INSFORGE_URL`
Astro	`PUBLIC_`	`PUBLIC_INSFORGE_URL`
SvelteKit	`PUBLIC_`	`PUBLIC_INSFORGE_URL`

npm run build 在本地成功
所有必需的环境变量已使用正确的框架前缀配置
边缘函数目录已从前端构建中排除（如适用）
zip 文件中绝不包含 node_modules、.git、.env、.insforge 或构建输出
构建输出目录与框架的预期输出匹配（dist/、build/、.next/ 等）

表达式	描述
`* * * * *`	每分钟
`/5 * * *`	每 5 分钟
`0 * * * *`	每小时（在 0 分）
`0 9 * * *`	每天上午 9:00
`0 9 * * 1`	每周一上午 9:00
`0 0 1 * *`	每月第一天午夜
`30 14 * * 1-5`	工作日下午 2:30

仅使用 5 字段 cron 表达式
- pg_cron 不支持秒（6 字段格式）
- 示例：*/5 * * * * 表示每 5 分钟
将敏感值存储为密钥
- 在标头中使用 ${{secrets.KEY_NAME}} 引用 API 密钥和令牌
- 在引用之前，先通过密钥 API 创建密钥
针对 InsForge 函数执行无服务器任务
- 使用函数 URL 格式：https://your-project.region.insforge.app/functions/{slug}
- 确保目标函数存在且状态为 "active"
监控执行日志
- 定期检查日志以确保计划任务成功运行
- 查找非 200 状态码和失败的执行

错误	解决方案
使用 6 字段 cron（带秒）	仅使用 5 字段格式：`分钟小时日月星期几`
引用不存在的密钥	先通过密钥 API 创建密钥
指向不存在的函数	在安排计划前验证函数存在且为 `active`
计划任务未运行	检查 `isActive` 是否为 `true` 以及 cron 表达式是否有效

问题	检查
函数不工作	`function.logs`
数据库查询失败	`postgres.logs`, `postgREST.logs`
身份验证问题	`insforge.logs`
API 返回 500 错误	`insforge.logs`, `postgREST.logs`

🇺🇸English

InsForge CLI

Command-line tool for managing InsForge Backend-as-a-Service projects.

Critical: Always Use npx (No Global Install)

NEVER install the CLI globally (npm install -g @insforge/cli). Always run commands via npx:

npx @insforge/cli <command>

This ensures the latest version is always used without global install issues (permissions, PATH, node version mismatches).

Session start — verify authentication and project:

npx @insforge/cli whoami    # verify authentication
npx @insforge/cli current   # verify linked project

If not authenticated: npx @insforge/cli login If no project linked: npx @insforge/cli create (new) or npx @insforge/cli link (existing)

Global Options

Flag	Description
`--json`	Structured JSON output (for scripts and agents)
`-y, --yes`	Skip confirmation prompts

All examples below use npx @insforge/cli. Never call insforge directly.

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
`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

Commands

Authentication

npx @insforge/cli login — OAuth (browser) or --email for password login. See references/login.md
npx @insforge/cli logout — clear stored credentials
npx @insforge/cli whoami — show current user

Project Management

npx @insforge/cli create — create new project. See references/create.md
npx @insforge/cli link — link directory to existing project
npx @insforge/cli current — show current user + linked project
npx @insforge/cli list — list all orgs and projects
npx @insforge/cli metadata — 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.

Database — `npx @insforge/cli db`

npx @insforge/cli db query <sql> — execute raw SQL. See references/db-query.md
npx @insforge/cli db tables / indexes / policies / triggers / functions — inspect schema
npx @insforge/cli db rpc <fn> [--data <json>] — call database function (GET if no data, POST if data)
npx @insforge/cli db export — export schema/data. See references/db-export.md
npx @insforge/cli db import <file> — import from SQL file. See references/db-import.md

Edge Functions — `npx @insforge/cli functions`

npx @insforge/cli functions list — list deployed functions
npx @insforge/cli functions code <slug> — view function source
npx @insforge/cli functions deploy <slug> — deploy or update. See references/functions-deploy.md
npx @insforge/cli functions invoke <slug> [--data <json>] [--method GET|POST] — invoke function

Storage — `npx @insforge/cli storage`

npx @insforge/cli storage buckets — list buckets
npx @insforge/cli storage create-bucket <name> [--private] — create bucket (default: public)
npx @insforge/cli storage delete-bucket <name> — delete bucket and all its objects (destructive)
npx @insforge/cli storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort] — list objects
npx @insforge/cli storage upload <file> --bucket <name> [--key <objectKey>] — upload file
npx @insforge/cli storage download <objectKey> --bucket <name> [--output <path>] — download file

Deployments — `npx @insforge/cli deployments`

npx @insforge/cli deployments deploy [dir] — deploy frontend app. See references/deployments-deploy.md
npx @insforge/cli deployments list — list deployments
npx @insforge/cli deployments status <id> [--sync] — get deployment status (--sync fetches from Vercel)
npx @insforge/cli deployments cancel <id> — cancel running deployment

Secrets — `npx @insforge/cli secrets`

npx @insforge/cli secrets list [--all] — list secrets (values hidden; --all includes deleted)
npx @insforge/cli secrets get <key> — get decrypted value
npx @insforge/cli secrets add <key> <value> [--reserved] [--expires <ISO date>] — create secret
npx @insforge/cli secrets update <key> [--value] [--active] [--reserved] [--expires] — update secret
npx @insforge/cli secrets delete <key> — soft delete (marks inactive; restore with --active true)

Schedules — `npx @insforge/cli schedules`

npx @insforge/cli schedules list — list all scheduled tasks (shows ID, name, cron, URL, method, active, next run)
npx @insforge/cli schedules get <id> — get schedule details
npx @insforge/cli schedules create --name --cron --url --method [--headers <json>] [--body <json>] — create a cron job (5-field cron format only)
npx @insforge/cli schedules update <id> [--name] [--cron] [--url] [--method] [--headers] [--body] [--active] — update schedule
npx @insforge/cli schedules delete <id> — delete schedule (with confirmation)
npx @insforge/cli schedules logs <id> [--limit] [--offset] — view execution logs

Logs — `npx @insforge/cli logs`

npx @insforge/cli logs <source> [--limit <n>] — fetch backend container logs (default: 20 entries)

Source	Description
`insforge.logs`	Main backend logs
`postgREST.logs`	PostgREST API layer logs
`postgres.logs`	PostgreSQL database logs
`function.logs`	Edge function execution logs

Source names are case-insensitive: postgrest.logs works the same as postgREST.logs.

Documentation — `npx @insforge/cli docs`

npx @insforge/cli docs — list all topics
npx @insforge/cli docs instructions — setup guide
npx @insforge/cli docs <feature> <language> — feature docs (db / storage / functions / auth / ai / realtime × typescript / swift / kotlin / rest-api)

For writing application code with the InsForge SDK, use the insforge (SDK) skill instead, and use the npx @insforge/cli 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 npx @insforge/cli 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

npx @insforge/cli db query "CREATE TABLE posts (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT,
  author_id UUID REFERENCES auth.users(id),
  created_at TIMESTAMPTZ DEFAULT now()
)"
npx @insforge/cli db query "ALTER TABLE posts ENABLE ROW LEVEL SECURITY"
npx @insforge/cli db query "CREATE POLICY \"public_read\" ON posts FOR SELECT USING (true)"
npx @insforge/cli db query "CREATE POLICY \"owner_write\" ON posts FOR INSERT WITH CHECK (auth.uid() = author_id)"

FK to users: always auth.users(id). RLS current user: auth.uid().

Deploy an edge function

# Default source path: insforge/functions/{slug}/index.ts
npx @insforge/cli functions deploy my-handler
npx @insforge/cli functions invoke my-handler --data '{"action": "test"}'

Deploy frontend

Always verify the local build succeeds before deploying. Local builds are faster to debug and don't waste server resources.

# 1. Build locally first
npm run build

# 2. Deploy
npx @insforge/cli deployments deploy ./dist --env '{"VITE_API_URL": "https://my-app.us-east.insforge.app"}'

Environment variable prefix by framework:

Framework	Prefix	Example
Vite	`VITE_`	`VITE_INSFORGE_URL`
Next.js	`NEXT_PUBLIC_`	`NEXT_PUBLIC_INSFORGE_URL`
Create React App	`REACT_APP_`	`REACT_APP_INSFORGE_URL`
Astro	`PUBLIC_`

Pre-deploy checklist:

npm run build succeeds locally
All required env vars configured with correct framework prefix
Edge function directories excluded from frontend build (if applicable)
Never include node_modules, .git, .env, .insforge, or build output in the zip
Build output directory matches framework's expected output (dist/, build/, .next/, etc.)

Backup and restore database

npx @insforge/cli db export --output backup.sql
npx @insforge/cli db import backup.sql

Schedule a cron job

# Create a schedule that calls a function every 5 minutes
npx @insforge/cli schedules create \
  --name "Cleanup Expired" \
  --cron "*/5 * * * *" \
  --url "https://my-app.us-east.insforge.app/functions/cleanup" \
  --method POST \
  --headers '{"Authorization": "Bearer ${{secrets.API_TOKEN}}"}'

# Check execution history
npx @insforge/cli schedules logs <id>

Cron Expression Format

InsForge uses 5-field cron expressions (pg_cron format). 6-field expressions with seconds are NOT supported.

┌─────────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌─────────── day of month (1-31)
│ │ │ ┌───────── month (1-12)
│ │ │ │ ┌─────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Expression	Description
`* * * * *`	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 every month at midnight

Secret References in Headers

Headers can reference secrets stored in InsForge using the syntax ${{secrets.KEY_NAME}}.

{
  "headers": {
    "Authorization": "Bearer ${{secrets.API_TOKEN}}",
    "X-API-Key": "${{secrets.EXTERNAL_API_KEY}}"
  }
}

Secrets are resolved at schedule creation/update time. If a referenced secret doesn't exist, the operation fails with a 404 error.

Best Practices

Use 5-field cron expressions only
- pg_cron does not support seconds (6-field format)
- Example: */5 * * * * for every 5 minutes
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
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 status: "active"
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: `minute hour day month day-of-week`
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

1. Create secrets if needed     -> `npx @insforge/cli secrets add KEY VALUE`
2. Create/verify target function -> `npx @insforge/cli functions list`
3. Create schedule              -> `npx @insforge/cli schedules create`
4. Verify schedule is active    -> `npx @insforge/cli schedules get <id>`
5. Monitor execution logs       -> `npx @insforge/cli schedules logs <id>`

Debug with logs

npx @insforge/cli logs function.logs          # function execution issues
npx @insforge/cli logs postgres.logs          # database query problems
npx @insforge/cli logs insforge.logs          # API / auth errors
npx @insforge/cli logs postgrest.logs --limit 50

Best Practices

Start with function.logs for function issues
- Check execution errors, timeouts, and runtime exceptions
Use postgres.logs for query problems
- Debug slow queries, constraint violations, connection issues
Check insforge.logs for API errors
- Authentication failures, request validation, general backend errors

Common Debugging Scenarios

Problem	Check
Function not working	`function.logs`
Database query failing	`postgres.logs`, `postgREST.logs`
Auth issues	`insforge.logs`
API returning 500 errors	`insforge.logs`, `postgREST.logs`

Non-interactive CI/CD

INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD npx @insforge/cli login --email -y
npx @insforge/cli link --project-id $PROJECT_ID --org-id $ORG_ID -y
npx @insforge/cli db query "SELECT count(*) FROM users" --json

Project Configuration

After create or link, .insforge/project.json is created:

{
  "project_id": "...",
  "appkey": "...",
  "region": "us-east",
  "api_key": "ik_...",
  "oss_host": "https://{appkey}.{region}.insforge.app"
}

oss_host is the base URL for all SDK and API operations. api_key is the admin key for backend API calls.

Never commit this file to version control or share it publicly. Do not edit this file manually. Use npx @insforge/cli link to switch projects.

Weekly Installs

2.3K

Repository

insforge/agent-skills

GitHub Stars

First Seen

Feb 25, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykFail

Installed on

cline2.3K

github-copilot2.3K

codex2.3K

cursor2.3K

gemini-cli2.3K

antigravity2.3K

InsForge CLI 命令行工具 - 管理后端即服务项目，支持数据库、函数、存储

🇨🇳中文介绍

InsForge CLI

重要：始终使用 npx（不要全局安装）

相关 Skills

全局选项

退出代码

环境变量

命令

身份验证

项目管理

数据库 — npx @insforge/cli db

边缘函数 — npx @insforge/cli functions

存储 — npx @insforge/cli storage

部署 — npx @insforge/cli deployments

密钥 — npx @insforge/cli secrets

计划任务 — npx @insforge/cli schedules

日志 — npx @insforge/cli logs

文档 — npx @insforge/cli docs

非显而易见的行为

常见工作流

设置数据库架构

部署边缘函数

部署前端

备份和恢复数据库

安排 cron 作业

Cron 表达式格式

标头中的密钥引用

最佳实践

常见错误

推荐工作流

使用日志调试

最佳实践

常见调试场景

非交互式 CI/CD

项目配置

🇺🇸English

InsForge CLI

Critical: Always Use npx (No Global Install)

Global Options

Exit Codes

Environment Variables

Commands

Authentication

Project Management

Database — npx @insforge/cli db

Edge Functions — npx @insforge/cli functions

Storage — npx @insforge/cli storage

Deployments — npx @insforge/cli deployments

Secrets — npx @insforge/cli secrets

Schedules — npx @insforge/cli schedules

Logs — npx @insforge/cli logs

Documentation — npx @insforge/cli docs

Non-Obvious Behaviors

Common Workflows

Set up database schema

Deploy an edge function

Deploy frontend

Backup and restore database

Schedule a cron job

Cron Expression Format

Secret References in Headers

Best Practices

Common Mistakes

Recommended Workflow

Debug with logs

Best Practices

Common Debugging Scenarios

Non-interactive CI/CD

Project Configuration

最新 Skills

数据库 — `npx @insforge/cli db`

边缘函数 — `npx @insforge/cli functions`

存储 — `npx @insforge/cli storage`

部署 — `npx @insforge/cli deployments`

密钥 — `npx @insforge/cli secrets`

计划任务 — `npx @insforge/cli schedules`

日志 — `npx @insforge/cli logs`

文档 — `npx @insforge/cli docs`

Database — `npx @insforge/cli db`

Edge Functions — `npx @insforge/cli functions`

Storage — `npx @insforge/cli storage`

Deployments — `npx @insforge/cli deployments`

Secrets — `npx @insforge/cli secrets`

Schedules — `npx @insforge/cli schedules`

Logs — `npx @insforge/cli logs`

Documentation — `npx @insforge/cli docs`