insforge-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

InsForge CLI

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

用于管理InsForge后端即服务（Backend-as-a-Service）项目的命令行工具。

Critical: Always Use npx (No Global Install)

重要提示：始终使用npx（请勿全局安装）

NEVER install the CLI globally (

npm install -g @insforge/cli

). Always run commands via

npx

bash

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:

bash

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)

绝不全局安装CLI（

npm install -g @insforge/cli

）。始终通过

npx

运行命令：

bash

npx @insforge/cli <command>

这确保始终使用最新版本，避免全局安装带来的问题（权限、PATH、Node版本不匹配）。

会话启动 —— 验证身份认证和项目：

bash

npx @insforge/cli whoami    # 验证身份认证
npx @insforge/cli current   # 验证关联的项目

若未认证：

npx @insforge/cli login

若未关联项目：

npx @insforge/cli create

（创建新项目）或

npx @insforge/cli link

（关联现有项目）

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.

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

以下所有示例均使用
npx @insforge/cli
。请勿直接调用
insforge
。

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

代码	含义
0	成功
1	通用错误（例如调用函数时返回HTTP 400+状态码）
2	未认证
3	未关联项目
4	资源未找到
5	权限拒绝

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

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

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

```
npx @insforge/cli login
```
—— OAuth（浏览器）或使用
```
--email
```
进行密码登录。查看 references/login.md
```
npx @insforge/cli logout
```
—— 清除存储的凭证
```
npx @insforge/cli whoami
```
—— 显示当前用户

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.

```
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
```
获取结构化输出。在构建功能前请先运行此命令，以了解已配置的资源。

Database —

npx @insforge/cli db

数据库 ——

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

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

Edge Functions —

npx @insforge/cli 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

```
npx @insforge/cli functions delete <slug>
```
— delete an edge function (with confirmation)

```
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 functions delete <slug>

—— 删除边缘函数（需确认）

Storage —

npx @insforge/cli 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

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

—— 下载文件

Deployments —

npx @insforge/cli 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

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

—— 取消正在进行的部署

Secrets —

npx @insforge/cli 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

)

```
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
```
恢复）

Schedules —

npx @insforge/cli 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

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

—— 查看执行日志

Diagnostics —

npx @insforge/cli diagnose

诊断 ——

npx @insforge/cli diagnose

Run with no subcommand for a full health report across all checks.

```
npx @insforge/cli diagnose
```
— full health report (runs all diagnostics)

npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] [--metrics <list>]

— EC2 instance metrics (CPU, memory, disk, network). Default range:

1h

npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] [--limit <n>]

— latest advisor scan results and issues. Default limit: 50

npx @insforge/cli diagnose db [--check <checks>]

— database health checks. Checks:

connections

slow-queries

bloat

size

index-usage

locks

cache-hit

(default:

all

)

```
npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]
```
— aggregate error-level logs from all backend sources. Default limit: 100

不带子命令运行将生成涵盖所有检查项的完整健康报告。

```
npx @insforge/cli diagnose
```
—— 完整健康报告（运行所有诊断项）
```
npx @insforge/cli diagnose metrics [--range 1h|6h|24h|7d] [--metrics <list>]
```
—— EC2实例指标（CPU、内存、磁盘、网络）。默认时间范围：
```
1h
```

npx @insforge/cli diagnose advisor [--severity critical|warning|info] [--category security|performance|health] [--limit <n>]

—— 最新的顾问扫描结果和问题。默认限制：50

npx @insforge/cli diagnose db [--check <checks>]

—— 数据库健康检查。检查项：

connections

slow-queries

bloat

size

index-usage

locks

cache-hit

（默认：

all

）

```
npx @insforge/cli diagnose logs [--source <name>] [--limit <n>]
```
—— 聚合所有后端来源的错误级别日志。默认限制：100

Logs —

npx @insforge/cli 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
.

```
npx @insforge/cli logs <source> [--limit <n>]
```
—— 获取后端容器日志（默认：20条）

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

来源名称不区分大小写：
postgrest.logs
与
postgREST.logs
效果相同。

Documentation —

npx @insforge/cli docs

文档 ——

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.

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

）

若要使用InsForge SDK编写应用代码，请改用insforge（SDK）技能，并使用
npx @insforge/cli docs <feature> <language>
获取特定的SDK文档。

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

函数调用URL：调用地址为

{oss_host}/functions/{slug}

—— 并非

/api/functions/{slug}

。当返回HTTP 400+状态码时，退出码为1。

密钥删除为软删除：标记密钥为非活跃，而非永久销毁。可通过

npx @insforge/cli secrets update KEY --active true

恢复。使用

secrets list --all

查看非活跃密钥。

存储桶删除为硬删除：永久删除存储桶及其中的所有对象。

db rpc使用GET或POST：无

--data

参数时使用GET；有

--data

参数时使用POST。

定时任务仅支持5字段cron：格式为

minute hour day month day-of-week

。不支持6字段（包含秒）的格式。请求头中可使用

${{secrets.KEY_NAME}}

引用密钥。

Common Workflows

常见工作流

Set up database schema

设置数据库架构

bash

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()
.

bash

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)"

关联用户表的外键：始终使用
auth.users(id)
。RLS当前用户：
auth.uid()
。

Deploy an edge function

部署边缘函数

bash

undefined

bash

undefined

Default source path: insforge/functions/{slug}/index.ts

默认源码路径：insforge/functions/{slug}/index.ts

npx @insforge/cli functions deploy my-handler npx @insforge/cli functions invoke my-handler --data '{"action": "test"}'

undefined

npx @insforge/cli functions deploy my-handler npx @insforge/cli functions invoke my-handler --data '{"action": "test"}'

undefined

Deploy frontend

部署前端

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

bash

undefined

在部署前请务必验证本地构建是否成功。本地构建调试速度更快，且不会浪费服务器资源。

bash

undefined

1. Build locally first

1. 先在本地构建

npm run build

2. Deploy

2. 部署

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_` | `PUBLIC_INSFORGE_URL` |
| SvelteKit | `PUBLIC_` | `PUBLIC_INSFORGE_URL` |

**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.)

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


**按框架区分的环境变量前缀**：

| 框架 | 前缀 | 示例 |
|-----------|--------|---------|
| 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`在本地执行成功
- [ ] 所有必需的环境变量已配置正确的框架前缀
- [ ] 边缘函数目录已从前端构建中排除（如适用）
- [ ] 切勿将`node_modules`、`.git`、`.env`、`.insforge`或构建输出包含在压缩包中
- [ ] 构建输出目录与框架预期的输出目录匹配（`dist/`、`build/`、`.next/`等）

Backup and restore database

备份与恢复数据库

bash

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

bash

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

Schedule a cron job

设置Cron任务

bash

undefined

bash

undefined

Create a schedule that calls a function every 5 minutes

创建每5分钟调用一次函数的定时任务

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>

undefined

npx @insforge/cli schedules logs <id>

undefined

Cron Expression Format

Cron表达式格式

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
`30 14 * * 1-5`	Weekdays at 2:30 PM

InsForge使用5字段cron表达式（pg_cron格式）。不支持包含秒的6字段表达式。

┌─────────────── 分钟 (0-59)
│ ┌───────────── 小时 (0-23)
│ │ ┌─────────── 日期 (1-31)
│ │ │ ┌───────── 月份 (1-12)
│ │ │ │ ┌─────── 星期 (0-6，周日=0)
│ │ │ │ │
* * * * *

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

Secret References in Headers

请求头中的密钥引用

Headers can reference secrets stored in InsForge using the syntax

${{secrets.KEY_NAME}}

json

{
  "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.

请求头中可使用

${{secrets.KEY_NAME}}

语法引用InsForge中存储的密钥。

json

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

密钥会在定时任务创建/更新时解析。若引用的密钥不存在，操作将返回404错误。

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

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

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

错误	解决方案
使用6字段cron（包含秒）	仅使用5字段格式： `minute hour day month day-of-week`
引用不存在的密钥	先通过密钥API创建密钥
目标函数不存在	在设置定时任务前验证函数是否存在且状态为 `active`
定时任务未运行	检查 `isActive` 是否为 `true` 且cron表达式有效

Recommended Workflow

Diagnose backend health

诊断后端健康

bash

undefined

bash

undefined

Full health report (all checks)

完整健康报告（所有检查项）

npx @insforge/cli diagnose

Check specific areas

检查特定领域

npx @insforge/cli diagnose metrics --range 24h # CPU/memory/disk over last 24h npx @insforge/cli diagnose advisor --severity critical # critical issues only npx @insforge/cli diagnose db --check bloat,slow-queries # specific DB checks npx @insforge/cli diagnose logs # aggregate errors from all sources

undefined

npx @insforge/cli diagnose metrics --range 24h # 过去24小时的CPU/内存/磁盘指标 npx @insforge/cli diagnose advisor --severity critical # 仅查看严重问题 npx @insforge/cli diagnose db --check bloat,slow-queries # 特定数据库检查项 npx @insforge/cli diagnose logs # 聚合所有来源的错误日志

undefined

Debug with logs

使用日志调试

bash

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

bash

npx @insforge/cli logs function.logs          # 函数执行问题
npx @insforge/cli logs postgres.logs          # 数据库查询问题
npx @insforge/cli logs insforge.logs          # API / 认证错误
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

函数问题先查看function.logs
- 检查执行错误、超时和运行时异常
查询问题使用postgres.logs
- 调试慢查询、约束违反和连接问题
API错误查看insforge.logs
- 认证失败、请求验证错误、通用后端错误

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`
General health / performance	`diagnose` (full report) or `diagnose metrics`
Database bloat / slow queries	`diagnose db`
Security / config issues	`diagnose advisor --category security`

问题	检查项
函数无法正常工作	`function.logs`
数据库查询失败	`postgres.logs` , `postgREST.logs`
认证问题	`insforge.logs`
API返回500错误	`insforge.logs` , `postgREST.logs`
整体健康 / 性能问题	`diagnose` （完整报告）或 `diagnose metrics`
数据库膨胀 / 慢查询	`diagnose db`
安全 / 配置问题	`diagnose advisor --category security`

Non-interactive CI/CD

非交互式CI/CD

bash

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

bash

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

link

.insforge/project.json

is created:

json

{
  "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.

在执行

create

或

link

后，会创建

.insforge/project.json

文件：

json

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

oss_host

是所有SDK和API操作的基础URL。

api_key

是用于后端API调用的管理员密钥。

切勿将此文件提交到版本控制系统或公开分享。请勿手动编辑此文件。使用
npx @insforge/cli link
切换项目。

insforge-cli

Original

Translation

InsForge CLI

InsForge CLI

Critical: Always Use npx (No Global Install)

重要提示：始终使用npx（请勿全局安装）

Global Options

全局选项

Exit Codes

退出码

Environment Variables

环境变量

Commands

命令

Authentication

身份认证

Project Management

项目管理

Database — npx @insforge/cli db

数据库 —— npx @insforge/cli db

Edge Functions — npx @insforge/cli functions

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

Storage — npx @insforge/cli storage

存储 —— npx @insforge/cli storage

Deployments — npx @insforge/cli deployments

部署 —— npx @insforge/cli deployments

Secrets — npx @insforge/cli secrets

密钥 —— npx @insforge/cli secrets

Schedules — npx @insforge/cli schedules

定时任务 —— npx @insforge/cli schedules

Diagnostics — npx @insforge/cli diagnose

诊断 —— npx @insforge/cli diagnose

Logs — npx @insforge/cli logs

日志 —— npx @insforge/cli logs

Documentation — npx @insforge/cli docs

文档 —— npx @insforge/cli docs

Non-Obvious Behaviors

非直观行为

Common Workflows

常见工作流

Set up database schema

设置数据库架构

Deploy an edge function

部署边缘函数

Default source path: insforge/functions/{slug}/index.ts

默认源码路径：insforge/functions/{slug}/index.ts

Deploy frontend

部署前端

1. Build locally first

1. 先在本地构建

2. Deploy

2. 部署

Backup and restore database

备份与恢复数据库

Schedule a cron job

设置Cron任务

Create a schedule that calls a function every 5 minutes

创建每5分钟调用一次函数的定时任务

Check execution history

查看执行历史

Cron Expression Format

Cron表达式格式

Secret References in Headers

请求头中的密钥引用

Best Practices

最佳实践

Common Mistakes

常见错误

Recommended Workflow

推荐工作流

Diagnose backend health

诊断后端健康

Full health report (all checks)

完整健康报告（所有检查项）

Check specific areas

检查特定领域

Debug with logs

使用日志调试

Best Practices

Database —
`npx @insforge/cli db`

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

Edge Functions —
`npx @insforge/cli functions`

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

Storage —
`npx @insforge/cli storage`

存储 ——
`npx @insforge/cli storage`

Deployments —
`npx @insforge/cli deployments`

部署 ——
`npx @insforge/cli deployments`

Secrets —
`npx @insforge/cli secrets`

密钥 ——
`npx @insforge/cli secrets`

Schedules —
`npx @insforge/cli schedules`

定时任务 ——
`npx @insforge/cli schedules`

Diagnostics —
`npx @insforge/cli diagnose`

诊断 ——
`npx @insforge/cli diagnose`

Logs —
`npx @insforge/cli logs`

日志 ——
`npx @insforge/cli logs`

Documentation —
`npx @insforge/cli docs`

文档 ——
`npx @insforge/cli docs`