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: Session Start Checks

重要：会话启动检查

bash

insforge whoami    # verify authentication
insforge current   # verify linked project

If not authenticated:

insforge login

If no project linked:

insforge create

(new) or

insforge link

(existing)

bash

insforge whoami    # 验证身份验证状态
insforge current   # 验证关联的项目

如果未完成身份验证：

insforge login

如果未关联项目：

insforge create

（创建新项目）或

insforge link

（关联现有项目）

Global Options

全局选项

Flag	Description
`--json`	Structured JSON output (for scripts and agents)
`--project-id <id>`	Override linked project ID
`-y, --yes`	Skip confirmation prompts

标志	描述
`--json`	结构化JSON输出（适用于脚本和Agent）
`--project-id <id>`	覆盖已关联的项目ID
`-y, --yes`	跳过确认提示

Exit Codes

退出码

Code	Meaning
0	Success
2	Not authenticated
3	Project not linked
4	Resource not found
5	Permission denied

代码	含义
0	执行成功
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

身份验证

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

```
insforge login
```
— 支持OAuth（浏览器方式）或使用
```
--email
```
参数进行密码登录。详见references/login.md
```
insforge logout
```
— 清除已存储的凭证
```
insforge whoami
```
— 显示当前用户信息

Project Management

项目管理

```
insforge create
```
— create new project. See references/create.md
```
insforge link
```
— link directory to existing project
```
insforge current
```
— show current user + linked project
```
insforge list
```
— list all orgs and projects

```
insforge create
```
— 创建新项目。详见references/create.md
```
insforge link
```
— 将当前目录关联到现有项目
```
insforge current
```
— 显示当前用户及关联的项目
```
insforge list
```
— 列出所有组织和项目

Database —

insforge db

数据库 —

insforge db

```
insforge db query <sql>
```
— execute raw SQL. See references/db-query.md

insforge db tables / indexes / policies / triggers / functions

— inspect schema

```
insforge db rpc <fn> [--data <json>]
```
— call database function (GET if no data, POST if data)
```
insforge db export
```
— export schema/data. See references/db-export.md
```
insforge db import <file>
```
— import from SQL file. See references/db-import.md

```
insforge db query <sql>
```
— 执行原生SQL语句。详见references/db-query.md

insforge db tables / indexes / policies / triggers / functions

— 查看数据库架构信息

```
insforge db rpc <fn> [--data <json>]
```
— 调用数据库函数（无
```
--data
```
参数时用GET请求，有参数时用POST请求）
```
insforge db export
```
— 导出数据库架构/数据。详见references/db-export.md
```
insforge db import <file>
```
— 从SQL文件导入数据。详见references/db-import.md

Edge Functions —

insforge functions

边缘函数 —

insforge functions

```
insforge functions list
```
— list deployed functions
```
insforge functions code <slug>
```
— view function source
```
insforge functions deploy <slug>
```
— deploy or update. See references/functions-deploy.md

insforge functions invoke <slug> [--data <json>] [--method GET|POST]

— invoke function

```
insforge functions list
```
— 列出已部署的函数
```
insforge functions code <slug>
```
— 查看函数源代码
```
insforge functions deploy <slug>
```
— 部署或更新函数。详见references/functions-deploy.md

insforge functions invoke <slug> [--data <json>] [--method GET|POST]

— 调用函数

Storage —

insforge storage

存储 —

insforge storage

```
insforge storage buckets
```
— list buckets

insforge storage create-bucket <name> [--private]

— create bucket (default: public)

```
insforge storage delete-bucket <name>
```
— delete bucket and all its objects (destructive)

insforge storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort]

— list objects

insforge storage upload <file> --bucket <name> [--key <objectKey>]

— upload file

insforge storage download <objectKey> --bucket <name> [--output <path>]

— download file

```
insforge storage buckets
```
— 列出存储桶

insforge storage create-bucket <name> [--private]

— 创建存储桶（默认：公开访问）

```
insforge storage delete-bucket <name>
```
— 删除存储桶及其中所有对象（此操作不可恢复）

insforge storage list-objects <bucket> [--prefix] [--search] [--limit] [--sort]

— 列出存储桶中的对象

insforge storage upload <file> --bucket <name> [--key <objectKey>]

— 上传文件

insforge storage download <objectKey> --bucket <name> [--output <path>]

— 下载文件

Deployments —

insforge deployments

部署 —

insforge deployments

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

```
insforge deployments deploy [dir]
```
— 部署前端应用。详见references/deployments-deploy.md
```
insforge deployments list
```
— 列出所有部署记录
```
insforge deployments status <id> [--sync]
```
— 获取部署状态（
```
--sync
```
参数会从Vercel拉取最新状态）
```
insforge deployments cancel <id>
```
— 取消正在进行的部署

Secrets —

insforge secrets

密钥管理 —

insforge secrets

```
insforge secrets list [--all]
```
— list secrets (values hidden;
```
--all
```
includes deleted)
```
insforge secrets get <key>
```
— get decrypted value

insforge secrets add <key> <value> [--reserved] [--expires <ISO date>]

— create secret

insforge secrets update <key> [--value] [--active] [--reserved] [--expires]

— update secret

```
insforge secrets delete <key>
```
— soft delete (marks inactive; restore with
```
--active true
```
)

```
insforge secrets list [--all]
```
— 列出密钥（值会隐藏；
```
--all
```
参数会包含已删除的密钥）
```
insforge secrets get <key>
```
— 获取解密后的密钥值

insforge secrets add <key> <value> [--reserved] [--expires <ISO date>]

— 创建密钥

insforge secrets update <key> [--value] [--active] [--reserved] [--expires]

— 更新密钥

```
insforge secrets delete <key>
```
— 软删除（标记为非活跃状态；可通过
```
--active true
```
参数恢复）

Schedules —

insforge schedules

定时任务 —

insforge schedules

```
insforge schedules list
```
— list all scheduled tasks (shows ID, name, cron, URL, method, active, next run)
```
insforge schedules get <id>
```
— get schedule details

insforge schedules create --name --cron --url --method [--headers <json>] [--body <json>]

— create a cron job (5-field cron format only)

insforge schedules update <id> [--name] [--cron] [--url] [--method] [--headers] [--body] [--active]

— update schedule

```
insforge schedules delete <id>
```
— delete schedule (with confirmation)

insforge schedules logs <id> [--limit] [--offset]

— view execution logs

```
insforge schedules list
```
— 列出所有定时任务（显示ID、名称、cron表达式、URL、请求方法、活跃状态、下次执行时间）
```
insforge schedules get <id>
```
— 获取定时任务详情

insforge schedules create --name --cron --url --method [--headers <json>] [--body <json>]

— 创建定时任务（仅支持5字段cron格式）

insforge schedules update <id> [--name] [--cron] [--url] [--method] [--headers] [--body] [--active]

— 更新定时任务

```
insforge schedules delete <id>
```
— 删除定时任务（需确认）

insforge schedules logs <id> [--limit] [--offset]

— 查看执行日志

Logs —

insforge logs

日志 —

insforge logs

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

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

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

日志源名称不区分大小写：
postgrest.logs
与
postgREST.logs
效果一致。

Documentation —

insforge docs

文档 —

insforge docs

```
insforge docs
```
— list all topics
```
insforge docs instructions
```
— setup guide

insforge docs <feature> <language>

— feature docs (

db / storage / functions / auth / ai / realtime

typescript / swift / kotlin / rest-api

)

```
insforge docs
```
— 列出所有文档主题
```
insforge docs instructions
```
— 查看设置指南

insforge docs <feature> <language>

— 查看功能文档（支持功能：

db / storage / functions / auth / ai / realtime

；支持语言：

typescript / swift / kotlin / rest-api

）

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

insforge 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终止。

密钥删除为软删除：仅标记密钥为非活跃状态，不会彻底销毁。可通过

insforge secrets update KEY --active true

恢复。使用

secrets list --all

可查看非活跃密钥。

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

db rpc命令的请求方式：无

--data

参数时使用GET请求；有

--data

参数时使用POST请求。

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

分钟 小时 日期 月份 星期

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

${{secrets.KEY_NAME}}

引用密钥。

Common Workflows

常见工作流

Set up database schema

设置数据库架构

bash

insforge 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()
)"
insforge db query "ALTER TABLE posts ENABLE ROW LEVEL SECURITY"
insforge db query "CREATE POLICY \"public_read\" ON posts FOR SELECT USING (true)"
insforge 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

insforge 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()
)"
insforge db query "ALTER TABLE posts ENABLE ROW LEVEL SECURITY"
insforge db query "CREATE POLICY \"public_read\" ON posts FOR SELECT USING (true)"
insforge db query "CREATE POLICY \"owner_write\" ON posts FOR INSERT WITH CHECK (auth.uid() = author_id)"

关联用户表的外键：请始终使用
auth.users(id)
。行级安全策略中的当前用户：使用
auth.uid()
。

Deploy an edge function

部署边缘函数

bash

undefined

bash

undefined

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

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

insforge functions deploy my-handler insforge functions invoke my-handler --data '{"action": "test"}'

undefined

insforge functions deploy my-handler insforge functions invoke my-handler --data '{"action": "test"}'

undefined

Deploy frontend

部署前端应用

bash

npm run build
insforge deployments deploy ./dist --env '{"VITE_API_URL": "https://my-app.us-east.insforge.app"}'

Always build locally first. Env var prefix depends on framework:
VITE_*
,
NEXT_PUBLIC_*
,
REACT_APP_*
.

bash

npm run build
insforge deployments deploy ./dist --env '{"VITE_API_URL": "https://my-app.us-east.insforge.app"}'

请始终先在本地构建项目。环境变量前缀取决于使用的框架：
VITE_*
、
NEXT_PUBLIC_*
、
REACT_APP_*
。

Backup and restore database

备份与恢复数据库

bash

insforge db export --output backup.sql
insforge db import backup.sql

bash

insforge db export --output backup.sql
insforge db import backup.sql

Schedule a cron job

创建定时任务

bash

undefined

bash

undefined

Create a schedule that calls a function every 5 minutes

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

insforge 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

查看执行历史

insforge schedules logs <id>

undefined

insforge schedules logs <id>

undefined

Debug with logs

使用日志调试

bash

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

bash

insforge logs function.logs          # 排查函数执行问题
insforge logs postgres.logs          # 排查数据库查询问题
insforge logs insforge.logs          # 排查API/身份验证错误
insforge logs postgrest.logs --limit 50

Non-interactive CI/CD

非交互式CI/CD流程

bash

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

bash

INSFORGE_EMAIL=$EMAIL INSFORGE_PASSWORD=$PASSWORD insforge login --email -y
insforge link --project-id $PROJECT_ID --org-id $ORG_ID -y
insforge 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.

执行

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调用的管理员密钥。