Canva CLI 是一个用于与 Canva REST API 进行直接、程序化交互的命令行工具,入口为 canva api 命令。它面向需要使用本地文件、脚本或编码智能体完成 Canva 操作的场景;对于纯粹依赖对话式交互的设计工作,则建议使用 Canva 的 AI 辅助流程,而非本工具。
安装与环境。使用前先检查 canva --version 是否成功;如果 CLI 不可用,需要说明其依赖 Node.js v24 和 npm v11。只有在用户明确要求或同意安装时,才执行 npm install -g @canva/cli@latest。
登录与账号。访问 Canva 资源前需确保目标用户已登录,执行 canva login,该命令会打开浏览器授权流程并要求用户确认。远程或无头环境可使用 canva login --mode manual。不要请求、打印、查看或复制本地存储的认证令牌。涉及多个 Canva 账号时,需由用户先指明目标 profile;对单次命令可用 --profile 指定,除非用户要求切换,否则不改变当前活动 profile。
发现操作。不要猜测命令、参数或请求结构。先运行 canva api --help,再按资源组缩小范围;用 canva api <group> <command> --help 查看参数;需要以 JSON 形式获取命令契约时使用 canva api describe <group> <command>。CLI 命令遵循 REST API 操作名,而不是 URL 路径。优先使用文档中列出的参数;仅当嵌套 JSON 载荷无法用参数表达时,才使用 --body @file.json。
认证与校验。命令以已登录的 Canva 账号身份执行,需要时运行 canva login。若请求返回 MISSING_SCOPE,应重新登录后再重试。对于创建、修改或上传内容的命令,在可用时先加 --dry-run 运行,以在不发出 API 请求的情况下校验参数与登录状态。发出状态变更请求前,确保目标设计、文件夹、素材或其他资源明确无歧义。
结果解读。请求到达 API 后,CLI 在标准输出返回一个 JSON 对象。先检查 ok 字段再判断是否成功:成功时使用 data 作为 API 响应;失败时报告 error.code、error.message 及相关 meta.status,不要臆造恢复方案。可将 next 视为可能的后续操作(例如登录),但执行前应确认建议的命令是否合适。若因参数无效或未知参数产生用法错误,应查阅 --help,而不是用猜测的参数重试。
异步操作。部分操作(包括素材上传)返回 job 而非已完成的资源。需保存返回的 job ID,短暂延迟后轮询对应的“Get job”命令;状态为 in_progress 时,在每次轮询之间采用指数退避,逐步增加等待时间,遵守接口速率限制,避免并发或紧循环轮询。状态变为 success 或 failed 时立即停止轮询。成功时返回结果资源 ID 和有用链接;失败时返回 job 错误并停止,除非用户要求,否则不重试原始请求。若在可用任务时间内 job 仍处于进行中,应报告其 job ID 和最新状态,便于之后再次检查。
汇报。总结所执行的操作、确切目标、结果以及有用的 ID 或 Canva URL。不要包含凭据、访问令牌或不必要的原始响应数据。
适用场景:需要以脚本或智能体方式调用 Canva REST API、处理本地文件、批量或程序化操作设计、文件夹与素材等资源的工作。限制:不适用于纯对话式设计创作;需要 Node.js v24 与 npm v11 环境;必须完成登录授权;异步任务需按轮询规则等待完成。详细安装、认证、profile 与 REST API 请求说明可参考官方文档。