otterdrive

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Otter Drive

Use the installed

otterdrive

CLI as the only boundary for artifact operations. Do not access Cloudflare, D1, R2, deployment credentials, or storage objects directly.

将已安装的

otterdrive

CLI 作为制品操作的唯一边界。不要直接访问 Cloudflare、D1、R2、部署凭据或存储对象。

Establish context

建立上下文

Verify the executable and version:

bash

command -v otterdrive
otterdrive --version

If it is missing, require Node.js 24 LTS and install the official npm package:
bash
```
npm install --global otterdrive@latest
otterdrive --version
```
The official package is
```
otterdrive
```
and its repository metadata points to
```
https://github.com/otterware-app/otter-drive
```
. When developing the CLI itself inside a clean Otter Drive checkout, use
```
pnpm install --frozen-lockfile
```
,
```
pnpm --dir apps/cli build
```
, and
```
npm install --global ./apps/cli
```
. Preserve existing checkout changes and never replace them automatically.
Check authentication before doing work:
bash
```
otterdrive --json auth status
```
If login is required, ask the user to complete the human-controlled device flow:
bash
```
otterdrive auth login --url https://drive.otterware.app
```
Do not approve a device request on the user's behalf. For unattended agents, prefer a scoped organization API key supplied through
```
OTTERDRIVE_TOKEN
```
. Never print, commit, log, or place credentials in a prompt.

验证可执行文件和版本：

bash

command -v otterdrive
otterdrive --version

如果缺少该可执行文件，则要求使用 Node.js 24 LTS，并安装官方 npm 包：
bash
```
npm install --global otterdrive@latest
otterdrive --version
```
官方包名为
```
otterdrive
```
，其仓库元数据指向
```
https://github.com/otterware-app/otter-drive
```
。在干净的 Otter Drive 代码检出目录中开发 CLI 本身时，使用
```
pnpm install --frozen-lockfile
```
、
```
pnpm --dir apps/cli build
```
和
```
npm install --global ./apps/cli
```
。保留代码检出目录中已有的更改，绝不要自动替换这些更改。
开始工作前检查身份验证状态：
bash
```
otterdrive --json auth status
```
如果需要登录，请让用户完成由人工控制的设备授权流程：
bash
```
otterdrive auth login --url https://drive.otterware.app
```
不要代替用户批准设备授权请求。对于无人值守的 Agent，优先使用通过
```
OTTERDRIVE_TOKEN
```
提供的限定范围的组织 API key。绝不打印、提交、记录凭据，也不要将其放入提示词中。

Choose the team

选择团队

Inspect available organizations with
```
otterdrive --json organizations list
```
.
Treat
```
otterdrive organizations use <id>
```
as a persistent configuration change. Use it only when the intended workspace is clear.
Every artifact is visible to members of its organization; there is no private visibility mode.
A device-login token represents a user and may access artifacts in that user's organizations. Organization API keys are restricted to their organization.
Use
```
--profile <name>
```
for separate accounts or deployments. Put global options before the command for clarity.

使用
```
otterdrive --json organizations list
```
查看可用组织。
将
```
otterdrive organizations use <id>
```
视为持久性配置更改。仅在目标工作区明确无误时使用。
组织成员可以看到该组织内的所有制品；不存在私有可见性模式。
设备登录令牌代表一个用户，并且可以访问该用户所属组织中的制品。组织 API key 仅限于其所属组织。
使用
```
--profile <name>
```
管理不同的账户或部署。为清晰起见，应将全局选项放在命令之前。

Inspect before changing

更改前先检查

Resolve an artifact by ID or slug, then inspect its metadata and versions:

bash

otterdrive --json artifacts show <artifact>
otterdrive --json artifacts versions <artifact>
otterdrive --json artifacts files <artifact> --version <number>

Use

otterdrive artifacts read

for one file and

pull

for a full version. Prefer a temporary or explicitly approved destination when pulling; do not overwrite an existing working tree blindly.

通过 ID 或 slug 确定制品，然后检查其元数据和版本：

bash

otterdrive --json artifacts show <artifact>
otterdrive --json artifacts versions <artifact>
otterdrive --json artifacts files <artifact> --version <number>

使用

otterdrive artifacts read

读取单个文件，使用

pull

拉取完整版本。拉取时优先选择临时目录或明确获批的目标目录；不要盲目覆盖现有工作树。

Publish safely

安全发布

Use

create

only for a new artifact. It creates both the artifact and immutable version 1:

bash

otterdrive --json artifacts create <output-directory> \
  --slug <slug> \
  --title <title> \
  --label "Initial version"

The source may also be a single document. Publish

.md

.csv

.tsv

, and

.xlsx

files directly; Otter Drive provides a purpose-built browser preview for each format:

bash

otterdrive --json artifacts create ./report.xlsx \
  --slug quarterly-report \
  --title "Quarterly report" \
  --label "Initial workbook"

Publish a new immutable version of an existing artifact with

push

bash

otterdrive --json artifacts push <artifact> <output-directory> \
  --label <summary> \
  --if-version <observed-current-version>

Always use

--if-version

for agent-driven updates. If it conflicts, stop, re-read the latest artifact and versions, compare the competing work, and report the conflict. Never retry with a newer version number without understanding what changed.

Publish a curated build/output directory, not a repository root. Before upload, inspect all files recursively for secrets, environment files, credentials, source maps, caches, and unrelated content. The CLI uploads every regular file in the selected directory except

.DS_Store

and the metadata files

.otterdrive.json

and

.otterware.json

; it rejects symbolic links. Use

--entry

when the entry file is not

index.html

仅在新制品场景中使用

create

。它会同时创建制品和不可变版本 1：

bash

otterdrive --json artifacts create <output-directory> \
  --slug <slug> \
  --title <title> \
  --label "Initial version"

源也可以是单个文档。直接发布

.md

、

.csv

、

.tsv

和

.xlsx

文件；Otter Drive 为每种格式都提供了专用的浏览器预览：

bash

otterdrive --json artifacts create ./report.xlsx \
  --slug quarterly-report \
  --title "Quarterly report" \
  --label "Initial workbook"

使用

push

为现有制品发布新的不可变版本：

bash

otterdrive --json artifacts push <artifact> <output-directory> \
  --label <summary> \
  --if-version <observed-current-version>

Agent 驱动的更新始终使用

--if-version

。如果发生冲突，请停止操作，重新读取最新制品和版本，比较冲突的修改内容并报告冲突。绝不要在未了解变更内容的情况下使用更新的版本号重试。

发布经过整理的构建或输出目录，而不是仓库根目录。上传前，应递归检查所有文件，查找密钥、环境文件、凭据、source maps、缓存和无关内容。CLI 会上传所选目录中的每个普通文件，但不包括

.DS_Store

以及元数据文件

.otterdrive.json

和

.otterware.json

；它会拒绝符号链接。当入口文件不是

index.html

时，使用

--entry

。

Distinguish operations

区分不同操作

```
create
```
: create metadata and version 1 for a new artifact.
```
push
```
: upload content as a new immutable version.
```
update
```
: change title, description, or slug without publishing files.
```
move
```
: move an artifact and all immutable versions to another organization.
```
promote
```
: make an existing version current without rewriting it.
```
archive
```
/
```
restore
```
: change whether the artifact is active.

Before moving, inspect both organizations and confirm the intended destination. Moving requires a user device login with owner or admin access in both organizations; organization API keys cannot move artifacts. A move fails when the destination already has the artifact slug or an upload is pending:

bash

otterdrive --json artifacts move <artifact> <destination-organization>

Require clear user intent before moving an artifact, promoting an older version, or archiving an artifact. Do not simulate version edits: published versions and their files are immutable.

```
create
```
：为新制品创建元数据和版本 1。
```
push
```
：将内容上传为新的不可变版本。
```
update
```
：在不发布文件的情况下修改标题、描述或 slug。
```
move
```
：将制品及其所有不可变版本移动到另一个组织。
```
promote
```
：将现有版本设为当前版本，而不重写该版本。
```
archive
```
/
```
restore
```
：更改制品是否处于活跃状态。

移动前，检查两个组织并确认目标位置。移动操作要求使用用户设备登录，并且用户必须在这两个组织中均拥有 owner 或 admin 权限；组织 API key 无法移动制品。当目标组织中已存在相同 slug 的制品或仍有上传任务待处理时，移动操作会失败：

bash

otterdrive --json artifacts move <artifact> <destination-organization>

移动制品、将旧版本设为当前版本或归档制品前，必须获得明确的用户意图。不要模拟版本编辑：已发布的版本及其文件不可变。

Return useful results

返回有用的结果

Use root

--json

for automation and parse fields rather than terminal prose. After a mutation, report the artifact ID or slug, organization, resulting version, and preview URL. Do not expose authentication material in the report.

Read references/cli.md when exact command flags, environment overrides, or retrieval examples are needed.

对于自动化操作，使用根级

--json

并解析字段，而不是依赖终端文本。完成修改后，报告制品 ID 或 slug、组织、生成的版本以及预览 URL。不要在报告中暴露身份验证材料。

需要获取准确的命令标志、环境变量覆盖方式或检索示例时，请阅读 references/cli.md。