> ## Documentation Index
> Fetch the complete documentation index at: https://platform.stepfun.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 命令行工具

`platform-cli` 是开放平台的命令行工具，可在终端中完成登录、空间切换、API Key 管理、用量查询与组织管理，适用于脚本化和批量操作的场景。控制台中常用的成员、项目、额度与用量管理均有对应命令。

## 安装

运行环境要求 Node.js 20.0.0 及以上版本。

```bash theme={null}
npm install -g @step.ai/platform-cli
```

安装完成后通过以下方式调用：

```bash theme={null}
platform-cli [command] [options]
```

任意命令追加 `-h` 可查看该命令的帮助文本，其中标注了命令的适用空间。

## 登录

```bash theme={null}
# 交互式选择登录方式
platform-cli auth login

# 通过浏览器授权登录
platform-cli auth login browser

# 通过短信验证码登录
platform-cli auth login sms --mobile <手机号>

# 通过短信验证码登录，指定国家代码，默认为 86
platform-cli auth login sms --mobile <手机号> --cc 86

# 查看当前用户与所处空间
platform-cli auth whoami

# 退出登录并清除本地会话
platform-cli auth logout
```

登录后始终进入个人空间。在非交互式环境中请显式指定登录方式，例如 `platform-cli auth login browser`，或 `platform-cli auth login sms --mobile <手机号> --code <验证码>`。

短信验证码登录需要后端签名凭证。CLI 按以下优先级加载：先读取环境变量 `PLATFORM_API_USER` 与 `PLATFORM_API_SECRET`，未设置时再读取 `~/.platform-cli/config.json` 中的 `apiUser` 与 `apiSecret` 字段。

## 空间

命令行的所有操作都在一个空间中进行，会话始终处于个人空间或某个组织空间。命令按适用空间划分，在不适用的空间下执行会失败并提示先切换空间。空间与组织的概念见[组织与项目](/docs/zh/guides/organization/overview)。

| 适用范围      | 命令                                    |
| --------- | ------------------------------------- |
| 仅个人空间     | `key`、`usage`、`rate-limit`、`voucher`  |
| 仅组织空间     | `org`、`org key`、`org usage`           |
| 仅组织空间的主账号 | 大部分 `org member` 与 `org project` 管理命令 |

```bash theme={null}
# 列出个人空间与您所属的全部组织
platform-cli auth space list

# 交互式切换空间
platform-cli auth space switch

# 切回个人空间
platform-cli auth space switch personal

# 切换到指定组织
platform-cli auth space switch <organizationId>

# 显示当前空间
platform-cli auth space current
```

## 个人空间命令

### API Key

管理个人账号的 API Key。个人空间下有且仅有一个默认 API Key，该 Key 不能更新或删除，`create` 用于创建额外的非默认 API Key。

```bash theme={null}
# 列出 API Key
platform-cli key list
platform-cli key list --json

# 创建非默认 API Key
platform-cli key create --name "my-key"

# 刷新默认 API Key 的 Secret
platform-cli key refresh --json

# 更新非默认 API Key 的名称，省略 --key-id 时进入交互式选择
platform-cli key update --key-id <id> --name "new-name"

# 删除非默认 API Key，省略 --key-id 时进入交互式选择
platform-cli key delete --key-id <id> --yes
```

### 用量与速率限制

查询 Step Plan 的用量记录与速率限制状态。

```bash theme={null}
# 显示当前用量窗口
platform-cli usage

# 按时间范围查询用量记录，时间参数为毫秒时间戳
platform-cli usage --start-time 1775836800000 --to-time 1775923200000 --page 1 --page-size 20 --json

# 显示当前速率限制摘要
platform-cli rate-limit
platform-cli rate-limit --json
```

### 代金券

```bash theme={null}
platform-cli voucher redeem <code>
```

## 组织空间命令

以下命令需先切换到组织空间。`org member` 与 `org project` 系列命令仅主账号可用；`org key` 操作的是您本人在各项目下的 API Key，任意组织成员均可使用。

### 成员管理

```bash theme={null}
platform-cli org member invite --phone <手机号>
platform-cli org member list --page 1 --page-size 20 --json

# 查看邀请记录
platform-cli org member invitations --json

platform-cli org member remove <userId> --yes
```

### 项目管理

```bash theme={null}
platform-cli org project list --page 1 --page-size 20 --json
platform-cli org project create <name> --description "text"
platform-cli org project update --project-id <id> --name "新名称" --description "text"
platform-cli org project delete <projectId> --yes
```

### 项目成员

```bash theme={null}
platform-cli org project member list --project-id <id> --json
platform-cli org project member add <userId...> --project-id <id>
platform-cli org project member remove <userId> --project-id <id> --yes
```

### 项目额度

`limit` 的 `<amount>` 单位为 Credit，取值 `0` 表示清除该项目的额度限制。额度规则见 [Credit 额度规则](/docs/zh/guides/organization/credits)。

```bash theme={null}
platform-cli org project credit --project-id <id> --json
platform-cli org project credit limit <amount> --project-id <id> --yes
```

### 项目下的 API Key

主账号通过以下命令管理项目下的全部 API Key，包括自己在该项目下创建的 API Key。`limit` 的 `<amount>` 取值 `0` 表示清除该 Key 所属成员在本项目内的额度限制。

```bash theme={null}
platform-cli org project key list --project-id <id> --json
platform-cli org project key limit <keyId> <amount> --yes
platform-cli org project key disable <keyId> --yes
platform-cli org project key enable <keyId>
```

### 组织额度与用量

```bash theme={null}
# 组织的额度订阅信息
platform-cli org subscribe --json

# 组织的用量明细，时间参数为毫秒时间戳
platform-cli org usage --from-time <ms> --to-time <ms> \
  --project-ids <id...> --uids <uid...> --model-id <id> \
  --page 1 --page-size 20 --json
```

### 本人在各项目下的 API Key

```bash theme={null}
platform-cli org key list --json
platform-cli org key create --project-id <id> --name "my-key"
platform-cli org key update --key-id <id> --name "new-name"
platform-cli org key delete --key-id <id> --yes
```

## 语言设置

```bash theme={null}
# 查看当前语言
platform-cli config language

# 设置语言
platform-cli config language <lang>

# 列出可用语言
platform-cli config language list
```