bpmax-cli

CLI for BPMAX multi-environment access, API key login bootstrap, and high-frequency project and flow operations.

Update

Check for a newer npm release without installing:

bpmax-cli update --check

Update an npm-installed CLI and sync bundled skills:

bpmax-cli update

The update command checks the npm registry for bpmax-cli, runs npm install -g bpmax-cli@<version> when auto-update is available, and then installs the bundled skills. Set BPMAX_CLI_REGISTRY_URL to use a private registry. Set BPMAX_CLI_NO_UPDATE_NOTIFIER=1 or BPMAX_CLI_NO_SKILLS_NOTIFIER=1 to suppress startup notices.

First-time setup

After installation, bpmax-cli prints an agent-oriented setup hint. The expected flow is: ask the user to directly input any BPMAX page URL in the target workspace, then run setup with that URL after the user replies.

For browserless agent environments such as OpenClaw, Aily, or Feishu-hosted assistants, prefer the device initialization flow:

bpmax-cli init \
  --agent openclaw \
  --channel feishu \
  --url https://example.com/w:store_mgr \
  --name retail \
  --format json

The command saves the profile, syncs bundled skills for the selected agent adapter, and returns a message_card with:

• authorization_url
• user_code
• expires_at
• next_action
• next_command

After the user confirms the code in BPMAX, complete authorization with:

bpmax-cli auth device complete --profile retail --session <device_code> --format json

For agent-driven use, ask the user for any BPMAX page URL in the target workspace, then run setup with that URL. The CLI extracts the environment origin and workspace from the URL and opens browser authorization without terminal prompts:

bpmax-cli setup http://127.0.0.1:10018/w:store_mgr --name local

To only create the profile and authorize later:

bpmax-cli setup http://127.0.0.1:10018/w:store_mgr --name local --skip-login
bpmax-cli auth login --profile local

Interactive setup is still available when running the CLI directly:

bpmax-cli setup

Browserless device authorization

Start a device authorization session without opening a local browser:

bpmax-cli auth device start \
  --profile retail \
  --agent openclaw \
  --channel feishu \
  --format json

The result includes a short user_code, authorization_url, session (same as device_code), and a channel-neutral message_card. This is the recommended path for OpenClaw-style agents embedded in Feishu or other chat surfaces. Agents should execute message_card.next_command after the user confirms the code.

Complete after the user confirms the code:

bpmax-cli auth device complete --profile retail --session <session> --format json

Local terminal users can still use the existing browser callback flow:

bpmax-cli auth login --profile retail

BPMAX web URLs

Generate common in-system URLs from the active profile origin and workspace:

bpmax-cli url workspace
bpmax-cli url project-list
bpmax-cli url project-detail 13094
bpmax-cli url project-step 13094 --step-id 15687 --format json

The default pretty output prints only the URL. Use --format json for structured fields such as kind, profile, origin, workspace, path, and url.

Project detail and create commands also attach a url field when the returned object includes a project id.

Project tasks

List pending steps assigned to the current user:

bpmax-cli project my-step --format table

Get project and step details:

bpmax-cli project get 13097 --format json
bpmax-cli step get 15690 --format json

Filter pending steps at the API query level instead of pulling all pages locally:

bpmax-cli project my-step --flow-type flow802926525 --format json
bpmax-cli project my-step --key-of-flow-node 'flow802926525::1776572829122' --format json

Use --flow-key when the target flow has a non-empty key. --flow-step-id maps to the backend node filter.

Create a project with an interactive form guide:

bpmax-cli project create --profile yuanrong --flow-id 123 --format json

project create uses the interactive guide by default. During the guide, choose "打开 BPMAX 表单页继续填写" to hand off to the web form. The CLI prints a PC URL and mobile path with the fields already entered encoded in init_value.

Use --no-interactive only for explicit direct-submit automation. If the target form template contains auto-init lambda scripts, the CLI still refuses direct submit and prints a web form handoff URL with reason: "form_template_auto_init_lambda".

ES fast queries

Use raw ES project search for high-volume reads, aggregations, budget summaries, trend analysis, and other reporting-style queries. Prefer ES aggregations over paging through project list and grouping locally.

bpmax-cli es project-search --profile yuanrong --body @query.json --format json

The body is passed to POST /api/project/raw-es-search unchanged:

{
  "data_set_key": "budget_project",
  "flow_type": "flow123",
  "flow_key": "",
  "body": {
    "size": 0,
    "query": { "match_all": {} },
    "aggs": {
      "by_status": { "terms": { "field": "status" } }
    }
  }
}

Profile recipes

Profile recipes are local, profile-scoped playbooks for environment-specific BPMAX operations. They live outside project repositories under:

~/.bpmax/profiles/<profile>/recipes/<workspace>/<recipe-name>/

Create a scaffold for the active profile and workspace:

bpmax-cli recipe init create-store-staff --title "创建店员"

List, inspect, or locate recipes:

bpmax-cli recipe list --format table
bpmax-cli recipe show create-store-staff --format json
bpmax-cli recipe path create-store-staff

Each recipe directory contains recipe.json, README.md, and payload.json. recipe.json is the machine-readable definition. payload.json can use {{variable}} placeholders, and @payload.json in command.argv means the file is read relative to the recipe directory, rendered, and passed as that argument value.

Example recipe.json:

{
  "version": 1,
  "name": "create-store-staff",
  "title": "创建店员",
  "description": "发起门店人员管理流程",
  "workspace": "store_mgr",
  "variables": [
    { "name": "name", "required": true },
    { "name": "phone", "required": true }
  ],
  "command": {
    "argv": ["project", "create", "--body", "@payload.json", "--format", "json"],
    "mutating": true
  }
}

Run a recipe with explicit variables. Mutating recipes require --yes:

bpmax-cli recipe run create-store-staff \
  --yes \
  --var name=杨小小 \
  --vars '{"phone":"18211223344","store_group_id":"817","store_name":"TMS测试门店"}'

Recipe execution is intentionally limited to bpmax-cli subcommands. It does not run arbitrary shell commands. --profile <profile> is injected into the child command when the recipe did not already specify it.

Skill distribution

The project-owned skills live under skills/.

Running npm install or npm run install:skills copies project skills into detected local agent skill directories, including:

• ~/.codex/skills
• ~/.claude/skills
• ~/.cc-switch/skills
• ~/.agents/skills
• ~/.gemini/skills

Only directories that already exist, or whose parent agent home exists, are targeted.

If aily-skillhub is available in PATH, the installer also runs:

aily-skillhub install --file-path <skill-directory>

for each bundled skills/bpmax-* directory.

For OpenClaw, pass an explicit agent:

node scripts/install-skills.mjs --json --agent openclaw

The installer first tries:

openclaw skills install --file-path <skill-directory>

If the OpenClaw CLI is unavailable or installation fails, it falls back to copying skills into ~/.openclaw/skills when OpenClaw is explicitly requested or ~/.openclaw already exists. Do not manually copy bundled skills for OpenClaw unless the installer reports a failure; the installer already tries both the OpenClaw CLI path and the fallback directory copy.