Sharkly の UI で行われるクリックは、すべて人が下した判断です。この Task を作成する、あの Agent をアサインする、実行状況を確認する。そうした判断を下す場面には、このインターフェースが最適です。しかし、同じ判断を千回繰り返す場面には向いていません。夜間ビルドが失敗したら必ず Task にする、とチームが決めた瞬間から、人が画面をクリックして回る作業はワークフローではなく雑務になります。
そこで登場するのがプログラマティックなインターフェースです。Sharkly CLI を使えば、人・エージェント・スクリプトがターミナルから Sharkly を操作できます。組織のリソース管理、エージェント実行用の Computer の登録、ローカルサービスの状態確認、そして繰り返し発生するワークフローの自動化が可能です。その背後には api.sharkly.ai の REST API があり、CLI が使うのと同じパーソナルアクセストークンを受け付けます。
これは、一般的な PM ツール以上に Sharkly にとって重要な意味を持ちます。Sharkly は単に作業を記述する場所ではなく、作業が実行される場所だからです。Sharkly は Claude Code や Codex といったコーディングツールの周囲に、共有タスク、Computer、コンテキスト、コントロール、レビューのレイヤーを追加します。そのため、スクリプトによる sharkly task create は単にチケットを起票するだけでは終わりません。Task が Agent にアサインされ、ready ステータスにあれば、実際の Computer 上で実際の実行を開始できます。このインターフェースをスクリプト化するということは、働き手そのものをスクリプト化するということです。
TL;DR
Sharkly CLI（コマンドは sharkly）を使えば、人・エージェント・スクリプトがターミナルから Sharkly を操作できます。また、リモートホストや Linux ホストにローカルサービスをインストールして、Computer としてフリートに参加させる際にも使います。認証は意図的に分離されています。パーソナルアクセストークン（プレフィックス shk_）は人またはスクリプトのログインに、ワンタイムのインストールトークン（プレフィックス sit_）は Computer の登録に、そして Agent の実行には Sharkly が発行するスコープ付き実行クレデンシャルを使用します。トークンを用意すれば、スクリプトから Task の作成・編集、コメント、実行とログの確認、Computer の管理まで行えます。いずれも --output json を使えばパースしやすい出力が得られます。同じ shk_ トークンは REST API に対するベアラートークンとしても機能し、Automation の Webhook トリガーを使えば、CI やその他の外部システムから POST リクエストで Agent の実行を開始できます。
1 つのプラットフォーム、2 つの入り口
Sharkly の UI とプログラマティックなインターフェースは、同じシステムへの 2 つの入り口です。スクリプトが作成した Task は、チームメイトがボード上で見るのと同じ Task であり、ステータス、Workflow、コメント、実行履歴もすべて同じです。スクリプト化によって共有レコードを迂回することはありません。自動化はシステム・オブ・レコードに情報を供給します。
両者を上手に使い分ける基準は、誰が判断を下すかです。人が判断を下すときは UI を使います。要件を練る、差分をレビューする、結果を承認する、といった場面です。判断がすでに下されていて、手順だけを繰り返す場合は CLI か API を使います。監視システムから Task を起票する、実行ログをダッシュボードに取り込む、cron ジョブから Computer の健全性を確認する、といった場面です。スクリプトが Task を作成し、実行をトリガーすることもできますが、承認はあくまで人の手に残ります。
CLI のインストールと、それがインストールするもの
macOS または Linux では、公式インストーラーは次の 1 コマンドです。
curl -fsSL https://file-assets.sharkly.ai/download/install.sh | bash
Windows には公式の PowerShell インストーラーがあります（現在は AMD64 のみ）。どのプラットフォームでも、次のコマンドでインストールの確認とメンテナンスができます。
sharkly version
sharkly update
CLI にはクライアントとしての役割以外に、もう 1 つの役割があります。ドキュメントでは Computer を接続する方法が 2 つ説明されています。対応している個人向けコンピューターに Sharkly Desktop をインストールするか、リモートホストまたは Linux コンピューターに Sharkly CLI とローカルサービスをインストールするかです。後者の方法を使えば、ビルドサーバーや予備の Linux マシン、コンテナが Agent の実行リソースになります。CLI がセットアップするローカルサービスは、Computer の登録、インストール済み Runtime の検出、ハートビートの送信、キューに入った実行の受信、タスクディレクトリの準備、進捗のストリーミングを行い、接続自体をこちらから開始するため、受信ポートを開ける必要はありません。
まだ最初のマシンを UI から接続する段階であれば、はじめかたガイドでその手順を説明しています。
3 つのクレデンシャル、3 つの役割
Sharkly は用途ごとに別々のクレデンシャルを使います。自動化を始める前に、この分離の考え方をしっかり理解しておきましょう。
パーソナルアクセストークンは shk_ で始まり、CLI、スクリプト、その他の信頼できるクライアントがあなたのユーザーアカウントとして動作できるようにします。Settings で作成し、有効期限を 30 日、90 日、1 年、または無期限から選び、作成時に一度だけ完全な値をコピーします。プロンプト方式でログインすれば、トークンがシェル履歴に残ることはありません。
sharkly login --token
sharkly auth status
コンピューターインストールトークンは sit_ で始まり、30 分で失効し、使用できるのは 1 回だけです。その唯一の役割は Computer の登録です。
sharkly computer register --install-token sit_...
3 つ目のクレデンシャルは、あなたが直接扱うことはありません。実行中の Agent は Sharkly が発行するスコープ付き実行クレデンシャルを受け取り、その実行コンテキストが許可するコマンド群に限定されます。
ドキュメントはこの境界を明確に示しています。パーソナルアクセストークンでコンピューターを登録することはできず、インストールトークンで人の CLI ログインを作成することもできません。登録は独立したローカルサービスセッションを作成するため、後でパーソナルアクセストークンを失効させても、登録済みの Computer がオフラインになることはありません。同様に、sharkly auth logout はローカルプロファイルからトークンを消去するだけで、Settings で失効させるまでサーバー上ではトークンは有効なままです。
CI の場合はログインフローを完全に省略できます。CLI は SHARKLY_TOKEN 環境変数からトークンを読み取り、これは保存済みのプロファイルよりも優先されます。ワークフローファイルに書き込むのではなく、GitHub Actions secrets などの保護されたシークレットストアから設定し、--organization-id で組織を明示してください。
ターミナルから Computer のフリートを管理する
ホストを登録したら、sharkly computer コマンドグループでブラウザを使わずに状態確認とメンテナンスができます。
sharkly computer list --output json
sharkly computer show <computer-id> --output json
sharkly computer usage <computer-id> <runtime-id> --days 30 --output json
sharkly computer ping <computer-id> <runtime-id> --wait --output json
sharkly computer update <computer-id> <runtime-id>
list は現在の組織に登録されている Computer を表示し、show は Runtime を含む 1 台の Computer の情報を返し、usage は特定の Runtime を調査し、ping はその Runtime が往復通信を完了できるかを確認し、update は Runtime の CLI 更新を要求します。ping が存在する理由はこうです。Computer がオンラインであるというのは、そのローカルサービスがハートビートを送信しているというだけのことで、特定の Runtime が今すぐ実行を遂行できるという意味ではありません。
ホスト上での日常的な診断には、ユーザー向けのコマンドを使います。
sharkly computer status --output json
sharkly computer logs --lines 100
daemon 名前空間はプロセスのライフサイクルとディスクの制御を提供します。sharkly daemon disk-usage や sharkly daemon cleanup などがあり、--confirm を付けない限りドライランになります。ドキュメントの判断基準はこうです。日常的な診断には computer status と computer logs を優先し、daemon はプロセスのライフサイクル、ディスクレポート、クリーンアップが必要なときだけ使う。所有権、可視性、クリーンアップポリシーについては、このシリーズの Computers の記事で詳しく解説しています。
Task のスクリプト化：会議なしで届く仕事
Task は、CLI がパイプラインの中でその価値を発揮する場面です。コマンド群は、ボードをスクリプト化したものだと考えれば分かりやすいでしょう。
sharkly task list --output json
sharkly task search "authentication error" --output json
sharkly task create --title "Investigate authentication error" --output json
sharkly task edit <task-id> --status <status> --output json
sharkly task comment <task-id> --body "Investigation started." --output json
分かりやすい CI のユースケースは、作業の自動起票です。リリース失敗を検知する夜間ジョブに、人がフォームを埋める必要はありません。
sharkly task create \
--title "Investigate the failed release" \
--body-file ./task-body.md \
--output json
内容を正確に渡したいときは常に --body-file か --body-stdin を使います。短い --body 形式はエスケープシーケンスをデコードしてしまうからです。また、Agent にアサインされた Task は ready ステータスになると実行が始まるため、この 1 つのコマンドが完全自動ループの起点になります。スクリプトが Task を起票し、アサインされた Agent がそれを引き受け、実行、ブロッカー、結果が Task に戻り、翌朝に人がレビューします。
レポート用スクリプトでは、クライアント側で選別するのではなく本物のフィルターが使えます。--status-changed-within 7d でステータスの経過時間で絞り込んだり、カスタムフィールドで絞り込んだりできます。
sharkly task list --space HF --field "Customer Tier=VIP" --output json
--field フラグを複数指定すると AND 条件になり、マッチングは型を考慮した完全一致で、フィルタリングはページネーションの前にサーバー側で行われます。ドキュメントのスクリプト規約はそのまま取り入れましょう。--output json を明示的に指定し、--color never と --quiet を加え、--organization-id を省略せずに書き、set -euo pipefail を使います。終了コードは仕様として定められています。0 は成功、1 はコマンド、バリデーション、認証、リモート API のエラー、2 は一時的なローカルサービスやネットワークの状態を表すため、リトライ処理を組み立てやすくなっています。
CLI は自己記述的でもあります。sharkly schema task create --format json はコマンドレジストリを機械可読な形式で公開し、sharkly tldr task は厳選されたシナリオを表示します。スクリプトを書く主体がエージェント自身である場合、これは重要な点です。
ダッシュボードを開かずに実行を監視する
実行は同じインターフェースから観測できます。
sharkly run list --task <task-id> --output json
sharkly run view <run-id> --output json
sharkly run log <run-id> --since <sequence> --output json
sharkly run cancel <run-id> --output json
--since フラグを使えばポーリングがまともになります。監視スクリプトが最後に処理したシーケンス番号を記録し、各回で新しいメッセージだけを取得します。これに sharkly agent list、sharkly automation view、sharkly automation runs を組み合わせれば、シェルスクリプトと jq だけでエージェント部隊のステータスページを作れます。
REST API と Webhook
CLI が行うことはすべて REST API 上で動作します。ドキュメントには直接アクセスする方法も示されています。パーソナルアクセストークンを HTTPS 経由でベアラートークンとして送信します。
curl -fsS https://api.sharkly.ai/rest/v1/users/current \
-H "Authorization: Bearer ${SHARKLY_TOKEN}"
API 経由のアクセスは、トークンの背後にいるユーザーの権限によって制限されます。現在のトークンモデルにはトークンごとのスコープ選択がないため、有効期限を定めたトークンをサービスごとに作成するのが賢明です。エンドポイントのリファレンスは docs.sharkly.ai にあり、CLI の --output json レスポンスは、扱うことになるデータ構造の正確なプレビューになります。
通信は逆方向にも流れます。Automation には Webhook トリガーを設定できます。Sharkly が POST リクエストを受け付けるシークレット URL を生成し、有効なリクエストが Automation の Agent または Crew の実行を開始します。完全な URL は一度だけ表示され、デフォルトではベアラーシークレットとして機能し、署名検証も任意で追加できます。これが CI の話の受信側です。パイプラインから Sharkly に「何かが起きたのでトリアージ Agent を実行して」と伝えられます。
このインターフェースが何ではないかを正確に押さえておく価値があります。Sharkly CLI は別のコーディングエージェントではなく、API はモデルエンドポイントではありません。実行を行うのは Claude Code や Codex のような Runtime であり、Sharkly のプログラマティックなインターフェースはその周囲のレイヤーを管理します。この中立性が、自動化のインターフェースと実行が 1 つのベンダーの壁の内側にある GitHub Agent HQ のようなエコシステム依存の選択肢との違いです。
どこから始めるか
思っているよりも小さく始めましょう。有効期限 90 日のパーソナルアクセストークンを作成し、sharkly login --token を実行し、毎日行っている最も退屈な読み取り処理をスクリプト化します。たとえばタスクリストを jq に通して朝のサマリーにする、といったものです。読み取りは安全で、JSON の構造を学べます。次に、明らかなトリガーを持つ書き込みを 1 つ自動化します。たとえば CI ジョブの失敗から Task を作成する、といったものです。Webhook トリガーの設定は、その両方が日常になってからにしましょう。
守るべきパターンは、プラットフォーム全体が基盤としているものです。スクリプトと Agent が作業を生成して実行し、コンテキスト、進捗、ブロッカー、結果、人のレビューは、リクエストからリリースまで見える状態に保たれます。入り口は自動化し、レビューは残す。これが原則です。
FAQ
Sharkly を使うのに CLI は必要ですか？
いいえ。個人のコンピューターの接続は Sharkly Desktop で完結し、日々の Task 作業は Web アプリで行えます。CLI が必要になるのは、リモートホストや Linux コンピューターを接続する場合です。そこでは Sharkly CLI とローカルサービスのインストールがドキュメント化されたセットアップ手順だからです。また、同じワークフローを何度も繰り返すうちにクリック操作がコストになってきたときにも役立ちます。
パーソナルアクセストークンとインストールトークンの違いは何ですか？
パーソナルアクセストークン（プレフィックス shk_）は、人またはスクリプトをあなたのユーザーアカウントとして認証し、CLI ログイン、CI ジョブ、直接の API リクエストに使われます。コンピューターインストールトークン（プレフィックス sit_）はワンタイムで有効期間が短く、30 分で失効し、Computer の登録にのみ使用します。どちらも他方の代わりにはなりません。
CLI を使わずに Sharkly REST API を直接呼び出せますか？
はい。パーソナルアクセストークンを HTTPS 経由で api.sharkly.ai にベアラートークンとして送信します。ドキュメントでは Authorization: Bearer ヘッダーを付けた curl -fsS https://api.sharkly.ai/rest/v1/users/current がパターンとして示されています。トークンはあなたのユーザーアカウントの権限を引き継ぎます。
CI パイプラインから Task を作成するにはどうすればよいですか？
shk_ トークンを保護された CI シークレットとして保存し、CLI が自動的に読み取る SHARKLY_TOKEN 環境変数として公開します。その後、sharkly task create を --title、正確な複数行コンテンツ用の --body-file、明示的な --organization-id、そして --output json を付けて実行すれば、ジョブが作成された Task の ID を取得できます。
パーソナルアクセストークンを失効させると、登録済みの Computer は停止しますか？
いいえ。Computer の登録はインストールトークンを通じて独立したローカルサービスセッションを作成するため、パーソナルアクセストークンを失効させてもそれらの Computer は停止しません。ただし失効により、CLI、API、自動化リクエストでそのトークンが使われているすべての場所でトークンが無効になります。そのため、ローテーションでは古いトークンを失効させる前に、依存するスクリプトを更新する必要があります。
