Zenn
⚙️

Raycastを一段進化させるScript commands

2024/12/13に公開
Raycast
idea

🧑‍🤝‍🧑 想定読者

  • 毎日の定型作業を手軽に自動化したい人
  • 業務効率を上げていきたい人

📝 この記事の内容

  • Raycast Script Commandの基本的な仕様と設定方法
  • メタデータパラメータの詳細な使い方と設定例
  • 実践的なスクリプト例（GitHub PR確認、朝一定例作業の自動化、カスタムURLオープナー）
  • 引数を使った柔軟なスクリプトの作り方

🔍 Raycastとは

https://www.raycast.com/
Raycastは、macOSで使える便利なランチャーアプリ（Windowsもリリース予定？）。キーボードからさまざまな操作ができ、日々の作業を自動化できます。

Spotlightの検索機能を更に使いやすく進化させており、アプリの起動やファイル検索、カレンダーの確認、パソコンの設定変更など、やりたいことを素早く実行することが可能です。

好みに合わせて機能をカスタマイズしたり、自動化の仕組みを作ったりすることもできるアプリ。

🔍 Script Commandとは


定型業務をHotKeyを割り当てたりして、実行できる自動化機能です。自分でスクリプトを組むので作業スタイルに合わせてカスタマイズすることが可能です

できることの一例

  • 複数のブラウザタブを開く作業を1つのコマンドに集約
  • GitHubのプルリクエスト確認を自動化して定期的に情報更新
  • よく使うアプリケーションやツールの起動を効率化
  • APIを使った情報取得と表示の自動化

👍　主なメリット

  • 割とスムーズに動く＆自分でスクリプトをコントロール＆色々なことできる
  • 好きな言語が使える（Bash、Python、Ruby、PHP、Node.js、Swift、AppleScript）
  • コミュニティの作成したスクリプト例もある

Script commandsのことはじめ

既存のScript commandsのインストール

  1. こちらのリポジトリから使用したいScriptを選択、新規ディレクトリに保存
  2. Raycastの環境設定→Extensions→+ボタン→Add Script Directoryを選択
  3. 1で保存したScriptが含まれるディレクトリを選択
  4. これで、選択したScript Commandが使用可能に！

新規のScript commands

  1. Raycast上でCreate Script Command機能を使用
  2. VSCodeなどで開き、Scriptを作成・編集
  3. 作成したScript commandsをRaycastから実行できます
  4. BashでShellを作る場合はShellCheck（拡張機能などの）を通すとよいです

📚 メタデータの仕様

必須パラメータ

パラメータ名 説明 型 設定例・補足
schemaVersion スキーマバージョン number 現在はバージョン1のみ対応
title コマンド名 string 検索時に表示される名前。例："Quick PR Check"
mode 実行・出力方法 string 下記の4種類から選択

モードの種類

  • silent: 通知や出力を表示しない。アプリを開く、ファイルを移動する等の単純な操作に使用
  • compact: 一行の出力を表示。Git branch一覧表示やTODOリスト表示などに最適
  • fullOutput: 複数行の出力を表示。ログ解析や詳細情報の表示に使用
  • inline: Raycastウィンドウ内に直接結果を表示。CPU使用率表示などのリアルタイム情報に

オプションパラメータ

パラメータ名 説明 型 設定例・補足
packageName サブタイトル string 例："GitHub Tools"
icon アイコン string 以下の形式に対応:
- 絵文字："🔍"
- ファイルパス："./icon.png"
- SF Symbols："􀤆"
iconDark ダークモード用アイコン string iconと同じ形式
needsConfirmation 確認ダイアログ表示 boolean デフォルト：false
refreshTime 自動更新間隔 string 例："10s", "1m", "1h"
author 作者名 string 例："John Doe"
authorURL 作者のURL string 例："https://github.com/johndoe"
description コマンドの説明 string 検索時に表示される説明文

アイコンの設定について

  1. 絵文字を使用する場合
# @raycast.icon 🚀
  1. 画像ファイルを使用する場合
# @raycast.icon /absolute/path/to/icon.png

💡 活用例

1. AppleScriptでSlackチャンネルを開く

スクリプト

#!/usr/bin/osascript

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title Open General Channel
# @raycast.mode silent
# @raycast.packageName Slack

# Optional parameters:
# @raycast.icon 💬
# @raycast.description Slackの#generalチャンネルを開きます

tell application "Slack"
    activate
    tell application "System Events"
        delay 0.5
        -- Cmd + K でチャンネル検索を開く
        keystroke "k" using {command down}
        delay 0.5
        -- チャンネル名を入力
        keystroke "general"
        delay 0.5
        -- Enterでチャンネルに移動
        key code 36
    end tell
end tell

2. GitHubのPR一覧を取得（GitHub CLI版）

使用前の準備

  1. GitHub CLI (gh) をインストール
 brew install gh
  1. GitHub CLIで認証
 gh auth login

GitHub CLIの認証については以下の記事が参考になります
https://techblog.ap-com.co.jp/entry/2021/08/23/091131

Script

#!/bin/bash

# Required parameters:
# @raycast.schemaVersion 1
# @raycast.title List PRs
# @raycast.mode fullOutput

# Optional parameters:
# @raycast.icon 🔍
# @raycast.packageName GitHub

# PRの一覧を取得（最新10件）
gh pr list --limit 10 --format '- %t %U %l%n'

3.GitHubのPR一覧を取得（GitHub API版）

使用前の準備

  • node.jsをインストールしてください
  • GitHubの個人のsettings>Developer Settings>Personal Access Token>Tokensで、GitHubのTokenを取得してください

Script

#!/usr/bin/env node

// Required parameters:
// @raycast.schemaVersion 1
// @raycast.title List PRs
// @raycast.mode fullOutput

// Optional parameters:
// @raycast.icon 🔍
// @raycast.packageName GitHub


// GitHub Personal Access Tokenを環境変数から取得
const GITHUB_TOKEN = "your_api_key"
const OWNER = "適宜";
const REPO = "適宜";

async function fetchPullRequests() {
  try {
    const response = await fetch(
      `https://api.github.com/repos/${OWNER}/${REPO}/pulls?state=open&per_page=10`,
      {
        headers: {
          Authorization: `token ${GITHUB_TOKEN}`,
          Accept: "application/vnd.github.v3+json",
        },
      }
    );

    if (!response.ok) {
      throw new Error(`GitHub API responded with status ${response.status}`);
    }

    const pullRequests = await response.json();

    pullRequests.forEach((pr) => {
      console.log(`- ${pr.title}`);
      console.log(`  URL: ${pr.html_url}`);
      console.log(
        `  Labels: ${pr.labels.map((label) => label.name).join(", ") || "None"}`
      );
      console.log("");
    });
  } catch (error) {
    console.log(`GITHUB_TOKEN: ${GITHUB_TOKEN}`);
    console.error("Error fetching pull requests:", error.message);
  }
}

fetchPullRequests();

上記を実行する以下のようなイメージなります

📌 まとめ

Script commandsは、高度なカスタマイズ性と多言語対応により、業務効率化の可能性を大きく広げてくれるツールです！
活用例は本当に基礎的なものにとどめました！（なんでもできてしまうため...)

コミュニティにもScript例があるため、活用してみてください！

参考

https://github.com/raycast/script-commands/tree/master

https://www.raycast.com/blog/getting-started-with-script-commands

Discussion