tinet-cticloud-cli 0.1.6

Tinet CtiCloud OpenAPI CLI

CTICloud 命令行客户端，封装 OpenAPI 接口，与 CTICloud Wiki 中参数与响应一致，适合脚本化集成与 Agent 调用。

当前版本： 0.1.6
PyPI： https://pypi.org/project/tinet-cticloud-cli/

功能概览

子命令	说明
config	本地凭证管理
profile	多配置管理（支持多企业/环境切换）
agent	座席管理与座席操作
agent-login	座席服务端登录鉴权（区别于座席上线）
agent-report	座席报表查询
agent-status	座席实时状态查询
agent-tel	座席电话管理
area-code	号码归属地查询
asr	ASR 转写结果查询
cdr	任务话单/来电/外呼/webcall/sip/预测外呼等通话记录查询
data-manager	缓存数据管理
enterprise	企业信息查询
enterprise-hotline	企业号码列表查询
enterprise-setting	企业配置管理
enterprise-voice	企业语音文件管理
exten	分机管理
hybrid-group	号码池管理
investigation	满意度调查记录查询
ivr-router	呼入路由设置列表查询
monitor	平台监控与实时统计：座席/队列/话机/业务/中继监控；座席/满意度/队列实时统计
rasr	RASR 机器人对话事件查询
record	录音试听/下载
skill	技能与座席/队列关系查询
task	外呼任务全生命周期管理；号码导入与查询；任务批次列表/详情；运行中任务监控总览与详情
webcall	发起 webcall 呼叫

所有出站 HTTP 请求自动附加：

• X-CtiCloud-CLI-version: {版本号}（不参与 sign）
• X-TraceId: {UUID}（每次请求新生成，不参与 sign）

环境要求

• Python ≥ 3.10
• 运行时需访问 api-{region}.cticloud.cn
• 获取 CTICloud 企业id、部门 token

安装

从 PyPI 安装（推荐）：

pip install tinet-cticloud-cli
tinet-cticloud-cli --version   # 0.1.6
tinet-cticloud-cli --help

指定版本或升级：

pip install 'tinet-cticloud-cli==0.1.6'
pip install --upgrade tinet-cticloud-cli

macOS 等受限环境可使用 pipx：

pipx install tinet-cticloud-cli

配置凭证

0.1.5 breaking： 已移除运行时凭证环境变量（CTICLOUD_REGION / CTICLOUD_VALIDATE_TYPE / CTICLOUD_ENTERPRISE_ID / CTICLOUD_DEPARTMENT_ID / CTICLOUD_TOKEN）。请改用下方 config set，或 --profile / profile use。

配置文件：

# --validate-type：1 部门编号验证 2 企业编号验证
tinet-cticloud-cli config set \
  --region your_enterprise_region \
  --validate-type 2 \
  --enterprise-id your_enterprise_id \
  --token your_token

# 关闭本地文件日志（可选）
tinet-cticloud-cli config set --log false

多配置（profile）：

--profile 为可选全局参数。凭证解析优先级：

场景	使用的配置
不传 --profile（默认）	~/.cticloud/config.json
传入 --profile <name>	~/.cticloud/profile.json 中的指定 profile

单企业/单环境一般只需 config set，后续命令不必写 --profile。需要管理多组企业/环境时再用 profile：

# 创建 profile
tinet-cticloud-cli profile set --name prod \
  --region 1 --validate-type 2 \
  --enterprise-id your_enterprise_id \
  --token your_token

# 查看所有 profile
tinet-cticloud-cli profile list

# 本次命令临时使用指定 profile（不改 config.json）
tinet-cticloud-cli --profile prod task query --type 1

# 不传 --profile：使用 config.json
tinet-cticloud-cli task query --type 1

# 将 profile 完整覆盖写入 config.json，之后不传 --profile 即用该配置
tinet-cticloud-cli profile use prod

# 删除 profile（需确认）
tinet-cticloud-cli profile delete prod

profile 保存在 ~/.cticloud/profile.json，命名规则：^[a-z][a-z0-9-]{0,63}$。

快速示例

顺序与上方「功能概览」一致：config 置顶，其余按字母序。
枚举含义与 --help 一致；完整取值见各子命令 --help 或 Wiki。

# config
tinet-cticloud-cli config show

# profile（--profile 可选；不传则用 config.json）
tinet-cticloud-cli profile set --name staging --region 5 --enterprise-id E002 --token tok
tinet-cticloud-cli profile list
tinet-cticloud-cli profile use staging          # 写入 config.json 后，后续可不带 --profile
tinet-cticloud-cli task query --type 1          # 默认：config.json
tinet-cticloud-cli --profile staging task query --type 1   # 可选：临时指定 profile

# agent
tinet-cticloud-cli agent query --limit 10
tinet-cticloud-cli agent get --cno 2000
tinet-cticloud-cli agent login --cno 2000 --bind-tel [phone] --bind-type 1   # 1 电话 2 分机 3 webrtc
tinet-cticloud-cli agent create --cno 9001 --name 张三 --area-code 010
tinet-cticloud-cli agent update --cno 9001 --comment 备注
tinet-cticloud-cli agent preview-outcall --cno 9001 --tel your_tel
tinet-cticloud-cli agent preview-outcall-cancel --cno 9001

# agent-login / agent-report / agent-status / agent-tel
tinet-cticloud-cli agent-login authenticate --cno 9001 --pwd your_password
# --time-range-type：1 日报表 2 周报表 3 月报表 4 自定义时间
tinet-cticloud-cli agent-report agent-duration \
  --time-range-type 1 \
  --start-time 2026-07-01 --end-time 2026-07-01
tinet-cticloud-cli agent-status get --cno 9001
tinet-cticloud-cli agent-tel tel-list --cno 9001

# area-code / asr
tinet-cticloud-cli --json area-code get --tel [phone]
# --call-type：1 呼入 2 webcall 4 预览外呼 5 预测外呼 6 主叫外呼 9 内部呼叫
tinet-cticloud-cli --json asr get --call-type 4 --main-unique-id sip-xxx

# cdr（--start-time / --end-time 等为 Unix 秒级时间戳）
tinet-cticloud-cli cdr list-auto-task --start-time 1700000000 --start-time-end 1700086400
tinet-cticloud-cli --json cdr ib-query --start-time 1700000000 --end-time 1700086400

# data-manager / enterprise*
tinet-cticloud-cli --json data-manager --method get --key your_key   # set|get|delete
tinet-cticloud-cli --json enterprise get
tinet-cticloud-cli --json enterprise-hotline list-page --limit 10
tinet-cticloud-cli --json enterprise-setting list
tinet-cticloud-cli --json exten get --exten 8001
tinet-cticloud-cli --json hybrid-group list
tinet-cticloud-cli --json investigation query --limit 10
tinet-cticloud-cli --json ivr-router list

# monitor
tinet-cticloud-cli --json monitor agent --limit 10
tinet-cticloud-cli --json monitor enterprise-call-latest
# --queue-monitor-fields：queueParams,agentStatuses,queueEntries,agentSummary
tinet-cticloud-cli --json monitor queue --queue-monitor-fields queueParams --qnos 1000
tinet-cticloud-cli --json monitor statistics-queue

# rasr / record / skill / webcall
tinet-cticloud-cli --json rasr query --unique-id your-unique-id
tinet-cticloud-cli record get-info --record-file your-record-file.mp3
tinet-cticloud-cli --json record get-url --record-file your-record-file.mp3
tinet-cticloud-cli --json record get-batch-url --record-type record --record-file a.mp3,b.mp3
tinet-cticloud-cli --json skill list-relation --relation-type cno --name your-skill
tinet-cticloud-cli webcall --tel your_tel

# task
tinet-cticloud-cli task query --limit 10
tinet-cticloud-cli task monitor-tasks --status 2   # 1 运行中 2 暂停

全局 --json 输出 Wiki 原始 JSON；默认人类可读摘要，并对手机号、password / encryptPassword 等敏感字段脱敏。写操作可用全局 --dry-run 做本地校验与预览（不发写请求、不写本地配置），详见 --help。

帮助与 API 文档

安装后通过 --help 查看各子命令及参数（与 Wiki Query/Body 字段一一对应）：

tinet-cticloud-cli --help
tinet-cticloud-cli config --help
tinet-cticloud-cli profile --help
tinet-cticloud-cli agent --help
tinet-cticloud-cli agent login --help
tinet-cticloud-cli agent-login --help
tinet-cticloud-cli agent-report --help
tinet-cticloud-cli agent-status --help
tinet-cticloud-cli agent-tel --help
tinet-cticloud-cli area-code --help
tinet-cticloud-cli asr --help
tinet-cticloud-cli cdr --help
tinet-cticloud-cli cdr list-auto-task --help
tinet-cticloud-cli cdr ib-query --help
tinet-cticloud-cli data-manager --help
tinet-cticloud-cli enterprise --help
tinet-cticloud-cli enterprise-hotline --help
tinet-cticloud-cli enterprise-setting --help
tinet-cticloud-cli enterprise-voice --help
tinet-cticloud-cli exten --help
tinet-cticloud-cli hybrid-group --help
tinet-cticloud-cli investigation --help
tinet-cticloud-cli ivr-router --help
tinet-cticloud-cli monitor --help
tinet-cticloud-cli rasr --help
tinet-cticloud-cli record --help
tinet-cticloud-cli skill --help
tinet-cticloud-cli task --help
tinet-cticloud-cli webcall --help

OpenAPI 契约与字段说明见 CTICloud Wiki。