@vibecape/cli

CLI for Vibecape Remote Space administration and extension development.

The npm package is scoped as @vibecape/cli, but the installed command is vibecape.

pnpm dlx @vibecape/cli extension init my-extension

Commands

vibecape login [--federation <url>] [--provider <id>]
vibecape users
vibecape users use <user-id>
vibecape logout [user-id]
vibecape server init
vibecape server start [--foreground]
vibecape server stop [--force]
vibecape server restart [--force]
vibecape server status
vibecape server group create --name <name> [--owner <user-id>]
vibecape server group member add <group-id> <user-id> --role editor
vibecape server group request list <group-id>
vibecape server group request approve <group-id> <user-id> [--role editor|viewer]
vibecape server group request reject <group-id> <user-id>
vibecape space create [directory] --group <group-url> [--name <name>]
vibecape space list --group <group-url>
vibecape space clone <space-id> [directory] --group <group-url>
vibecape space settings [directory]
vibecape extension init [directory] [options]
vibecape extension validate [directory]
vibecape extension build [directory]
vibecape extension pack [directory]

[directory] defaults to the current working directory.

Remote Space

Remote Space 沿用 Vibecape 的 Downcity Federation 登录。App 与 CLI 共用 ~/.vibecape/app.db 中的账户和当前用户。Token 直接保存在权限为 0600 的数据库中，不创建第二套 CLI credential。

升级自旧版 Electron safeStorage 账户结构时，旧账户会被清空而不会迁移 Token；用户需要重新登录一次。

vibecape login
vibecape users
vibecape users use <user-id>

export VIBECAPE_GROUP_URL=https://spaces.example.com/groups/group_...

用户在 Vibecape App 中通过 Group URL 提交申请。服务器管理员在 Vibecape Server 主机上审批，不需要 Federation 登录：

vibecape server group request list <group-id>
vibecape server group request approve <group-id> <user-id> --role editor

审批通过后，成员按 Space ID clone，不输入 Git URL 或 Space URL：

vibecape space list --group "$VIBECAPE_GROUP_URL"
vibecape space clone space_... ./my-space --group "$VIBECAPE_GROUP_URL"

Group 创建、申请审批、成员变更和 Owner 转移统一由服务器管理员通过 vibecape server group ... 完成；用户只在 App 中提交申请和查看状态。

space create 会初始化或复用当前 Git repository，维护 Vibecape 的 .gitignore 区块，解除 .downcity/ 与 .vibecape/ 的 Git 跟踪但保留本地文件，拒绝同步已被 Git 跟踪的 .env 文件，创建 checkpoint commit，然后把 main 推送到 Remote Space。连接信息保存在 Git remote 中，不创建 .vibecape/space.json。

Phase 1 允许普通图片进入 Git，但拒绝超过 20 MiB 的单文件；视频和大型附件需要等待后续 Git LFS 支持。

Local Server

本机首次启动时运行交互式初始化：

vibecape server init
vibecape server start

配置默认写入 ~/.vibecape/server.env，文件权限为 0600。初始化过程会询问 Federation URL、Bureau Token、City ID、监听地址、公开地址和数据目录；Bureau Token 不回显。运行时显式设置的同名环境变量优先于配置文件。

server start 在后台启动并等待健康检查通过，不占用当前终端。PID 和日志分别保存在数据目录的 server.pid、server.log；重复启动是幂等的。日常管理使用：

vibecape server status
vibecape server restart
vibecape server stop

vibecape server start --foreground 使用前台运行模式，适合开发调试，或交给 systemd、Docker、Dokploy 管理。进程无法通过健康检查确认时，stop 会拒绝杀死 PID；确认状态文件可信后可使用 stop --force。

Server 管理命令使用同一份配置：

vibecape server group create --name "Research Team"
vibecape server group member add <group-id> <user-id> --role editor
vibecape server group member list <group-id>
vibecape server group request list <group-id>
vibecape server group request approve <group-id> <user-id> --role editor
vibecape server group request reject <group-id> <user-id>

未显式提供 --owner 时，当前 Federation 用户自动成为 Group Owner。当前用户必须属于 Server 配置的同一 Federation 和 City。需要代其他用户创建时仍可传入 --owner <user-id>。

详细配置见 @vibecape/server README。

Quick start

pnpm dlx @vibecape/cli extension init my-extension \
  --id com.example.my-extension \
  --name "My Extension"
cd my-extension
pnpm install
pnpm run validate
pnpm run typecheck
pnpm run build

vibecape extension init

Creates a runnable extension project with a manifest, main action, renderer UI, TypeScript config, icon, README, and local CLI scripts.

vibecape extension init [directory]
  --id <reverse-domain-id>
  --name <display-name>
  --description <description>
  --force

The directory defaults to the current directory. A non-empty directory is rejected unless --force is passed. --force overwrites template-owned files but does not delete unrelated files.

Expected extension layout

my-extension/
  manifest.json
  package.json
  README.md
  tsconfig.json
  main/
    index.ts
  renderer/
    index.tsx
  assets/
  products/

Required files:

• manifest.json
• package.json
• main/index.ts

Optional files:

• renderer/index.tsx
• README.md
• assets/**
• products/*

The generated manifest.json references the public JSON Schema shipped by the SDK:

{
  "$schema": "./node_modules/@vibecape/extension-kit/manifest.schema.json"
}

vibecape extension validate

Checks the package shape and the same manifest contract used by the Vibecape app.

vibecape extension validate
vibecape extension validate ./extensions/feishu

Validation requires:

• manifest.json exists
• package.json exists
• all manifest fields conform to @vibecape/extension-kit/manifest
• paths stay inside the extension package
• removed fields such as permissions and agentPlugin are rejected
• package.json.version is a non-empty string

Successful output looks like:

Validated [email protected]

vibecape extension build

Builds an extension into dist/.

vibecape extension build

The build step:

• removes the previous dist/
• bundles main/index.ts to dist/main/index.js
• bundles renderer/index.tsx to dist/renderer/index.js when present
• extracts renderer slot contributions to dist/renderer/ui.json
• builds manifest.agent.plugin when configured
• builds any product packages under products/* that contain a package.json
• creates a versioned zip archive under dist/
• computes a sha256 for the archive
• writes dist/vibecape-extension.json with the GitHub Release descriptor contract

The renderer build treats React as a Vibecape runtime import, so extension renderer bundles do not vendor React.

vibecape extension pack

pack currently runs the same build pipeline as build.

vibecape extension pack

The output archive includes:

• release manifest.json
• package.json
• README.md when present
• assets/**
• built products/* files
• built dist/** files

Archive naming:

dist/<extension-id>-<package-version>.zip

GitHub Release descriptor

build and pack produce two assets for a GitHub Release:

dist/<extension-id>-<version>.zip
dist/vibecape-extension.json

The descriptor includes the full packaged manifest snapshot and archive sha256/size. Upload both files to a public GitHub Release using the exact archive name. Vibecape App Main resolves the public repository and latest stable Release directly; the CLI does not upload to Pages, R2, or the official catalog.

Renderer UI extraction

When renderer/index.tsx exists, the CLI imports the renderer in a build-time collector and executes the default renderer function:

import { defineRenderer } from "@vibecape/extension-kit/react";
import { PublishDialog } from "./PublishDialog";

export default defineRenderer(function render({ ui }) {
  ui.doc.menu.export({ title: "Publish" }).dialog(PublishDialog);
  ui.command.palette({ title: "Publish" }).run("feishu.publish");
});

That produces dist/renderer/ui.json:

{
  "contributions": [
    {
      "where": "doc.menu.export",
      "how": "dialog",
      "id": "publish",
      "title": "Publish",
      "component": "PublishDialog"
    },
    {
      "where": "command.palette",
      "how": "run",
      "id": "publish",
      "title": "Publish",
      "action": "feishu.publish"
    }
  ]
}

Components passed to slots must be exported from the renderer entry module so the CLI can serialize them by export name.

Manifest handling

The CLI reads manifest.json and package.json.

package.json.version is the release version. During packing, the CLI writes a release manifest whose entries point at built files:

{
  "main": "./dist/main/index.js",
  "renderer": "./dist/renderer/index.js"
}

Do not rely on a version field inside manifest.json; use package.json.version.

Local workspace development

Inside the Vibecape monorepo, official extensions can depend on workspace packages:

{
  "devDependencies": {
    "@vibecape/extension-kit": "workspace:*",
    "@vibecape/cli": "workspace:*"
  }
}

Extension scripts can still call the installed bin name:

{
  "scripts": {
    "validate": "vibecape extension validate",
    "build": "vibecape extension build",
    "pack": "vibecape extension pack"
  }
}

Troubleshooting

manifest.json not found

Run the command from the extension root or pass the directory explicitly:

vibecape extension validate ./extensions/feishu

Extension renderer must export default render function

renderer/index.tsx must default-export a function created with defineRenderer.

component must be exported from renderer entry

Export the component from renderer/index.tsx or pass a supported string component reference.

vibecape-extension.json is missing

Run vibecape extension build or vibecape extension pack from the extension root and upload the generated descriptor together with the archive.