trylle-cli

Trylle CLI、技能指南

概述

使用 try 作为 Trylle 平台操作的主要接口。使用 git 进行本地版本控制，但不要用 GitHub 专用工具替代 Trylle 资源。

调用此技能中的任何脚本，即表示你同意 TERMS_OF_USE 中的使用条款。

工作流

1. 定位或安装二进制文件

尽可能使用本地的 trylle-cli 或 try 二进制文件。如果它不在 PATH 中，

npm i -g @trylle/trylle-cli

可以通过 npx trylle-cli 运行一次性命令，例如：npx trylle-cli version。 本文档其余部分将使用 try 作为参考。

获取二进制文件的其他方式：

# Python Way
uv tool install trylle-cli

# Rust Way (slow and will build from source)
cargo install trylle-cli

2. 核心用法

重要提示：此 CLI 面向人类用户设计，因此在 Agent 场景下使用命令时，应添加 --json 标志。

1. 使用 try auth status --json 检查身份验证状态。其 kind 对于个人密钥为 cli_key，对于单次运行范围的令牌（自动化运行、CI 任务、Magic Task 或 Magic Session）为 bot_token；此时 botToken 会显示令牌的作用域、存储库和有效期。除非用户明确请求获取机密内容且环境能够安全处理，否则切勿运行 try auth token --show 或打印令牌。
2. 在检出目录中使用 try repo context --json 解析上下文。在检出目录之外，对支持此参数的命令使用 -R OWNER/NAME，或者在 try repo view、clone 和类似存储库命令中按位置传入 OWNER/NAME。
3. 执行写入操作前，运行 try <group> <command> --help，验证标识符和预期范围，然后仅执行用户请求的变更。
4. 重新读取受影响的资源。适合帮助用户继续操作时，使用 try browse repo|pr|issue 返回网页 URL。

选择任务对应的命令

• 存储库和日常上下文：使用 try status 查看当前用户的摘要，并使用 try repo。
• 拉取请求和评审：使用 try pr。
• 问题分类处理：使用 try issue。
• 依赖分支和拉取请求：使用 try stack。
• CI 状态、日志、监控和重新运行：使用 try ci。
• 云端编码 Agent：使用 try task 启动或跟进 Agent，并使用 try session 访问其工作区。
• 你运行所在会话周围的 Trylle 应用（本地或云端）：使用 try app。try app open changes|files|terminal|pr 会显示会话面板中的相应标签页；try app open --pr <number|url|OWNER/NAME#N> 会在其中显示拉取请求；try app pr attach|detach|list 用于跟踪与会话关联的拉取请求。在会话中使用 try pr create 创建的拉取请求已自动关联。只有在有助于读者了解工作进展时才向其展示内容，无需在每一步之后都展示。
• 存储库或组织配置：使用 try actions 或 try org。
• 账户和操作：使用 try profile、try ssh-key、try automation 或 try bot。
• 资源链接和未覆盖的公共端点：使用 try browse 或 try api（try api --list [FILTER] --json 会列出所有公共端点及其参数）。
• 本地 AI 和评审辅助工具：使用 try ai、try explain、try draft 或 try diff。

阅读 references/command-catalog.md，了解完整的命令映射和准确的参数格式。在创建或发布存储库、发起或评审拉取请求、分类处理问题、处理分支栈、诊断 CI，或更改密钥和设置时，请阅读 references/workflows.md。在自动化程序提交或管理拉取请求的行内评审评论之前，请阅读 references/inline-reviews.md。

安全与输出规则

• 将删除仓库、合并或关闭 PR、关闭议题、替换标签、删除密钥、切换自动化功能、安装机器人、重命名或转移仓库、删除或强制暂停 Magic Session，以及更改机密视为会产生重大影响的操作。先显示确切目标并检查当前状态。
• 不要将凭据写入命令字面量、日志、文件、提交消息或聊天中。使用预先存在的环境变量存储机密值，并在之后取消设置临时变量。
• 对复杂的 PR、评审、议题或评论正文，优先使用 --body-file。使用 --attach FILE[#ALT] 附加截图（参见工作流）。
• 只要有 --json，就使用它。面向人的输出供终端阅读，格式可能会改变。
• 不要猜测不受支持的标志。已安装 CLI 的 --help 输出是准确信息来源。
• 如果存在一等命令，不要使用 try api。对于原始调用，只使用任务所需的公开 /v1 API 路径。

安装或更新技能

如果缺少部分技能文件，或 CLI 参考映射已过时，请使用以下命令更新技能：

# add
npx skills add trylle-labs/skills

# update
npx skills update trylle-labs/skills --skill trylle-cli

也可以使用 uv：

uvx upd-skill -g trylle-labs/trylle-cli

当前 CLI 注意事项

• 仓库推断依赖可识别的 git 远程仓库。如果推断存在歧义，请明确传入 -R OWNER/NAME。
• 当前分支没有开放 PR 时，try pr current --json 会以非零状态退出，而不是返回 JSON null。预期不存在 PR 时，请使用 try repo context --json。
• try pr review 必须且只能指定 --approve、--request-changes 或 --comment 中的一个。
• 如果通过 --comments 或 --comments-file 提交行内评论，try pr review 还必须指定 --commit-id。
• try issue label --set 会替换完整的标签集合；--add 和 --remove 则会保留无关标签。
• try stack submit 会先将当前分支推送到 origin，然后再创建拉取请求。
• try ci watch 会持续轮询，直到运行结束。CLI 1.1.6 及更早版本则只返回单个日志快照。
• 非交互模式下，try repo delete 和 try repo transfer 必须指定 --yes，try session delete 也一样。
• 无法通过 CLI 生成或列出机器人令牌：平台会注入作用域为单次运行的 TRYLLE_BOT_TOKEN。管理机器人（try bot ...）需要使用某人的 CLI 密钥，并且只有机器人的创建者才能通过 try bot edit 编辑机器人；具备评论或写入作用域的机器人令牌也可用于 --attach 上传。
• try session logs 读取的是会话历史记录，而不是实时 shell；如需使用 shell，请运行 try session ssh。输出按时间顺序排列，包含会话开始以来的完整记录。
• try app 只能在 Trylle 会话中使用（它会读取 TRYLLE_SESSION_ID 和 TRYLLE_DESKTOP_ENDPOINT）；在其他位置运行时会提示没有可操作的会话。读者正在查看该会话时，面板请求会立即显示；否则会等到他们打开会话后才显示。云会话只会追踪 Trylle 拉取请求。
• PR 作者、议题标签等列表筛选条件可能会应用于返回的页面。断定不存在匹配项之前，请增大页面大小或翻页。