# World CLI (`world`) 安装与接入指南

`world` 是 World Machine 的官方命令行工具，配合 `world-machine` Skill 可让 AI Agent 直接写入和召回双时态记忆与实体状态。

如果你正在使用支持指令执行的 AI Agent（如 Claude Code、Cursor、Trae、Antigravity 等），可以直接向它发送：

> 帮我安装 World CLI：`https://worldmachine.dev/cli-guide.md`

---

## 前置条件

- Go 1.27+（用于编译安装 `world` CLI）
- 如使用 `skills` CLI 自动安装 Skill，需要 Node.js（提供 `npx`）
- 一个 World Machine 控制台账号（<https://console.worldmachine.dev/>）

---

## 第一步：安装 `world` CLI 与 `world-machine` Skill

```sh
# 1. 安装 world CLI（Go 源码安装）
go install github.com/bootun/world-cli/cmd/world@latest

# 验证命令是否在 PATH 中
world --version
```

> 如果你的系统 PATH 中已有其他名为 `world` 的工具，可自行将二进制重命名或设置别名 `wm`。

安装配套 Agent Skill（推荐）：

```sh
npx -y skills add bootun/world-cli --skill world-machine -y
```

---

## 第二步：登录授权

支持两种认证方式，任选其一即可：

### 方式 A：浏览器一键授权（推荐）

```sh
world auth login
```

- 终端会自动打开浏览器前往 `https://console.worldmachine.dev/cli-auth`（若在远程/SSH 终端，可加 `--no-browser` 后手动复制链接在本地浏览器打开）。
- 登录控制台并点击「授权并连接 CLI」，控制台会生成一把专用 API 密钥并自动回传到本地 CLI。
- 若浏览器处于隔离网络无法回传，页面会直接给出 `world auth login --api-key "..."` 兜底命令，复制回终端执行即可。

### 方式 B：直接传入 API Key

在控制台 <https://console.worldmachine.dev/keys> 创建密钥后执行：

```sh
world auth login --api-key "<YOUR_API_KEY>"
```

---

## 第三步：验证安装与连通性

```sh
world auth status
```

确认输出中的 `Reachable: true` 且 `Valid Key: true`，即表示安装与认证完成。

---

## 第四步：快速验证读写

```sh
# 写入一条记忆（会自动附带本地 IANA 时区）
world remember "我偏好使用深色模式，开发语言主要是 Go。" --source cli

# 自然语言召回（支持 --json 供 Agent 解析）
world recall "我偏好什么开发语言？" --json

# 按历史时间点回溯
world recall "当时的项目状态是什么？" --as-of "2026-01-01" --json
```
