# @craftware/crafty-cli 中文文档

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

版本：0\.7\.0
npm 元数据更新时间：2026-10-31T20:47:44.812Z
中文译文更新时间：2026-10-31T21:23:57.792Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40craftware/crafty-cli
原文对照：https://npmcn.com/package/%40craftware/crafty-cli/?lang=original
项目主页：https://github.com/twocare/crafty/tree/main/sdk/cli#readme
源码仓库：https://github.com/twocare/crafty

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

- 包体积（解压后）：762 kB，221 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2026-06-21T03:12:25.768Z
- 最新版本发布：2026-10-31T20:47:44.638Z
- 已发布版本数：14（近 12 个月 14 个）

## 中文简介

巧手的CLI -创建项目指定的启动器(`crafty create`)被描述为前端在狡猾的托管

## 安装

```sh
npm install @craftware/crafty-cli
```

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

## README

# @craftware / crafty-cli

狡猾的托管命令行-部署你的前端构建到 **狡猾的托管** 用一个命令。 CLI与狡猾的CMS租户对话；底层托管提供程序是完整的 抽象的（你永远不会直接处理它）。

## 安装

```bash
npm i -g @craftware/crafty-cli
```

要求Node.js 20+。

## 创建一个新站点

```bash
npm create crafty@latest      # or: crafty create [dir]
```

复制一个官方启动器（今天是Astro，“sittio de servicios”），让你登录 您在浏览器（作用域）中的租户 `deploy crafty:read crafty:write crafty:publish`)，使用启动器的块类型、集合、 形式及演示内容(已发布； `--draft` 保存为草稿)，然后写作 `.env`， `crafty.json` 和 `src/crafty.types.ts`． 然后 `npm install && npm run dev`． 初学者住在 [`sdk/starters`](https://npmcn.com/package/%40craftware/starters)； `npm run templates` 副本 成 `templates/` （自动完成） `npm pack` / `npm publish`）。

## 快速启动

从你的前端项目（已经使用了Crafty API的项目）：

```bash
crafty login     # opens a browser to approve the CLI (OAuth device flow)
crafty init      # writes crafty.json (site + environment + build dir)
npm run build    # produce ./dist (framework-specific)
crafty deploy    # zips the build, uploads it, prints the live URL
```

命令行显示如下 `CRAFTY_API_URL` 从你的项目 `.env` 要知道哪个租户 ，这样就没有其他东西需要配置了。主机必须为您的 租户、站点和环境（在Crafty面板中），然后才能进行部署。

## 多个租户

命令行保持 **每个租户主机一个会话**，所以你要一直登录 马上给你的房客。每个项目的 `CRAFTY_API_URL` 选择存储的 使用会话-切换目录不会强制重新登录。登录到 没有进入其项目的租户 `crafty login --host=<url>`.

## 命令

| 命令 | 描述 |
| --- | --- |
| `crafty create [dir] [--url=<url> --template=<id> --name=<name> --site=<slug> --draft --yes]` | 在Crafty中从starter和它的站点创建一个项目(与 `npm create crafty`）. 看到 [创建一个新站点](https://npmcn.com/package/%40craftware/crafty-cli/#readme-start-a-new-site). |
| `crafty login [--host=<url>]` | 通过OAuth 2.0设备授权授权进行身份验证。没有 `--host`租客来自哪里 `CRAFTY_API_URL`． 令牌范围 `deploy`中的每台主机存储 `~/.crafty/credentials` (600)模式。 |
| `crafty init [--site=<slug> --environment=<env> --build-dir=<dir>]` | 创建 `crafty.json` 在项目中。 |
| `crafty deploy [dir] [--force]` | 打包并部署一个构建目录(默认： `buildDir` 从 `crafty.json`,即 `dist`）. 项目根目录、主目录和项目外的目录被拒绝，除非 `--force` 是过去了。 |
| `crafty status` | 显示项目最后一次部署的状态。 |
| `crafty types [--api-key=<key> --url=<url> --out=<file>]` | 为环境的集合和块类型生成TypeScript类型(默认输出： `crafty.types.ts`）. 看到 [内容类型](https://npmcn.com/package/%40craftware/crafty-cli/#readme-content-types). |
| `crafty skills list` / `crafty skills install [name…] [--global | --dir=<path>]` | 列出或安装Crafty代理技能(`.claude/skills` 默认情况下)。 |
| `crafty logout` | 撤销和删除当前项目租户的会话。 |
| `crafty update` （`crafty --update` / `-u`） | 在npm上将全局安装的CLI自动更新到最新版本。 |
| `crafty --version` / `crafty help` | 打印版本/用法。 |

## 内容类型

`crafty types` 为内容模型(集合和 块类型)，因此您的代码—以及您的编码代理—将停止 猜测场的形状：

```bash
crafty types                                  # uses CRAFTY_API_URL + CRAFTY_API_KEY from .env
crafty types --api-key=$STAGING_KEY --out=src/crafty.types.ts
```

-   这个 **环境来自API密钥**：分级生成的类型 关键描述分期。在更改集合或块类型后再生。
-   它使用公共环境API密钥(`X-API-Key`)，而不是 `crafty login` 会话。 `--url` / `CRAFTY_API_URL` 选择租户； `https` 是必需的 除了 `localhost`.
-   输出: `<Slug>Entry` 返回的每个集合（条目元数据+字段） `/collections/{slug}/entries`)， `<Slug>BlockData` 和 `<Slug>Block` 每一块 类型, `CraftyPageBlock` 工会（受歧视） `type`), `CraftyCollectionTypes` / `CraftyBlockDataTypes` 鼻涕虫映射，并共享 `CraftyEntryReference` / `CraftyMediaSummary`.
-   字段映射: `string`/`text`/`longText`/`url`/`datetime` → `string`， `number`/`decimal` → `number`， `boolean` → `boolean`， `select` →并集 它的选项值(一个带有 `multiple`)， `stringList` → `string[]`， `repeater` →项目对象数组，媒体引用→id加a `<key>_media` 文件摘要、集合参考→ `CraftyEntryReference` 在 块上的条目和引用的条目类型， `json` → `unknown`. 可选字段包括 `| null`.

```ts
import type { BlogEntry, CraftyPageBlock } from "./crafty.types";

const { data } = await crafty.entries.list("blog");
const posts = data as unknown as BlogEntry[];

const page = await crafty.pages.get("home");
for (const block of page.blocks as unknown as CraftyPageBlock[]) {
  if (block.type === "hero") {
    block.data.heading; // typed as HeroBlockData
  }
}
```

(通用SDK方法，如 `crafty.entries.list<"blog">()` 计划;直到 然后，将SDK响应转换为生成的类型。)

图式来自于 `GET /api/v1/schema` (JSON模式，版本由 `format_version`）; 命令行拒绝它不知道的格式-运行 `crafty update`.

## crafty.json

```json
{
  "site": "acme",
  "environment": "production",
  "buildDir": "dist"
}
```

集 `buildDir` 到框架的输出：Vite/CRA/Astro `dist`.js静态 出口 `out`, Nuxt `.output/public`， SvelteKit（静态适配器） `build`.

## 它如何解决上下文

1.  `CRAFTY_API_URL` 从项目来看 `.env` （或环境）→租户基础URL。
2.  `crafty.json` → `site`， `environment`， `buildDir`.
3.  `CRAFTY_TOKEN` 从过程环境（CI）中，或者，如果没有它， `~/.crafty/credentials` →为该租户主机存储的访问令牌。

## 从CI部署（GitHub Actions）

在CI中没有 `crafty login`． 属性创建个人访问令牌 `deploy` Crafty panel的范围(**完成→令牌**（作为租户管理员）和 将其作为 `CRAFTY_TOKEN`，连同… `CRAFTY_API_URL`. `CRAFTY_TOKEN` 是 只从环境中读书，从不从环境中读书 `.env`.

要在内容更改时重新部署，请在 **网站→ Integraciones→Webhooks** 使用格式 **GitHub的行为**， URL `https://api.github.com/repos/{owner}/{repo}/dispatches` 和一个 `Authorization: Bearer <token>` header（用于该存储库的细粒度GitHub令牌） **内容：读、写**）. 然后狡猾地发送了一个 `repository_dispatch` 与 `event_type: crafty-content` 和狡猾的有效载荷 `client_payload`;它的 测试ping使用 `crafty-ping`，它在不启动构建的情况下检查令牌。

```yaml
# .github/workflows/crafty-deploy.yml
name: Deploy to Crafty Hosting

on:
  push:
    branches: [main]
  repository_dispatch:
    types: [crafty-content]
  workflow_dispatch:

# Publishing 20 entries in a row sends 20 events: each new run replaces the
# pending one and cancels the one in progress, so only the last one deploys.
concurrency:
  group: crafty-deploy
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
        env:
          CRAFTY_API_URL: ${{ vars.CRAFTY_API_URL }}
          CRAFTY_API_KEY: ${{ secrets.CRAFTY_API_KEY }}
      - run: npx --yes @craftware/crafty-cli@latest deploy
        env:
          CRAFTY_API_URL: ${{ vars.CRAFTY_API_URL }}
          CRAFTY_TOKEN: ${{ secrets.CRAFTY_TOKEN }}
```

`github.event.client_payload` 承载事件(`event`， `site`， `environment`， `data.type`， `data.slug`，…)，如果构建需要知道什么 改变了。

为了安全起见，令牌只会被发送到发出令牌的主机， `https` 是 要求(除了 `localhost`), `.git`， `.env*`， `.envrc`， `.dev.vars`， `.npmrc`， `.netrc`， `.aws`， `.ssh`， `.crafty`， `id_rsa*`风格的钥匙, `*.pem`， `*.key`， `node_modules` 并且符号链接将从上传的构建中排除（不区分大小写）。

## 部署的URL和自定义域

成功的部署是在一个租户范围的子域上进行的 `{tenant}-{hash}.crafty.do`，每个环境一个（DNS + TLS自动设置）。 要使用自己的域，请将其添加到下面的Crafty面板中 **站点→主机**;它 返回要在DNS提供商处创建的CNAME记录。使用子域，例如 `www`，只创建该记录，并留下电子邮件记录（MX， SPF， DKIM， DMARC） 都没动。根域只有在DNS在Cloudflare上时才能连接；永远不要把 CNAME的根，因为它破坏了域的电子邮件。

## 代理技能

这个包发送狡猾的代理技能： `crafty-deploy` (此命令行：何时 运行 `login`/`init`/`deploy`， `buildDir` 每个框架，故障排除)和 `crafty-cms` （MCP服务器和SDK）。将它们安装在代理读取的位置 技能:

```bash
crafty skills list
crafty skills install              # ./.claude/skills (this project)
crafty skills install --global     # ~/.claude/skills (every project)
crafty skills install --dir=<path> # another agent's skills folder
npx @craftware/crafty-cli skills install   # without installing the CLI
```

再次运行它将替换已安装的副本，因此它也将它们更新为以下内容 CLI的版本。克劳德。ai和Claude Desktop，从 docs.crafty.do (`/skills/crafty-cms.zip`， `/skills/crafty-deploy.zip`), 将它们作为技能上传。

## 开发

```bash
npm install
npm run build      # tsc → dist
npm test           # builds, then runs node:test
npm run typecheck
```

## 出版

作为公共的、限定范围的包发布 `@craftware` org。 `publishConfig.access` 已经 `public` 和 `prepublishOnly` 重建 `dist`，所以不需要额外的标志。

**先决条件:** 的成员的NPM帐户 `craftware` Org与publish 权限，以及启用2FA设备。

```bash
# 1. authenticate
npm login
npm whoami

# 2. from this package, install exact deps and validate
cd sdk/cli
npm ci
npm test
npm run typecheck

# 3. preview the exact tarball (no upload)
npm publish --dry-run
#    expect: dist/**, skills/**, templates/**, LICENSE, README.md, package.json
#    (never src/, tests/ or node_modules/)

# 4. publish
npm publish            # add --otp=123456 if 2FA is enabled

# 5. verify
npm view @craftware/crafty-cli
npm i -g @craftware/crafty-cli && crafty --version
```

### 发布新版本

```bash
cd sdk/cli
npm version patch      # or minor / major — creates a commit + git tag
git push --follow-tags
npm publish
```

注:

-   一个给定的版本只能出版一次；如果有任何变化，请点击版本。
-   在预定的提交处从干净树发布。
-   这个 `crafty` 本是 `dist/bin/crafty.js` ( `#!/usr/bin/env node` 工作)。
-   `create-crafty` （`sdk/create-crafty`,什么 `npm create crafty` 运行)依赖于此 包的 `./create` export：先发布CLI，然后再发布 `create-crafty`.

## 常见问题

### @craftware/crafty-cli 是什么？

巧手的CLI -创建项目指定的启动器\(crafty create\)被描述为前端在狡猾的托管

### 如何安装 @craftware/crafty-cli？

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

### @craftware/crafty-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/craftware\_\_crafty-cli 是否存在。

### @craftware/crafty-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @craftware/crafty-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @craftware/crafty-cli 可以商用吗？

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

### @craftware/crafty-cli 还在维护吗？

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