trylle-cli

Trylle CLI、スキルガイド

概要

Trylle プラットフォームの操作には、主要なインターフェースとして try を使用します。ローカルのバージョン管理作業には git を使用しますが、Trylle のリソースに GitHub 固有のツールを代用しないでください。

このスキルのスクリプトを実行すると、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 は人間が使用することを想定しているため、エージェントによるコマンド利用では --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 を使用します。
• Issue のトリアージ：try issue を使用します。
• 依存関係のあるブランチとプルリクエスト：try stack を使用します。
• CI の状態、ログ、監視、再実行：try ci を使用します。
• クラウドコーディングエージェント：エージェントの開始やフォローアップには try task、そのワークスペースには 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 を使って作成した PR は、すでに関連付けられています。作業の進行に役立つ場合は、毎回ではなく、その都度適切なものを読者に示してください。
• リポジトリまたは組織の設定：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 を参照してください。リポジトリの作成または公開、プルリクエストの作成またはレビュー、Issue のトリアージ、スタックの処理、CI の診断、シークレットと設定の変更については、references/workflows.md を参照してください。自動化によってインラインのプルリクエストレビューコメントを送信または管理する前に、references/inline-reviews.md を参照してください。

安全性と出力ルール

• リポジトリの削除、PR のマージまたはクローズ、イシューのクローズ、ラベルの置き換え、キーの削除、自動化の切り替え、ボットのインストール、リポジトリの名前変更または移管、Magic Session の削除または強制一時停止、シークレットの変更は、重大な操作として扱ってください。正確な対象を示し、まず現在の状態を確認してください。
• 認証情報をコマンドリテラル、ログ、ファイル、コミットメッセージ、チャットに含めないでください。シークレット値には既存の環境変数を使用し、一時変数は使用後に unset してください。
• 複雑な PR、レビュー、イシュー、コメントの本文には、インラインで記述する代わりに --body-file を優先してください。スクリーンショットは --attach FILE[#ALT] で添付してください（ワークフローを参照）。
• 使用可能な場合は --json を使用してください。人間向けの出力はターミナルでの閲覧を想定しており、書式が変更される可能性があります。
• サポートされていないフラグを推測して使用しないでください。インストール済み CLI の --help 出力が正しい情報源です。
• 同等の専用コマンドがある場合は、try api を使用しないでください。直接 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 を明示的に指定してください。
• try pr current --json は、現在のブランチにオープン中の PR がない場合、JSON の null を返す代わりにゼロ以外の終了コードで終了します。対象がないことが想定される状態では、try repo context --json を使用してください。
• try pr review では、--approve、--request-changes、--comment のいずれか1つだけを指定する必要があります。
• try pr review で --comments または --comments-file を使ってインラインコメントを送信する場合は、--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 キーが必要で、ボットを編集できるのはその作成者だけです。--attach によるアップロードには、コメントまたは書き込みスコープを持つボットトークンも使用できます。
• try session logs はセッションの履歴を読み込みます。ライブシェルではありません。シェルには try session ssh を使用してください。出力はセッション開始時点からの全内容を時系列で表示します。
• try app は Trylle セッション内でのみ動作します（TRYLLE_SESSION_ID と TRYLLE_DESKTOP_ENDPOINT を読み取ります）。それ以外の場所では、操作対象のセッションがないと表示されます。セッションを開いているユーザーにはパネルのリクエストがすぐに表示され、それ以外の場合はユーザーがそのセッションを開くまで待機します。クラウドセッションが追跡するのは Trylle のプルリクエストのみです。
• PR 作成者やイシューのラベルなどのリストフィルターは、取得したページに対して適用される場合があります。一致する項目がないと結論づける前に、ページサイズを増やすか、ページネーションを行ってください。