紫外线
anvil-cli 是本地开发 Anvil 应用程序的命令行工具.
用来:
- 检查本地文件夹中的 Anvil 应用程序
- 在自己的编辑器中编辑代码
- 在您工作时保持本地文件夹与 Anvil 同步
- 在同一工作流程中切换本地代码编辑和Anvil设计器
安装
macOS 或 Linux 系统
curl -fsSL https://anvil.works/install-cli.sh | sh
Windows 电源壳
irm https://anvil.works/install-cli.ps1 | iex
视窗 CMD
curl -fsSL https://anvil.works/install-cli.cmd -o install.cmd && install.cmd && del install.cmd
手动 npm 安装
这需要您自己支持的Node.js安装(22,24或26 LTS).
npm install -g @anvil-works/anvil-cli@latest
安装者使用独立安装的节点.js 22,24或26 LTS可用. 如果节点缺失或不支持,安装会随设置指令而停止. 没有交互提示 .
为了允许安装者在需要时提供私人节点.js 24副本,请使用下面适当的命令.
macOS/ Linux : (中文(简体) )
curl -fsSL https://anvil.works/install-cli.sh | sh -s -- --install-node
动力壳:
& ([scriptblock]::Create((irm https://anvil.works/install-cli.ps1))) -InstallNode
CMD: (英语)
curl -fsSL https://anvil.works/install-cli.cmd -o install.cmd && install.cmd --install-node && del install.cmd
私人复制品存放在 ~/.anvil-cli 并添加到 PATH,所以其他节点工具也可能使用. 将安装器重运行更新到最新的"节点24"发布并迁移到更旧的捆绑的"节点20"安装.
运行 anvil update 以检查 CLI 和捆绑的节点更新。 如果捆绑的节点需要更新,它会显示重新运行的安装者命令.
快速启动
这是主要快乐的道路:
- 安装
anvil-cli。 。 。 . - 运行
anvil configure。 。 。 . - 运行
anvil checkout。 。 。 . - 更改为应用程序目录 .
- 运行
anvil watch。 。 。 .
1. 配置国家领导才能
运行 :
anvil configure
这个指引的设置帮助你:
- 设置默认的 Anvil 服务器 URL
- 如果您想要, 请选择首选编辑器
- 登录到 Anvil
如果您使用 anvil.works,您通常可以在提示时接受默认服务器.
2. 检查您的应用程序
运行 :
anvil checkout
这将打开一个交互式的应用程序拾取器并为您创建应用程序目录 .
如果您已经从 Anvil 编辑器获得应用程序 URL, 您也可以运行 :
anvil checkout https://anvil.works/build/apps/W36XUTXGNPDK6VEA my-app
cd my-app
您也可以通过 app ID 查看 :
anvil checkout W36XUTXGNPDK6VEA my-app --url anvil.works
cd my-app
3. 开始同步
在应用程序目录中, 运行 :
anvil watch
在你工作的时候别管了.
与 anvil watch 运行中 :
- 本地代码更改为 Anvil
- 在 Anvil 同步中所做的兼容的更改返回本地文件
- 需要的时候可以继续使用Anvil设计师
核心命令
这些命令对于当地正常发展最为重要:
anvil configure
为您的默认服务器 URL、 编辑器偏好和登录设置了指南 .
anvil configure
anvil checkout
从编辑器 URL, Git URL, app ID, 或交互式拾取器创建本地应用程序文件夹 .
anvil checkout [input] [directory]
anvil co [input] [directory]
常见的例子:
anvil checkout
anvil checkout https://anvil.works/build/apps/W36XUTXGNPDK6VEA my-app
anvil checkout W36XUTXGNPDK6VEA my-app --url anvil.works
anvil co -Q "dashboard"
有用的选项 :
-O, --open退出后打开应用程序文件夹-b, --branch <BRANCH>检查特定分支--git-url <GIT_URL>使用单独的 Git 服务器-Q, --query <QUERY>预装交互式搜索-u, --url <ANVIL_URL>明确选择 Anvil 安装-U, --user <USERNAME>明确选择登录账户-f, --force超越目的地安全检查
anvil create
创建空白的 Anvil 应用程序并在当地查看. 没有名字, CLI 提示一个。 服务器提供当前 Python 3 运行时默认值.
anvil create "My App"
anvil create "My App" ./my-app --tag internal sales
anvil create "My App" --directory my-app --url anvil.works --user [email protected]
anvil create "My App" --no-checkout --tag internal sales
有用的选项 :
-d, --directory <PATH>选择本地目录( 默认为应用名称, 空格被下划线替换)--no-checkout只创建远程应用程序并打印其ID和编辑器 URL--tag <TAG...>添加空格分隔标记或重复选项; 名称和目的地后的位置-u, --url <ANVIL_URL>选择 Anvil 安装-U, --user <USERNAME>选择登录账户--git-url <GIT_URL>使用单独的 Git 服务器-O, --open创建后打开检出
App名在包含空格时需要引用. 引出和后入的白地被去除;所剩名称被保留. 作为第二个参数提供目的地 --directory但不是两者皆有 目的地必须是空的,并且是在现有的 Git 仓库之外. 这些检查在创建远程应用程序之前运行 .
与 --no-checkout,没有创建或检查本地目录。 它不能与目的地论点结合起来, --directory, (中文(简体) ), --git-url,或 --open;这些组合在登录或创建前失败. JSON 输出包括应用ID,名称,服务器,账户,标签,以及 editorUrl字段.
标记是合并的,修饰的,小写的,并被分解. 一个应用程序最多可以有20个独特的标记,每个标记包含1到50个字母,数字,连字符,或下划线.
服务器和账户选择遵循 checkout,包括互动选择和在需要时登录。 在脚本中,提供名称和使用 --url 财务报告和审定财务报表 --user 当选择是模糊的. --json 禁用提示符 .
如果创建成功但检查失败,错误会识别所创建的应用程序并解释如何恢复. 不重运行 create,这将创建另一个应用程序。 JSON 错误包括创建的应用程序细节 data.created。在退出后未打开编辑器会生成警告并保存成功结果.
anvil watch
工作时保持本地应用程序文件夹与Anvil同步.
anvil watch [path]
anvil w [path]
常见的例子:
anvil watch
anvil watch -s
anvil watch -a
anvil watch -O
anvil watch --url anvil.company.com
有用的选项 :
-A, --appid <APP_ID>直接指定应用程序-s, --staged-only只同步已播放的文件-a, --auto自动处理一些分支并同步转换-O, --open打开您首选编辑器中的被监视路径-u, --url <ANVIL_URL>明确选择 Anvil 安装-U, --user <USERNAME>明确选择登录账户
anvil validate
在同步前或当CLI报告验证错误时检查 Anvil app文件或目录 .
anvil validate <path>
当给定文件时,命令从文件路径中选择验证符. 当给定目录时,它会递归验证该目录下支持的文件. 它支持:
anvil.yaml.yaml文件在client_code/,包括:client_code/**/form_template.yaml.html文件在client_code/,包括:client_code/**/form_template.html和模块形式client_code/<Form>.html.css文件在theme/assets/,包括:theme.css: 警告选择对象anvil-dropzone包装 这些警告不会失败验证; 一般 CSS 语法没有检查 ..py文件在client_code/财务报告和审定财务报表server_code/
常见的例子:
anvil validate anvil.yaml
anvil validate client_code/Form1/form_template.yaml
anvil validate client_code/Form1.yaml
anvil validate client_code/Form1/form_template.html
anvil validate client_code/Form1.html
anvil validate client_code/Helpers.py
anvil validate server_code/ServerModule.py
anvil validate theme/assets/theme.css
anvil validate .
HTML 验证解析模板 @anvil-works/form-template-parser,检查可选的 YAML 前题,并报告语义问题,例如重复的显式组件名称或无效组件类型.
Python 验证 anvil validate 命令使用捆绑的本地检查器 @anvil-works/anvil-ty 用于验证 Python 文件时的语义应用程序检查。 设定 ANVIL_TY 到可执行路径,以覆盖捆绑的检查器. ANVIL_TY_TIMEOUT_MS 设置以毫秒计的超时( 默认: 300 000) ,以及 ANVIL_API_STUBS_PATH 选择 Anvil API stub 目录。 方案 validatePath() API保持一个轻量级同步倒置,使用本地 Python 解释器检查语法(ANVIL_PYTHON, (中文(简体) ), uv, (中文(简体) ), python3,或 python进行基本形式结构检查.
验证从不获取依赖性 。 有依赖关系的应用程序使用现有的 .anvil/deps 缓存; 缺少、 不完整或配置匹配的缓存生成非致命警告, 并指示运行 anvil deps fetch。 。 。 .
当文件有效时, 命令会打印成功消息, 并带有状态退出 0。当文件无效时,它会打印路径特定验证问题,并带有非零状态退出.
使用 --json 与 anvil validate 为脚本或LLM工具发布结构化的 NDJSON 输出.
anvil convert-template
将 Anvil 格式模板 YAML 文件转换为 HTML 模板格式.
anvil convert-template client_code/Form1/form_template.yaml
anvil convert-template client_code/Form1.yaml
默认情况下, 命令会写入兄弟关系 .html 文件并删除源文件 .yaml 写入成功后的文件 :
client_code/Form1/form_template.yaml变成client_code/Form1/form_template.htmlclient_code/Form1.yaml变成client_code/Form1.html
有用的选项 :
-o, --output <path>写入特定输出路径-f, --force覆盖已存在的输出文件--keep-source保留源 YAML 文件
使用 --json 与 anvil convert-template 以释放源路径,输出路径,以及源 YAML 是否被删除.
转换用途 @anvil-works/form-template-parser当软件包符合条件时,例如 form:MyForm 或依赖性 item_template 值存在, 命令读取 anvil.yaml (和 .anvil/deps/manifest.json 在序列化 HTML 之前.
anvil test
运行您的应用程序的服务器测试( R)tests/server_tests在Anvil, 和打印pytest的输出 当它们运行.
anvil test
anvil test tests/server_tests/test_orders.py::test_refund
anvil test -k "login and not slow"
anvil test --collect-only
你检查过的测试结果HEAD这必须被推到安维尔。 如果你有未承诺的更改,命令警告你,它们不包括在内.
目标为路径或 pytest 节点ID in tests/server_tests,相对于当前目录. -k 使用 pytest 关键字表达式.
选择应用程序、服务器和账户为 anvil watch 选择它们,包括当有选择时问你。 在CI中,使用 -A, --appid <APP_ID>, (中文(简体) ), -u, --url <ANVIL_URL> 财务报告和审定财务报表 -U, --user <USERNAME> 当选择是模糊的. --json 禁用提示符 .
命令带有 pytest 退出代码, 例如 0 如果每次测试都通过 1 如果有任何失败,你可以在CI中使用. 如果运行无法启动或完成, 例如服务器运行时间未能启动, 它会打印出错误 1。按 Ctrl-C 取消运行.
其他有用的命令
anvil login
anvil login anvil.company.com
anvil logout
anvil config list
anvil config get <key>
anvil config set <key> <value>
anvil config reset
anvil validate <file>
anvil convert-template <file>
anvil test
anvil version
anvil update
anvil --help
anvil <command> --help
全球选项:
-V, --verbose显示详细输出--json用于脚本或 LLM 工具的输出 NDJSON
建议的工作流程
你的编辑和Anvil设计师的工作
基本循环是:
- 运行
anvil watch在您的应用程序文件夹中 . - 在编辑器中本地编辑 Python .
- 需要设计者时,在安维尔打开同样的应用程序.
- 保留
anvil watch在他们之间移动时运行.
默认使用分支
在开始观看前创建或切换到分支 :
git checkout -b my-feature
anvil watch
如果你一边看一边换分枝, anvil watch 可能提示您重新启动或再同步 。 如果你想让CLI自动处理,请使用:
anvil watch --auto
实验时只使用相机模式
如果您想要更严格控制 Anvil 的同步, 请使用 :
anvil watch --staged-only
git add server_code/MyModule.py
只有阶段文件会同步 .
与AI助手合作
一个简单的模式是:
- 开始
anvil watch。 。 。 . - 在 Cursor, VS 代码或另一个编辑器中打开应用程序文件夹 .
- 在当地制作或审查AI生成的更改.
- 在安维尔测试同步结果.
如果你在纠缠混乱的变化, 把这个和 --staged-only。 。 。 .
多个账户和企业安装
大多数用户在 anvil.works 不需要考虑这个问题.
如果工作跨越多个Anvil设施或多个登录账户,CLI通常可以推断出正确的选择. 如果无法,您可以用:
--url选择安特维尔安装--user选择登录账户
实例:
anvil login anvil.company.com
anvil checkout APPID my-app --url anvil.company.com
anvil watch --url anvil.company.com --user [email protected]
anvil logout --url anvil.company.com --user [email protected]
如果您想要永久更改默认服务器 :
anvil config set anvilUrl https://anvil.company.com
当你跑的时候 anvil login,CLI现在支持本地和无头流:
- 新闻
Enter打开默认浏览器 - 或复制打印的设备登录 URL 和代码,以便在您选择的浏览器中继续
对于 anvil login,更喜欢在文档和示例中的位置服务器参数:
anvil login anvil.company.com
--url 如有需要,也予以支持.
解决问题
anvil 找不到命令
再次尝试安装命令, 然后打开一个新的终端并运行 :
anvil --help
如果安装脚本失败, 请使用 npm 后退 .
登录或账户选择问题
尝试:
anvil login
anvil config list
如果您使用自备安装:
anvil login anvil.company.com
anvil checkout 找不到应用程序
尝试从 Anvil 编辑器直接使用应用程序 URL, 或通过 --url 财务报告和审定财务报表 --user 如果 CLI 查看错误的安装或账户.
安维尔没有出现本地变化
确保您在正确的应用目录中并重新启动 :
anvil watch
使用时 --staged-only,记住,只有文件同步.
Anvil 的更改没有在本地出现
确保 anvil watch 仍在运行。 如果表会话看起来不健康或者下面的分行状态发生变化,请停止,然后从正确的分行和app文件夹重新开始.
CLI 使用错误的服务器
检查您的当前配置 :
anvil config list
在需要时明确设定默认值 :
anvil config set anvilUrl https://anvil.company.com
配置文件
anvil-cli 存储本地设置 config.json。 。 。 .
共同地点:
- 马可斯:
~/Library/Preferences/anvil-cli/config.json - 林纳:
~/.config/anvil-cli/config.json - 窗口 :
%APPDATA%\\anvil-cli\\Config\\config.json
这包括下列设置:
anvilUrlpreferredEditorverbose
认证机密在可用时存储在OS键链中.
发展中国家 anvil-cli
构建 CLI :
pnpm build
以监视模式运行 :
pnpm dev
类型检查 :
pnpm tsc --noEmit
运行测试 :
source tests/setup-test-env.sh
pnpm test
运行一个测试文件 :
source tests/setup-test-env.sh
pnpm rstest tests/some.test.ts
许可证
麻省理工学院