# jky-cli

`jky-cli` 是一个用于调用吉客云开放平台 API 的命令行工具，采用 Go 语言开发，支持 Windows、macOS、Linux。

## 功能特性

- 支持**通用 API 调用**：`api call` 命令，任意接口只需提供 `method` 和 `bizcontent` JSON。
- 支持**业务模块命令**：提供商品、部门、公司等业务封装命令，提供参数校验和友好输出。
- 支持通过 `--json` 字符串或 `--file` 文件传入复杂业务参数。
- 自动处理签名、时间戳、公共参数。
- 支持接口文档查询：`docs` 命令可获取接口文档信息。
- 支持跨平台（Windows、macOS Intel/ARM、Linux）。

## 安装

### 方式：下载预编译二进制

从吉客云开放平台官网[下载页面](https://open.jackyun.com/developer/jkyuncli/jkyuncli.html)下载对应操作系统的压缩包，解压后得到可执行文件 `jky-cli`（Windows 下为 `jky-cli.exe`）。

建议将可执行文件所在目录添加到系统 `PATH` 环境变量，方便全局使用。



## 快速开始

### 1. 配置认证信息

首次使用前，需要配置你的吉客云开放平台应用的 appkey 和 appsecret：

```bash
./jky-cli configure
```

按提示输入 AppKey 和 AppSecret，凭证将保存在系统安全存储中（macOS 钥匙串 / Windows 凭据管理器）。

### 2. 查看帮助

```bash
./jky-cli --help
```

### 3. 通用 API 调用示例

以查询商品接口 `erp-goods.goods.getforqimen` 为例：

```bash
./jky-cli api call --method erp-goods.goods.getforqimen --json '{"goodsCode":"100","pageIndex":0,"pageSize":10}'
```

如果 JSON 较复杂，推荐使用文件方式：

```bash
# 创建 params.json
cat > params.json <<EOF
{
  "goodsCode": "100",
  "pageIndex": 0,
  "pageSize": 10
}
EOF

./jky-cli api call --method erp-goods.goods.getforqimen --file params.json
```

### 4. 业务模块命令示例

#### 查询商品

```bash
./jky-cli goods search --goodsno 100
```

#### 查询部门

```bash
./jky-cli depart search --name 销售部
./jky-cli depart search --code DEPT001
```

#### 查询公司

```bash
./jky-cli company query --companycode C001
./jky-cli company query --companyname 吉客云
```

## 命令列表

### configure

交互式配置 appkey 和 appsecret。

```bash
./jky-cli configure
```

### api call

通用 API 调用，完全由用户控制 method 和 bizcontent。

| 参数 | 说明 | 是否必填 |
|------|------|----------|
| --method | 接口方法名，如 erp.purch.create | 是 |
| --json | 业务参数 JSON 字符串 | 二者至少提供一个 |
| --file | 包含业务参数 JSON 的文件路径 | 二者至少提供一个 |

### goods search

查询商品（业务封装）。

| 参数 | 说明 | 是否必填 |
|------|------|----------|
| --goodsno | 商品编码 | 是 |

### depart search

查询部门（业务封装）。

| 参数 | 说明 | 是否必填 |
|------|------|----------|
| --name | 部门名称 | 否 |
| --code | 部门编码 | 否 |

### company query

查询公司信息（业务封装）。

| 参数 | 说明 | 是否必填 |
|------|------|----------|
| --companycode | 公司编码 | 否 |
| --companyname | 公司名称 | 否 |
| --busibrand | 业务品牌 | 否 |
| --fax | 传真 | 否 |
| --tel | 电话 | 否 |
| --pageindex | 页码 | 否 |
| --pagesize | 每页数量 | 否 |
| --companycodes | 公司编码列表 | 否 |

### docs

获取吉客云 CLI 的接口文档。

```bash
# 列出所有接口/jky-cli docs list

# 获取单个接口详细信息/jky-cli docs get --method erp-goods.goods.getforqimen
```

## 高级技巧

### 复杂参数推荐使用 --file

将庞大的 JSON 写入文件，避免命令行转义烦恼：

```bash
./jky-cli api call --method erp.purch.create --file ./purchase.json
```

### Windows PowerShell 用户注意

建议使用 `--file` 传递 JSON；如必须使用字符串，请用单引号包裹：

```powershell
./jky-cli api call --method erp-goods.goods.getforqimen --json '{"goodsCode":"100"}'
```

## 常见问题

**Q: 提示“未找到 appkey/appsecret”？**

A: 请先运行 `jky-cli configure` 完成配置。

**Q: API 返回签名错误？**

A: 检查你的 appkey 和 appsecret 是否正确，以及系统时间是否准确。

**Q: 如何获取开放平台的接口方法名和参数？**

A: 请参考吉客云开放平台官方文档：https://open.jackyun.com/developer/apidocinfo.html

**Q: 文件读取失败？**

A: 确保文件路径正确，或使用绝对路径指定文件位置：

```bash
./jky-cli api call --method erp-goods.goods.getforqimen --file /path/to/params.json
```


## 许可证

MIT License