Developers · CLI

Cova CLI 使用指南

命令参考、登录凭证、脚本集成与常见问题。还没安装？先回 /cli 复制一键安装指令。

命令参考

命令面以 npm 包 covalink-mcp 的 cova 为准；标注「需登录」的命令未登录时退出码为 1。

cova login匿名可用

device flow 登录：终端打印登录链接、授权码与二维码，手机扫码或点开链接确认即完成。

--email <邮箱>与 --password 一起使用；无浏览器/服务器环境的账号密码登录
--password <密码>与 --email 一起使用

成功输出：已登录为 <用户名>

cova logout匿名可用

退出登录并清除本机凭证文件；未登录时执行仅清空本地文件，不报错。

成功输出：已退出登录

cova whoami需登录

查看当前登录账号：name / id / role / email。

--json输出原始 JSON

cova search <关键词>匿名可用

检索曲库曲目，输出 id / 标题 / 艺人 / 时长表格。匿名可用，无需登录。

--scene <场景>场景维度筛选，可重复传入
--mood <情绪>情绪维度筛选，可重复传入
--page <n>页码
--json输出原始 JSON

cova track <id>匿名可用

查看曲目详情：id / 标题 / 艺人 / 时长。匿名可用。

--preview附带试听地址
--json输出原始 JSON

cova playlists匿名可用

官方歌单列表，输出 id / 歌单 / 曲目数；--page 分页时每页 20 条。匿名可用。

--page <n>页码
--json输出原始 JSON

cova help匿名可用

打印全部命令与用法（cova --help 等价）。

登录与凭证

登录走 device flow：cova login 会打印登录链接、授权码和终端二维码，手机扫码或点开链接，在 /auth/device 页面确认授权。
凭证文件保存在 $XDG_CONFIG_HOME/covalink/credentials.json（缺省 ~/.config/covalink/credentials.json），权限 0600，仅本机使用，不上传第三方；路径可用环境变量 COVALINK_CREDENTIALS_PATH 覆盖。
访问令牌 2 小时有效、到期自动刷新；刷新令牌 30 天有效并自动轮换，过期后重新运行 cova login 即可。
无浏览器环境（服务器 / Docker / SSH）可用账号密码登录：cova login --email <邮箱> --password <密码>。
cova logout 会远程注销并删除本地凭证文件。

脚本化与 Agent 集成

CLI 默认输出人类可读表格；要喂给脚本或其他 Agent，用 --json 拿原始响应。

数据命令（whoami / search / track / playlists）加 --json 输出原始 JSON，便于管道给 jq 或其他程序消费。
环境变量 COVALINK_API_BASE 可覆盖默认 API 地址（默认 https://covalink.cn）；连接 staging：COVALINK_API_BASE=https://staging.covalink.cn cova search …。
失败统一走 stderr + 非零退出码：需登录命令在无凭证时提示「未登录。请运行 cova login」、凭证过期时提示「登录已过期」并要求重新 login；未知命令提示用法。
未全局安装时所有命令等价改写为 npx -y -p covalink-mcp cova <子命令>，效果一致。

示例：检索结果接 jq

cova search 古风 --scene 短视频 --json | jq '.tracks[].id'

能力边界

CLI 覆盖：扫码/账号登录、曲库检索、曲目详情与试听、官方歌单浏览、账号自检。
CLI 不覆盖：AI 生成音乐、自建歌单管理、下载结算、支付充值——这些走 MCP 工具（见 /mcp/guide）或直接在站点完成。
CLI 不开放：支付发起、管理后台与内部 Worker 接口；充值请前往官网定价页。

Agent 侧完整能力（生成、歌单、下载结算）见 MCP 使用手册；一键安装：curl -fsSL https://covalink.cn/cli/install.sh | bash

常见问题

安装后提示 cova: command not found？

npm 全局 bin 目录不在 PATH。执行 npm prefix -g 查看全局前缀（bin 在其下），把该目录加入 PATH 后重开终端；或干脆用 npx -y -p covalink-mcp cova <命令> 免安装运行。

Node.js 版本要求？

需要 Node.js 20 或更高版本。install.sh 会先自检版本，不满足会失败并提示升级；手动安装同样要求 Node 20+。

服务器上没有浏览器，怎么登录？

用账号密码登录：cova login --email <邮箱> --password <密码>。或者在本机跑 cova login 扫码后，把 credentials.json 复制到服务器同路径（权限保持 0600）。

如何连接测试环境（staging）？

命令前加环境变量：COVALINK_API_BASE=https://staging.covalink.cn cova login / cova search …。

cova CLI 和 Cova MCP 是什么关系？

同一个 npm 包 covalink-mcp 提供两个命令：cova 是给人/脚本用的命令行，covalink-mcp 是给 Agent 挂的 MCP server。登录态共用同一份本机凭证；Agent 侧的完整能力清单见 /mcp/guide。

如何卸载？

npm rm -g covalink-mcp，再删除凭证文件 ~/.config/covalink/credentials.json 即可。