# @anvil-works/anvil-cli 中文文档

规范地址：https://npmcn.com/package/%40anvil-works/anvil-cli/

版本：0\.8\.1
npm 元数据更新时间：2026-10-30T06:36:28.333Z
中文译文更新时间：2026-11-07T08:09:45.160Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40anvil-works/anvil-cli
原文对照：https://npmcn.com/package/%40anvil-works/anvil-cli/?lang=original
项目主页：https://anvil.works/docs
源码仓库：https://github.com/anvil-works/anvil-cli

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.6 MB，166 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：22 个
- 首次发布：2026-01-20T10:13:07.341Z
- 最新版本发布：2026-10-30T06:36:28.037Z
- 近 30 天下载量：1995（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：97（近 12 个月 97 个）

## 中文简介

本地开发 Anvil 应用程序的 CLI 工具

## 安装

```sh
npm install @anvil-works/anvil-cli
```

也可以使用：`pnpm add @anvil-works/anvil-cli`、`yarn add @anvil-works/anvil-cli`、`bun add @anvil-works/anvil-cli`

## README

# 紫外线

`anvil-cli` 是本地开发 Anvil 应用程序的命令行工具.

用来:

-   检查本地文件夹中的 Anvil 应用程序
-   在自己的编辑器中编辑代码
-   在您工作时保持本地文件夹与 Anvil 同步
-   在同一工作流程中切换本地代码编辑和Anvil设计器

## 安装

### macOS 或 Linux 系统

```bash
curl -fsSL https://anvil.works/install-cli.sh | sh
```

### Windows 电源壳

```powershell
irm https://anvil.works/install-cli.ps1 | iex
```

### 视窗 CMD

```cmd
curl -fsSL https://anvil.works/install-cli.cmd -o install.cmd && install.cmd && del install.cmd
```

### 手动 npm 安装

这需要您自己支持的Node.js安装(22,24或26 LTS).

```bash
npm install -g @anvil-works/anvil-cli@latest
```

安装者使用独立安装的节点.js 22,24或26 LTS可用. 如果节点缺失或不支持,安装会随设置指令而停止. 没有交互提示 .

为了允许安装者在需要时提供私人节点.js 24副本,请使用下面适当的命令.

macOS/ Linux : (中文(简体) )

```bash
curl -fsSL https://anvil.works/install-cli.sh | sh -s -- --install-node
```

动力壳:

```powershell
& ([scriptblock]::Create((irm https://anvil.works/install-cli.ps1))) -InstallNode
```

CMD: (英语)

```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 和捆绑的节点更新。 如果捆绑的节点需要更新,它会显示重新运行的安装者命令.

## 快速启动

这是主要快乐的道路:

1.  安装 `anvil-cli`。 。 。 .
2.  运行 `anvil configure`。 。 。 .
3.  运行 `anvil checkout`。 。 。 .
4.  更改为应用程序目录 .
5.  运行 `anvil watch`。 。 。 .

### 1\. 配置国家领导才能

运行 :

```bash
anvil configure
```

这个指引的设置帮助你:

-   设置默认的 Anvil 服务器 URL
-   如果您想要, 请选择首选编辑器
-   登录到 Anvil

如果您使用 `anvil.works`,您通常可以在提示时接受默认服务器.

### 2\. 检查您的应用程序

运行 :

```bash
anvil checkout
```

这将打开一个交互式的应用程序拾取器并为您创建应用程序目录 .

如果您已经从 Anvil 编辑器获得应用程序 URL, 您也可以运行 :

```bash
anvil checkout https://anvil.works/build/apps/W36XUTXGNPDK6VEA my-app
cd my-app
```

您也可以通过 app ID 查看 :

```bash
anvil checkout W36XUTXGNPDK6VEA my-app --url anvil.works
cd my-app
```

### 3\. 开始同步

在应用程序目录中, 运行 :

```bash
anvil watch
```

在你工作的时候别管了.

与 `anvil watch` 运行中 :

-   本地代码更改为 Anvil
-   在 Anvil 同步中所做的兼容的更改返回本地文件
-   需要的时候可以继续使用Anvil设计师

## 核心命令

这些命令对于当地正常发展最为重要:

### `anvil configure`

为您的默认服务器 URL、 编辑器偏好和登录设置了指南 .

```bash
anvil configure
```

### `anvil checkout`

从编辑器 URL, Git URL, app ID, 或交互式拾取器创建本地应用程序文件夹 .

```bash
anvil checkout [input] [directory]
anvil co [input] [directory]
```

常见的例子:

```bash
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 运行时默认值.

```bash
anvil create "My App"
anvil create "My App" ./my-app --tag internal sales
anvil create "My App" --directory my-app --url anvil.works --user me@example.com
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同步.

```bash
anvil watch [path]
anvil w [path]
```

常见的例子:

```bash
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文件或目录 .

```bash
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/`

常见的例子:

```bash
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 模板格式.

```bash
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.html`
-   `client_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的输出 当它们运行.

```bash
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 取消运行.

### 其他有用的命令

```bash
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设计师的工作

基本循环是:

1.  运行 `anvil watch` 在您的应用程序文件夹中 .
2.  在编辑器中本地编辑 Python .
3.  需要设计者时,在安维尔打开同样的应用程序.
4.  保留 `anvil watch` 在他们之间移动时运行.

### 默认使用分支

在开始观看前创建或切换到分支 :

```bash
git checkout -b my-feature
anvil watch
```

如果你一边看一边换分枝, `anvil watch` 可能提示您重新启动或再同步 。 如果你想让CLI自动处理,请使用:

```bash
anvil watch --auto
```

### 实验时只使用相机模式

如果您想要更严格控制 Anvil 的同步, 请使用 :

```bash
anvil watch --staged-only
git add server_code/MyModule.py
```

只有阶段文件会同步 .

### 与AI助手合作

一个简单的模式是:

1.  开始 `anvil watch`。 。 。 .
2.  在 Cursor, VS 代码或另一个编辑器中打开应用程序文件夹 .
3.  在当地制作或审查AI生成的更改.
4.  在安维尔测试同步结果.

如果你在纠缠混乱的变化, 把这个和 `--staged-only`。 。 。 .

## 多个账户和企业安装

大多数用户在 `anvil.works` 不需要考虑这个问题.

如果工作跨越多个Anvil设施或多个登录账户,CLI通常可以推断出正确的选择. 如果无法,您可以用:

-   `--url` 选择安特维尔安装
-   `--user` 选择登录账户

实例:

```bash
anvil login anvil.company.com
anvil checkout APPID my-app --url anvil.company.com
anvil watch --url anvil.company.com --user user@example.com
anvil logout --url anvil.company.com --user user@example.com
```

如果您想要永久更改默认服务器 :

```bash
anvil config set anvilUrl https://anvil.company.com
```

当你跑的时候 `anvil login`,CLI现在支持本地和无头流:

-   新闻 `Enter` 打开默认浏览器
-   或复制打印的设备登录 URL 和代码,以便在您选择的浏览器中继续

对于 `anvil login`,更喜欢在文档和示例中的位置服务器参数:

```bash
anvil login anvil.company.com
```

`--url` 如有需要,也予以支持.

## 解决问题

### `anvil` 找不到命令

再次尝试安装命令, 然后打开一个新的终端并运行 :

```bash
anvil --help
```

如果安装脚本失败, 请使用 npm 后退 .

### 登录或账户选择问题

尝试:

```bash
anvil login
anvil config list
```

如果您使用自备安装:

```bash
anvil login anvil.company.com
```

### `anvil checkout` 找不到应用程序

尝试从 Anvil 编辑器直接使用应用程序 URL, 或通过 `--url` 财务报告和审定财务报表 `--user` 如果 CLI 查看错误的安装或账户.

### 安维尔没有出现本地变化

确保您在正确的应用目录中并重新启动 :

```bash
anvil watch
```

使用时 `--staged-only`,记住,只有文件同步.

### Anvil 的更改没有在本地出现

确保 `anvil watch` 仍在运行。 如果表会话看起来不健康或者下面的分行状态发生变化,请停止,然后从正确的分行和app文件夹重新开始.

### CLI 使用错误的服务器

检查您的当前配置 :

```bash
anvil config list
```

在需要时明确设定默认值 :

```bash
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`

这包括下列设置:

-   `anvilUrl`
-   `preferredEditor`
-   `verbose`

认证机密在可用时存储在OS键链中.

## 发展中国家 `anvil-cli`

构建 CLI :

```bash
pnpm build
```

以监视模式运行 :

```bash
pnpm dev
```

类型检查 :

```bash
pnpm tsc --noEmit
```

运行测试 :

```bash
source tests/setup-test-env.sh
pnpm test
```

运行一个测试文件 :

```bash
source tests/setup-test-env.sh
pnpm rstest tests/some.test.ts
```

## 许可证

麻省理工学院

## 常见问题

### @anvil-works/anvil-cli 是什么？

本地开发 Anvil 应用程序的 CLI 工具

### 如何安装 @anvil-works/anvil-cli？

在项目目录运行 npm install @anvil-works/anvil-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 anvil，可以用 npx anvil 直接运行。

### @anvil-works/anvil-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @anvil-works/anvil-cli 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @anvil-works/anvil-cli 可以商用吗？

@anvil-works/anvil-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @anvil-works/anvil-cli 的下载量有多少？

根据 npm 官方下载统计，@anvil-works/anvil-cli 在 2026/10/06 – 2026/11/04 这 30 天内被下载 1,995 次，日均约 67 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @anvil-works/anvil-cli 还在维护吗？

最新版本 0\.8\.1 发布于 2026/10/30（8 天前）；至今共发布 97 个版本，其中过去 12 个月发布了 97 个；首次发布于 2026/01/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。