🌊 surf-cli

surf-cli は、Surfshark の OpenVPN 手動設定を CLI から扱うための TypeScript 製ツールです。Linux を主対象にし、openvpn が導入済みであることを前提に sudo openvpn を起動します。macOS は openvpn CLI がある場合のみ best-effort です。

注意: Surfshark 公式ドキュメントでは、OpenVPN 手動接続で使う username/password は通常のアカウントメール・パスワードとは別物です。通常ログイン API は公開仕様ではないため、メール/パスワード・コードログインは experimental とし、失敗時は手動 OpenVPN 認証情報入力へフォールバックします。

English README: docs/README-en.md

📦 インストール

パッケージマネージャー

npm install -g @remielledan/surf-cli
# bun install -g @remielledan/surf-cli
# pnpm install -g @remielledan/surf-cli
# yarn global add @remielledan/surf-cli

インストールスクリプト

curl -fsSL https://codeberg.org/xuanling/surf-cli/raw/branch/master/scripts/install.sh | bash

開発版（ソースから）

git clone https://codeberg.org/xuanling/surf-cli.git
cd surf-cli
corepack enable
pnpm install
pnpm build
pnpm link --global

✅ 要件

• Node.js 22 以上
• Linux（推奨）または macOS（best-effort）
• openvpn
• sudo
• Surfshark の有効な契約

🚀 使い方

Quick Start

surf-cli doctor                    # 前提条件を確認
surf-cli auth login --manual       # OpenVPN 認証情報を登録
surf-cli servers refresh           # サーバー設定をダウンロード
surf-cli connect jp-tok            # 日本・東京サーバーに接続
surf-cli status                    # 接続状態を確認
surf-cli disconnect                # 切断

ヘルプは surf-cli --help または各コマンドで surf-cli <command> --help で確認できます。

🔐 認証

推奨は Surfshark dashboard の VPN > Manual Setup > Desktop or mobile > OpenVPN で確認できる OpenVPN service credentials の手動登録です。

surf-cli auth login --manual

experimental なログイン経路（--email, --code）も用意していますが、Surfshark の非公開 Web API に依存するため、OpenVPN service credentials を取得できない場合は手動入力へフォールバックします。

認証情報は $XDG_STATE_HOME/surf-cli/credentials.json（mode 0600）へ保存します。デスクトップ keyring / gnome-keyring は不要です。

詳細は docs/topics/authentication.md を参照してください。

🔧 トラブルシュート

CONNECTION_FAILED で OpenVPN が初期化前に終了した場合、surf-cli は OpenVPN log、起動直後の stderr/stdout、終了コードの順に診断情報を表示します。

• まず surf-cli doctor で openvpn と sudo が利用できるか確認してください。
• sudo password prompt が出る場合は、端末でパスワードを入力してください。
• 詳細を直接確認したい場合は surf-cli connect jp-tok --foreground のように foreground 実行してください。
• AUTH_FAILED の場合は、通常の Surfshark アカウントではなく OpenVPN service credentials を surf-cli auth login --manual で登録し直してください。

詳細は docs/topics/vpn-connection.md を参照してください。

📚 ドキュメント

| ドキュメント | 内容 | | ---------------------------------------------------------------- | -------------------------------------------- | | docs/README.md | ドキュメントインデックス・アーキテクチャ概要 | | docs/topics/authentication.md | 認証方法の詳細 | | docs/topics/vpn-connection.md | VPN 接続モデルの詳細 | | docs/topics/server-catalog.md | サーバー設定の取得・展開・検索 | | docs/topics/data-storage.md | データ保存場所・XDG パス・権限 | | docs/topics/error-handling.md | エラー種別・exit code | | docs/development.md | 開発手順・CI/CD |

🔒 セキュリティ

• Surfshark アカウントパスワードは保存しません。
• OpenVPN service credentials は 0600 の state ファイル（$XDG_STATE_HOME/surf-cli/credentials.json）に保存します。
• 実行時 auth file は XDG runtime 配下に 0600 で作成します。
• CI に Surfshark credentials を渡す設計にはしていません。

脆弱性の報告は SECURITY.md を参照してください。