@canva/ cli (英语)
CLI用于创建和管理Canva Apps,并与Canva合作.
目录
导言
@canva/cli 是用于创建和管理 Canva Apps 的命令行工具。 使用 @canva/cli 开始创建和测试您的应用程序。 Canva CLI允许您从命令行创建应用程序,使用Canva推荐的开发工具和模板,并从您的机器中与Canva合作.
了解更多应用开发,访问 正式文件。 。 。 .
所需资源
在使用 CLI 之前,请确定您有以下内容:
-
节点.js
v24 -
无
v11 -
A 类 坎瓦账户。 。 。 .
说明: 如果您正在使用 nvm 这样的版本管理器, 请运行
nvm install 24命令可确保您有正确的节点.js版本.
快速启动
以下命令使用 Canva CLI 创建新的 Canva 应用程序 .
npm install -g @canva/cli@latest
canva login
canva apps create "My New App" --template="hello_world" --distribution="public" --git --installDependencies
cd my-new-app
canva apps start
使用 Canva CLI
第1步:安装和登录
安装 Canva CLI 允许您从命令行创建新应用程序 .
要开始 :
-
在全球安装 Canva CLI .
npm install -g @canva/cli@latest -
登录到Canva CLI. Canva CLI 然后在您的浏览器中打开访问请求页面 .
canva login -
在浏览器中,单击 允许 允许 Canva CLI 访问 管理应用程序 并代表您进行设计 。 当您允许访问时, Canva CLI 生成一个认证符并在当地存储它. 有关认证符号的更多信息,改为: 证书存储和去除。 。 。 .
-
遵从终端的登录指令. 本地浏览器登录自动完成;如果CLI使用手动模式,将浏览器中显示的确认代码复制并粘贴到CLI中.
第2步: 创建您的应用程序
在登录到 Canva CLI 并授权后,您可以创建您的应用程序.
要创建新的应用程序 :
-
运行
canva apps create命令。 以下代码片段中的旗帜是可选的,您可以在应用程序创建过程中配置这些设置. 见 CLI 参考 每个旗帜的更多信息.canva apps create "My New App" --template="hello_world" --distribution="public" --git --installDependencies说明:在创建了应用程序后不能更改发行类型.
第3步: 预览您的应用程序
当您的新应用程序准备好, Canva CLI 自动打开 开发者门户 到您浏览器中的新应用程序配置页面。 然后可以继续预览和管理您的新应用程序 .
要预览您的应用程序 :
-
更改为您的新应用程序文件夹 .
cd my-new-app -
运行以下命令启动您的应用程序 .
canva apps start -
预览 URL 将在您的浏览器中生成并自动打开 .
-
如果这是第一次预览您的应用程序, 请单击 打开 预览您的新应用程序.
第4步:对您的应用程序进行健康检查
创建您的应用程序后, 您可以使用 :
canva apps doctor
检查缺失的依赖性、过时的软件包和其他问题.
注销、 认证令牌存储和删除
使用 canva login 命令,然后授予 Canva CLI 访问权限来管理您的 Canva 账户中的应用程序,一个认证符被加密并存储在您的机器上 。 令牌为未来请求提供认证,所以每次发送请求时不需要允许Canva CLI访问.
当你通过 Canva CLI 时 canva logout 命令,取消认证符号,并删除.
脚本位置
Auth 令牌位于您的家目录中 .canva-cli 文件夹.
如果使用多个 配置文件,每个文件都有自己的符号文件:
页:1 default 配置文件存储于 credentials,以及其中所有其它简介
profiles/<name>.json记录到一个特征 留下其他特征,
除非你通过 --all 以删除每一个.
删除托肯
要删除符号,有两个选项. 然而,只有 canva logout 命令撤销并删除符号。 如果有信使的复制件,可以使用信使将Canva CLI重新连接到你的账户的应用上.
注销
-
使用
canva logout命令取消访问并删除所存储的令牌.canva logout
手动删除文件
-
地点
credentials文件,它存储在以下位置:- macOS 和 Linux: 符号存储于
~/.canva-cli/credentials。 。 。 . - 窗口: 符号存储于
%USERPROFILE%\.canva-cli\credentials。 。 。 .
被命名的简介的托肯坐在旁边
profiles文件夹, 一个 JSON 文件每个配置文件. - macOS 和 Linux: 符号存储于
-
删除文件 。 要删除每个已存储的登录, 请删除整个
.canva-cli文件夹.
CLI 参考
安装后,您可通过运行使用 Canva CLI :
canva <command-name>
旗帜
适用于命令的顶级旗帜 :
--help: 显示命令和旗帜的帮助信息.--lite: 启用简化的 CLI 接口,以加强可访问性.--profile: 将命令作为已存储的名登录运行 。 见 配置文件。 。 。 .--version:显示CLI版本编号.
图标
欢迎
显示欢迎页和一般信息.
canva welcome
提示
为 Apps SDK 工作打印随机开发提示.
canva tip
- 别名数字 :
tips:还打印出随机的开发提示.
错误
向GitHub上的Canva CLI提出问题.
canva bug
登录
登录到Canva CLI.
canva login
- 旗帜数字 :
-
--china, (中文(简体) ),--cn: 登录到canva.cn, 这将使用canva.cn来进行所有后续的命令, 直到您登录结束 . -
--mode: 登录时使用的认证模式或流量.可用模式 :
"auto": 用途manual当远程运行时,如超超超超高频或容器,以及callback否则(违约)."callback":运行本地服务器以接收认证代码."manual": 提示您手动复制并粘贴认证代码 .
-
--profile: 将此登录保存在一个命名的配置文件下而不是当前 一,留下你的其他登录。 命令继续使用您的当前 在运行前配置canva profile switch。见 配置文件。 。 。 .
-
登录
退出 Canva CLI, 删除保存的认证符号 :
canva logout
只有您当前使用的配置文件受到影响 。 要登录不同的 一,说吧:
canva logout --profile work
以登录退出 配置文件 立即通过 --all逐一报告
配置文件
canva profile switch,并且只有在每个配置文件完整的情况下才能成功
记录完毕,所以局部失败仍然是失败:
canva logout --all
--all 财务报告和审定财务报表 --profile 无法合并,因为其中包含每个简介和
其他名字一个.
存储的代币总是从机器上被删除. CLI也要求坎瓦公司
撤销,但该部分需要一个工作连接: 如果请求失败
命令报告删除,警告该符号在过期前仍然有效,
并且失败了,因为你还没有完全登记。 仍然删除,所以
运行 canva logout 报告您没有登录.
- 旗帜数字 :
--all:记录每个存储的配置文件,而不仅仅是当前配置文件.--profile: 将命名的配置文件录出, 而不是当前的配置文件 .
配置文件
管理 CLI 可以运行的存储登录 。 每一个配置文件都有自己的认证 标志和它自己的 Canva 环境, 这样您可以保留一个登录 账户和测试账户的登录并肩并肩切换 不再登录.
canva profile <subcommand>
要删除一个配置文件, 请用 canva logout --profile <name>,或
全部删除 canva logout --all。 。 。 .
要创建配置文件, 请登录 :
canva login --profile work
canva profile switch work
接受任何命令 --profile <name> 一次就和一张相撞,
不更改所选择的配置文件 :
canva apps list --profile work
设置 CANVA_CLI_PROFILE 选择整个 shell 会话的配置文件,即
用于脚本和代理 :
CANVA_CLI_PROFILE=work canva apps list --print
当一个以上被设定的时候, --profile 赢了 CANVA_CLI_PROFILE,然后是
选择配置文件 canva profile switch,最终 default 简介.
配置文件名称可能包含字母、数字、连字符和下划线,必须开始 带有字母或号码,并可能长达64个字符长.
列表
显示每一个存储的登录, 并标记正在使用的登录 .
canva profile list
切换
制作 <name> profile 之后的命令运行为 。 选择一直持续到你
又换了.
canva profile switch work
离开 <name> 从存储的登录中选择:
canva profile switch
交互列表在命令当前运行的配置文件上设置可视标记 .
请注意: --profile 财务报告和审定财务报表 CANVA_CLI_PROFILE 两者都推翻了这个配置 如果使用其中之一
选项,选择标记的配置可以使覆盖永久.
交互切换器在无头运行时无效 .
微调
启动 Canva MCP 磁共振 服务器。 这通常由您的 MCP 客户端调用,例如 Claude D桌面, Cursor, 或其他相容的工具. 关于如何配置您的 MCP 客户端以使用 Canva Dev MCP 服务器的更多信息,请参见 Dev MCP 服务器 在开发者文档中.
api 密码
打电话 Canva REST APIs (英语) 使用您的 Canva CLI 登录 。 命令按其行动资源分组,例如 canva api designs create,以及 --help 每个级别都努力显示可用的团体、命令和旗帜。 关于从CLI中获取REST API请求的更多信息,请参见: 制作 Canva REST API 的 CLI 请求 在开发者文档中.
每一次通话都会写一个JSON的标语 而不是其他的 所以输出可以直通 jq 或由代理人阅读。 缺少参数和未知的标记会打印一个用法错误来代替该对象 .
canva api designs get DAF123abc
canva api designs get --design-id DAF123abc
canva api designs create --design-type preset --design-type-name presentation --title "Q3 Review"
canva api designs get DAF123abc --dry-run
canva api designs list | jq '.data.items[].id'
路径参数可以作为位置参数或标记传递,例如 --design-id。每个查询参数和请求正文字段也是一面旗;运行 canva api <group> <command> --help 看到他们.
您可以使用操作旗( 建议) 或使用 --body 当旗帜无法表达嵌入式有效载荷时:
canva api designs create --body @payload.json
--body 也接受内置 JSON,或 - 读取 stdin。 它只用于派遣JSON请求机构的行动。 上传文件的操作, 例如 canva api assets create-upload,带 --file 换句话说.
- 旗帜数字 :
--dry-run: 验证参数并打印响应对象而无需发送请求.--body: 请求机构为@path/to/file.json内置JSON,或-为斯丁。 当操作旗无法表达有效载荷时使用此功能.--file: 从文件的字节请求正文, 或-为斯丁。 仅用于上传文件的操作 .
成功实例输出 :
{
"ok": true,
"data": {
"design": {
"id": "DAF123abc"
}
},
"next": [],
"meta": {
"status": 200,
"durationMs": 12
}
}
当一个电话失败, error 替换 data 并携带 code 财务报告和审定财务报表 message, (中文(简体) ), meta.status 是 HTTP 状态(或 0 ——当时没有提出请求 next 建议运行的命令,例如 canva login 当存储的符号缺少一个瞄准镜时.
如果您登录的CLI版本比 api 命令,运行 canva login 因此,您存储的标志 带有 REST API 瞄准镜.
说明
将一个 REST API 命令的合同显示为 JSON:它的方法和路径,它所需要的范围和能力,每个旗帜都有它的概要,速率限制,一个链接到参考文档,以及通常遵循它的命令.
canva api describe designs get
canva api describe exports create
请求
向 REST 路径发送原始请求 。 将此用于终点 canva api 没有生成命令。 每个 HTTP 方法有一个命令 : get, (中文(简体) ), post, (中文(简体) ), put, (中文(简体) ), patch,以及 delete。 。 。 .
canva api get /v1/users/me
canva api get "/v1/designs?query=Q3"
canva api post /v1/designs --body @body.json
canva api post /v1/asset-uploads --file ./photo.jpg --header "Asset-Upload-Metadata: {\"name_base64\": \"cGhvdG8=\"}"
- 旗帜数字 :
--body: 请求机构为@path/to/file.json内置JSON,或-为斯丁。 仅在post, (中文(简体) ),put,以及patch。 。 。 .--file: 从文件的字节请求正文, 或-为斯丁。 仅在post, (中文(简体) ),put,以及patch,不能与--body。 。 。 .--header: 一个额外的请求头作为'<name>: <value>'. 重复旗为一多.
应用程序
管理您的 Canva 应用程序 .
canva apps
创建
创建 Canva 应用程序 .
canva apps create "My New App" --template="hello_world" --distribution="public" --git --installDependencies
- 参数数字 :
name: 设置应用程序的名称, 例如canva apps create "My New App"。 。 。 .
- 旗帜数字 :
-
--template:指定应用程序的起始模板。 模板是预建的起步项目,展示常用案例和最佳做法. 关于现有模板的完整清单,见 应用程序模板。 。 。 . -
--distribution:设置应用程序的发行类型.可用类型 :
-
"public":供所有Canva用户使用,但须接受Canva审查. -
"private": 仅供您的团队使用 企业计划,并需要团队管理员批准.说明: 创建新应用程序后, 您无法更改分发设置
canva apps create命令.
-
-
--git: 初始化项目目录中的 Git 寄存器. -
--installDependencies:在应用创建过程中自动安装必要的npm依赖. -
--strict:在生成的项目中使用严格的 Canva app 林入配置. -
--optionalConfig: 项目目录中要创建的可选配置文件.可用的选项 :
"vscode": 添加一个.vscode文件夹到项目目录."cursor": 添加一个.cursor文件夹到项目目录."agents.md": 添加一个AGENTS.md文件到项目目录."claude": 添加一个CLAUDE.md文件到项目目录.
-
--offline: 本地Scaffold该应用同时在开发者门户网站中创建了应用. -
--yes: 自动接受任何提示的默认选项,并以非交互方式运行.
-
列表
列出您的 Canva 应用程序,包括使用 Apps SDK, REST API 或 MCP 的应用程序 .
canva apps list
使用 canva apps list --print 在脚本或其他非交互环境中。 添加 --all 以列出每个没有页码的应用程序.
- 旗帜数字 :
--app-id: 指定要选择的 App ID .--all, (中文(简体) ),-a:一次列出所有应用,不标注.--print, (中文(简体) ),-p:将应用程序列表打印到控制台上,不进行交互.
预览
预览您的应用程序 .
canva apps preview
- 旗帜数字 :
--intent: App 意向预览 当该应用程序有多个意向注册时.--target: 用于预览的 Canva 目标editor或者说canva_ai对于在一个以上地点运行的意图.--source: 从开发 URL 中装入应用程序( )url)或上传捆绑(bundle) (中文(简体) ). 当应用程序版本有一个时默认为开发 URL .--no-open: 在不打开浏览器的情况下打印预览 URL.
开始
启动当前目录中应用程序的本地开发服务器, 由 @canva/app-scripts。 。 。 .
canva apps start
-
旗帜数字 :
--config: canva-app 配置文件的路径, 从工程根解析( 默认 ) :canva-app.config.ts) (中文(简体) ).--entry: 应用程序的条目文件( 默认 :src/index.tsx) (中文(简体) ).--backend-entry: Dev 服务器旁边的后端运行的条目文件 .--use-https在HTTPS的前面服务.--override-frontend-port: 覆盖前端dev-server端口.--tunnel:通过公用HTTPS隧道将后端曝光.--preview: 服务器启动后, 在 Canva 中打开应用程序预览 .
-
实例数字 :
canva apps start canva apps start --preview canva apps start --use-https --tunnel
构建
制作应用程序并提取其翻译,由 @canva/app-scripts。 。 。 .
canva apps build
-
旗帜数字 :
--config: canva-app 配置文件的路径, 从工程根解析( 默认 ) :canva-app.config.ts) (中文(简体) ).--entry: 应用程序的条目文件( 默认 :src/index.tsx) (中文(简体) ).--output-dir: 构建输出目录(默认 :dist) (中文(简体) ).
-
实例数字 :
canva apps build canva apps build --output-dir out
上传
构建应用程序并将其 JavaScript 捆绑和翻译上传到 开发者门户,作为替代 自己上传捆绑。 。 。 .
canva apps upload
应用程序的构建方式与 canva apps build组合和翻译从 outputDir 在canva-app配置文件中设置,或从 dist/ 用于不使用的应用程序 @canva/app-scripts。要上传上一个构建的输出,请通过 --prebuilt。 。 。 .
Bundle上传需要至少一个在Canva内注册的意向. Apps只使用REST API或MCP不需要捆绑上传.
-
旗帜数字 :
--app-id: App ID 为上传资产. 当前目录中链接的应用程序的默认值.env文档.--dry-run: 预览将不构建或上传任何内容而上传的内容 .--prebuilt: 在不构建应用程序或提取其翻译的情况下上传已有的构建输出.--drift-strategy: 预选如何解决本地问题canva-app.json与开发者门户网站的差异。 一个push, (中文(简体) ),skip,或abort。 。 。 .--config: canva-app 配置文件的路径, 从工程根解析( 默认 ) :canva-app.config.ts) (中文(简体) ).
-
实例数字 :
canva apps upload canva apps upload --app-id AAEuu... canva apps upload --dry-run canva apps upload --prebuilt canva apps upload --drift-strategy skip
医生
在您的 Canva App 上进行诊断 以识别和解决问题.
canva apps doctor
- 旗帜数字 :
--fix:尽可能自动对问题应用修正.--report: 输出检查结果而不提示修正.--verbose: 显示为AI代理辅助优化的详细诊断输出.--check: 指定要运行的特定检查.
移徙
运行特定的代码迁移以更新您的应用到更新模式和API.
canva apps migrate <migrationName>
-
参数数字 :
-
migrationName:要运行的迁移名称.可用的迁移:
"apps-sdk-v1-v2": Migrates apps 使用 Apps SDK v1 软件包到 v2."app-ui-kit-v5": Migrates apps 使用 App UI Kit v4 到 v5."design-editor-intent": Migrates 从直接渲染图案到设计意图图案."webpack-to-app-scripts": Migrates apps on a hand-rolled webpack 配置和scripts/start/运行到@canva/app-scripts。 。 。 .
-
-
旗帜数字 :
--dry-run: 不修改文件而预览更改 。 生成一个显示所有拟议修改的标记下预览文件.--debug: 显示详细的调试输出.--force:即使项目验证发出警告,也要继续.
-
实例数字 :
canva apps migrate apps-sdk-v1-v2 canva apps migrate app-ui-kit-v5 canva apps migrate design-editor-intent canva apps migrate apps-sdk-v1-v2 --dry-run canva apps migrate apps-sdk-v1-v2 --debug canva apps migrate webpack-to-app-scripts
配置
管理您的 App 配置。 。 。 .
canva apps config
CLI 支持 Canva 内部配置和 Outside Canva 设置 canva-app.json,包括:
outside_canva.rest_api: REST API 注册、瞄准镜和返回导航.outside_canva.mcp: MCP入学人数.outside_canva.redirect_urls: OAuth重定向由REST API和MCP共享的URL.
关于 REST API 认证, 请复制 CANVA_CLIENT_ID 生成 CANVA_CLIENT_SECRET 进入您的项目 .env 文件来自 外 Canva – 配置 →.env 文件 输入 开发者门户配置拉出和推出不包含这些证书。 见 REST API 认证 为OAuth设置阶梯.
对于 --strategy,拉接受 remote 和推力接受 local; 两者均接受 manual 以写入冲突标记进行编辑. --force 财务报告和审定财务报表 --strategy 无法合并.
牵出
获取 canva-app.json (英语) 配置来自开发者门户网站.
canva apps config pull
- 旗帜数字 :
--force, (中文(简体) ),-f: 强制拉出应用程序配置, 覆盖任何本地更改--strategy: 预选冲突解决策略,允许命令运行而不使用用户输入
推动
提交当地 canva-app.json (英语) 转到开发者门户.
canva apps config push
- 旗帜数字 :
--force, (中文(简体) ),-f: 强制推动应用程序配置, 覆盖任何远程更改--strategy: 预选冲突解决策略,允许命令运行而不使用用户输入
状态
关于《公约》现况和有效性的报告 canva-app.json (英语) 相会.
canva apps config status
链接
通过更新.env文件将本地工程链接到已有的 Canva app
canva apps link
- 旗帜数字 :
--app-id: 指定要选择的 App ID .--force: 写.env未经确认.
下一步
限制
您必须管理您通过 Canva CLI 创建的新应用程序 开发者门户无法通过 Canva CLI 完全管理应用程序 .
canva api 通过Canva自己的OAuth客户端调用REST API. 为了制作一个代表用户调用Canva的产品,请参见 使用 REST API 访问创建自己的应用程序 在开发者文档中.
更新
要更新 CLI 到最新版本, 请运行 :
npm update -g @canva/cli@latest
捐款
目前Canva CLI不接受第三方捐款. 请通过 Canva 开发者社区 或提出问题 吉图布。 。 。 .
隐私
Canva CLI收集匿名分析与诊断数据来帮助提高产品可靠性. 这些数据按照下列规定处理: Canva的隐私政策。 。 。 .
要禁用收藏, 设置 CANVA_CLI_DISABLE_TELEMETRY=true 在你的环境。 例如:
export CANVA_CLI_DISABLE_TELEMETRY=true
许可证
参见 LICENSE.md 文档以获取更多信息.