Apache Burr 常用 CLI 命令与工具详解

Apache Burr 0.42.0 CLI 命令详解:burr 主命令选项、burr-demo 演示服务、burr-test-case 测试用例生成及三个管理工具,含全部 help 回显与实测用例输出。

Apache BurrBurr2026/10/14

Apache Burr 常用 CLI 命令与工具详解

目标:以 burr 0.42.0(实际安装主体 apache-burr 0.42.0)为基线,详解 Apache Burr 随包安装的全部 7 个 CLI 命令入口,覆盖 Web UI 服务、演示服务、测试用例生成与发布管理工具,给出完整 help 回显与实测用例输出。以下命令与回显均在真实环境逐步实测(Ubuntu 22.04,Python 3.10.12)。

一、CLI 工具总览

burr[start] 安装完成后共提供 7 个命令入口,均位于虚拟环境 bin 目录:

命令对应入口函数作用
burrcli_run_server启动 Web UI 服务
burr-admin-servercli_run_server管理后台服务(与 burr 同一实现)
burr-democli_demo_server启动演示服务
burr-test-casecli_test_case生成测试用例
burr-admin-build-uicli_build_ui构建前端静态资源
burr-admin-generate-demo-datacli_generate_demo_data生成演示数据
burr-admin-publishcli_build_and_publish打包发布到仓库

版本说明:burr 未提供 version 子命令,实测 burr version 回显:

Usage: burr [OPTIONS]
Try 'burr --help' for help.

Error: Got unexpected extra argument (version)

版本查询请使用 pip show apache-burr。

二、burr 主命令:Web UI 服务

完整帮助实测回显:

Usage: burr [OPTIONS]

Options:
  --port INTEGER        Port to run the server on
  --dev-mode            Run the server in development mode
  --no-open             Run the server without opening it
  --no-copy-demo_data   Don't copy demo data over.
  --host TEXT           Host to run the server on -- use 0.0.0.0 if you want
                        to expose it to the network
  --backend [local|s3]  Backend to use for the server.
  --help                Show this message and exit.

启动命令:

burr --no-open --port 7241 --host 0.0.0.0

启动日志实测回显(关键行):

INFO | burr.cli.__main__:_run_server:170 - Starting server on port 7241
INFO | burr.cli.__main__:_run_server:178 - Copying demo data over to /root/.burr
INFO | burr.cli.__main__:_command:59 - Running command: /opt/burr-demo/.venv/bin/python3 -m uvicorn burr.tracking.server.run:app --port 7241 --host 0.0.0.0
INFO:     Uvicorn running on http://0.0.0.0:7241 (Press CTRL+C to quit)

服务端主要 HTTP 接口实测回显:

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:7241/ready
200

curl -s http://127.0.0.1:7241/api/v0/version
{"version":"0.42.0"}

项目列表接口 /api/v0/projects 返回 5 个项目:demo_counter、demo_chatbot、demo_conversational-rag、demo_chatbot_with_traces、burr-quickstart;/openapi.json 提供完整 API 文档,包含 /api/v0/{project_id}/{partition_key}/apps 等路径。验证结果:服务启动与接口访问正常。

三、burr-admin-server:管理后台服务

burr-admin-server 与 burr 指向同一入口函数 cli_run_server,帮助输出完全一致(见上文)。二者均用于启动 Web UI 服务,日常使用 burr 即可。

四、burr-demo:演示服务

完整帮助实测回显:

Usage: burr-demo [OPTIONS]

Options:
  --port INTEGER  Port to run the server on
  --help          Show this message and exit.

启动命令:

burr-demo --port 7243

启动日志实测回显(关键行):

INFO | burr.cli.__main__:_run_server:170 - Starting server on port 7243
INFO | burr.cli.__main__:_run_server:178 - Copying demo data over to /root/.burr
INFO | burr.cli.__main__:_command:59 - Running command: /opt/burr-demo/.venv/bin/python3 -m uvicorn burr.tracking.server.run:app --port 7243 --host 127.0.0.1 --reload
INFO:     Will watch for changes in these directories: ['/opt/burr-demo']
INFO:     Uvicorn running on http://127.0.0.1:7243 (Press CTRL+C to quit)
INFO:     Started reloader process [327] using StatReload
INFO:     Application startup complete.
INFO:     127.0.0.1:60098 - "GET /demos/chatbot/ready HTTP/1.1" 200 OK
INFO:     127.0.0.1:60104 - "GET /ready HTTP/1.1" 200 OK

演示服务以 127.0.0.1 为默认监听地址并启用 --reload 热重载,额外提供 /demos/<示例名>/ready 等演示应用端点,就绪检查返回 200。验证结果:演示服务正常。

五、burr-test-case:测试用例生成

完整帮助实测回显(click 框架在 ARGS 后附省略点表示参数可重复,此处按规范省略该标记):

Usage: burr-test-case [OPTIONS] COMMAND [ARGS]

  Test case related commands.

Options:
  --help  Show this message and exit.

Commands:
  create  Create a test case from a persisted state.

create 子命令帮助实测回显:

Usage: burr-test-case create [OPTIONS]

  Create a test case from a persisted state.

  Does two things:

  1. Pulls data specified and saves it/prints to console. 2. Prints a pytest
  test case to the console for you to cut and paste.

  See examples/test-case-creation/notebook.ipynb for example usage. See
  examples/test-case-creation/test_application.py for details.

  If you have custom serialization/deserialization then pass in the name of a
  python module, or a path to a python file, to import with your custom
  serialization/deserialization registration functions. This will be imported
  so that they can be registered.

  Note:     - when burr fails, then the state retrieved for a sequence ID is
  the state at the start of the sequence ID.       The fixture created will
  only have input state.     - when burr completes successfully, then the
  state retrieved for a sequence ID is the final modified state.       The
  fixture created will have input and output state, as we will grab the prior
  sequence ID's state       as the input state.     - we strip any keys
  prefixed with __ from the state to avoid exposing private keys in the test
  case.

Options:
  --project-name TEXT      Name of the project.  [required]
  --partition-key TEXT     Partition key to look at.
  --app-id TEXT            App ID to pull from.  [required]
  --sequence-id TEXT       Sequence ID to pull.  [required]
  --target-file-name TEXT  What file to write the data to. Else print to
                           console.
  --serde-module TEXT      Python file or fully qualified python module to
                           import for custom serialization/deserialization.
  --action-name TEXT       Provide name of the action for the test case.
                           Defaults to the action name at the sequence ID.
  --help                   Show this message and exit.

实测命令(基于快速入门应用落盘轨迹):

burr-test-case create --project-name burr-quickstart --app-id 1b853a06-13d9-44e2-83a0-55897f602302 --sequence-id 3 --target-file-name /tmp/tc.json

实测回显(关键行):

Action was successful so loading initial and expected state into test fixture.

Writing data to file /tmp/tc.json

Add the following to your test file:

import pytest
from burr.core import state
from burr.testing import pytest_generate_tests  # noqa: F401

@pytest.mark.file_name("/tmp/tc.json")
def test_summarize(input_state, expected_state):
    """Function for testing the action"""
    input_state = state.State.deserialize(input_state)
    expected_state = state.State.deserialize(expected_state)
    _, output_state = summarize(input_state)  # exercise the action
    assert output_state == expected_state

验证结果:--sequence-id 3 对应 summarize 动作,成功生成 pytest 测试用例并写出测试数据文件(生成代码中保留两处提示性注释,实际使用前按需替换)。

六、管理工具

6.1 burr-admin-build-ui

从源码构建 Web UI 前端静态资源,帮助实测回显:

Usage: burr-admin-build-ui [OPTIONS]

  Build the UI artifacts from source.

Options:
  --help  Show this message and exit.

6.2 burr-admin-generate-demo-data

为 Web UI 生成演示数据,帮助实测回显:

Usage: burr-admin-generate-demo-data [OPTIONS]

  generate demo data for the UI

Options:
  --s3-bucket TEXT         S3 URI to save to, will use the s3 tracker, not
                           local mode
  --data-dir TEXT          Local directory to save to
  --unique-app-names       Use unique app names
  --no-clear-current-data  Don't clear current data
  --help                   Show this message and exit.

--s3-bucket 指定时走 S3 跟踪器写入对象存储;--data-dir 指定本地目录;--unique-app-names 为每次生成使用唯一应用名;--no-clear-current-data 保留既有数据不清空。

6.3 burr-admin-publish

打包并发布到 PyPI 仓库,帮助实测回显:

Usage: burr-admin-publish [OPTIONS]

  Publishes the package to a repository

Options:
  --prod          Publish to pypi (rather than test pypi)
  --no-wipe-dist  Wipe the dist/ directory before building
  --help          Show this message and exit.

--prod 发布到正式 PyPI(默认测试 PyPI);--no-wipe-dist 在构建前不清空 dist/ 目录。验证结果:三个管理工具帮助信息均正常输出。

七、常见问题与参考链接