CLI for Magic Builder (妙笔): publish HTML pages, create Feishu app bots, deploy FaaS functions, upload files, generate links, and install the Magic Builder Codex skill.

Install

npm install -g magic-builder

With Bun:

bun add -g magic-builder

The package provides three equivalent command names:

magic-builder --help
magic-cli --help
miaobi --help

You can also run it without installing:

npx magic-builder help
bunx magic-builder help

Update the CLI:

magic-builder update
magic-builder update --manager bun

update detects npm or Bun automatically; --manager is only for overriding.

Authentication

Most write operations need a Magic developer token.

magic-builder auth login

Manual token setup:

magic-builder auth set <token>
magic-builder auth show

Token lookup order:

--token
MAGIC_TOKEN
~/.magic-builder/magic-token
legacy ~/.magic-token
project .magic-token

CLI state is stored under:

~/.magic-builder/

This includes:

magic-token
magic-apps.json
widget-publish.json

Common Commands

Publish an HTML page:

magic-builder page publish app.html --title "Dashboard"

List or export pages:

magic-builder page list --scope mine
magic-builder page list --scope public --title demo
magic-builder page export --id <id> --out app.html

Delete a page:

magic-builder page delete --id <id>

Deploy a FaaS function:

magic-builder faas publish handler.js --name report-api

Create a Feishu app bot backed by Magic FaaS:

chmod 600 ./bot.credentials.json
magic-builder bot create \
  --handler ./bot.js \
  --name my_bot \
  --credentials ./bot.credentials.json

Pass --faas-id <existing-id> when updating an existing bot so its event callback URL stays unchanged.

Publish a Tools-only MCP service (ordinary HTTP handler may coexist):

magic-builder faas publish server.js --name weather-mcp --mcp --auth key,oauth --oauth-policy all
magic-builder faas mcp key create --id <id> --name production
magic-builder faas mcp key list --id <id>
magic-builder faas mcp key revoke --id <id> --key-id <key_id>
magic-builder faas mcp auth get --id <id>
magic-builder faas mcp auth update --id <id> --oauth-policy whitelist --oauth-user ou_xxx

List or delete FaaS functions:

magic-builder faas list
magic-builder faas list --title report
magic-builder faas delete --id <id>

Upload, list, or delete files:

magic-builder file upload logo.png
magic-builder file list
magic-builder file list --title logo
magic-builder file delete --id <id>

文件上传采用 sign -> PUT -> audit confirm 流程。预签名成功后会返回 audit_id，CLI 在对象上传完成后自动确认审计；确认失败时命令返回失败，重复执行确认不会新增审计记录。

Generate a Magic link:

magic-builder link create --title "Weekly Report"
magic-builder link create --fid <faas-id>

Submit Markdown to a People performance draft (perf is an alias):

magic-builder performance --review-url <people-review-url> --cookie ./cookie.txt --markdown ./performance.md
magic-builder perf --review-url <people-review-url> --cookie "$PEOPLE_COOKIE" --markdown "# Performance summary"
magic-builder perf --review-url <people-review-url> --cookie ./cookie.txt --markdown https://example.com/performance.md --dry-run

Cookie input accepts a raw Cookie header, a local path, or a Netscape cookie file. Markdown input accepts literal content, a local path, an HTTP(S) URL, or stdin. The command extracts x-f-csrf from the Cookie and does not print the Cookie in its output.

When --cookie and --cookie-file are omitted, performance automatically reads ./cookie.txt, matching the default output of extract-cookie:

magic-builder extract-cookie --curl-file ./request.curl
magic-builder performance --review-url <people-review-url> --markdown ./performance.md

With --review-url, the CLI loads the operator and tenant from /perf/api/user/settings, then reuses the current draft version, template, units, fields, source ids, and root review id from /perf/api/foundation/draft. Business ids are not hard-coded into the generated request.

Update the text fields in the self-review draft while preserving both rating fields and any omitted text:

magic-builder perf self-review --review-url <people-review-url> \
  --good "What went well" \
  --improve-file ./improvements.md \
  --values-comment-file ./values-comment.md
magic-builder perf self-review --review-url <people-review-url> --good-file ./good.md --dry-run

Each field can be provided as literal text or through its matching --*-file option. At least one field is required. The command reloads the latest self_review draft before every run and writes by default; --dry-run prints the payload without saving it.

Formally submit the latest draft to the current review stage:

magic-builder perf submit --review-url <people-review-url> --template-group-id <id> --dry-run
magic-builder perf submit --review-url <people-review-url> --template-group-id <id> --yes

The command posts to /perf/api/review/v2/stage. It always reloads the latest draft, derives the root review, template, stage, and work units from it, and serializes rich-text values into the stage payload. --template-group-id is optional when the draft already contains it. A real submission requires --yes; use --dry-run to inspect the payload first.

Extract Cookie from a copied curl command. This is a top-level general-purpose command. The default output is ./cookie.txt; the file is created with mode 0600:

magic-builder extract-cookie --curl-file ./request.curl
magic-builder extract-cookie --curl "curl 'https://example.com/...' -b 'foo=bar; token=value'"
cat ./request.curl | magic-builder extract-cookie --out-dir ./secrets

Create or append a Feishu document HTML Box:

magic-builder doc create --html app.html --title "Demo" # defaults to --edition external
magic-builder doc append --html app.html --doc-token <docx-token>
magic-builder doc create --html app.html --title "ByteDance Demo" --edition bytedance

Publish a document widget draft as a new app version:

magic-builder widget-publish \
  --app-id cli_a98afe875979500d \
  --block-type-id blk_6900429af84180025ce76527 \
  --change-log "修复 HTML Box 高度反馈循环"

The command reads Open Platform browser authentication from ~/.magic-builder/widget-publish.json by default:

{
  "cookie": "open_locale=zh-CN; session=...",
  "csrfToken": "...",
  "timezoneOffset": -480
}

Keep this file local and set its mode to 0600. Use --config <file> to select another file. The command fetches the widget detail, selects the latest uploaded test package before the existing draft/current package, updates the widget pkgId, increments the latest patch version, creates the app version with the application's actual default abilities and audit settings, and submits it for publishing. Use --version to override the generated version or --dry-run to inspect the payload without updating or publishing.

You can generate the local config directly from a browser-copied curl command:

magic-builder extract-cookie --curl-file ./widget-request.curl --widget-publish

This extracts only the Cookie and x-csrf-token, writes them to the default widget publish config with mode 0600, and does not print either secret.

Install or update the Magic Builder Codex skill:

magic-builder skill install
magic-builder skill check-update
magic-builder skill update

Skills are installed to ~/.agents/skills by default so Codex, Trae, Doubao, and other compatible agents can share them. Use --skills-root <dir> to override the destination.

Check local environment:

magic-builder version
magic-builder doctor
magic-builder config get

Help

All of these forms are supported:

magic-builder help
magic-builder help page
magic-builder page help
magic-builder page publish help
magic-builder man

--help, -h, and --man are also supported.

Global Options

--base-url, --magic-base-url <url>   Magic service base URL
--token <token>                      Auth token override
--format json|table|plain            Output format, default json
--quiet, -q                          Suppress progress messages
--version, -v                        Show version

Default Magic service: