terra-cli 是 Terra API 的命令行工具，用于在终端完成原本需要在 dashboard.tryterra.co 点击的账户配置操作，例如启用哪些数据提供方、发送哪些数据类型、webhook 投递地址以及凭证管理。它面向编码智能体（Claude Code、Codex、Cursor 等）使用，让需要读取或修改账户状态的任务可以直接完成。
主要能力：通过 terra examples list 和 terra examples clone 从已发布示例应用起步；用 terra whoami、terra environments list 等只读命令做预检；用 terra unified-api sources list、terra unified-api destinations list 等命令配置环境；用 terra events list 调试 webhook；用 terra data-api <path> 访问数据 API 任意端点；用 terra reference --format json 发现全部命令。
使用方式：macOS/Linux 可用 curl -fsSL https://cli.tryterra.co/install.sh | sh 安装，Windows PowerShell 用 irm "https://cli.tryterra.co/install.ps1" | iex，也可用 brew install tryterra/tap/terra 或 npm install -g @tryterra/cli。登录需人工在浏览器批准，可用 terra login --start 与 terra login --complete <device-code> 分步完成，或使用 TERRA_ADMIN_TOKEN 无头方式。
限制：默认登录只授予“Coding agent”预设，不含 keys:write、tokens:write、tokens:admin、billing:write、team:write 等危险权限，需要时由用户运行 terra login --scope <scope>。创建环境、注册、批准登录等仍需在 dashboard 完成。破坏性命令需 --yes 确认，replace 会清空未提供的字段，事件历史约保留 14 天。数据 API 与 admin API 凭证不可混用。