oss

中文 | English

S3 プロトコルベースのクロスクラウドオブジェクトストレージコマンドラインツール。単一のバイナリで、主要クラウドベンダーのオブジェクトストレージを操作： AWS S3、Alibaba Cloud OSS、Tencent Cloud COS、Huawei Cloud OBS、Baidu Cloud BOS、Kingsoft Cloud KS3、 UCloud US3、JD Cloud OSS、Google Cloud Storage、Cloudflare R2、Scaleway、Wasabi、 DigitalOcean Spaces、Backblaze B2、MinIO およびその他の S3 互換サービス。

• 🌐 匿名バケット閲覧：URL を指定するだけで、認証情報なしでパブリック読み取りバケットを一覧表示/ダウンロード
• 🔗 URL がそのまま入口：https://... URL アクセスをサポートし、各ベンダーのドメインを識別してバケット名/リージョンを解析； URL クエリパラメータ（prefix、delimiter、max-keys、continuation-token、marker、start-after） をそのままフィルタ条件として使用、aws-s3-bucket-browser と同様
• 📁 ディレクトリ形式で転送されるバケット：リバースプロキシ/CDN がバケットをパス配下にマウントするシナリオをサポート （例：https://files.example.com/mybucket/）、自動的に path-style で解析し、S3 API を透過的に渡すだけで一覧表示・ダウンロードが可能
• 🎫 追加パラメータの透過：URL 上の非リストパラメータ（例：?token=abc 認証ゲートウェイ）を すべての API リクエスト（一覧表示/ダウンロード/アップロード/署名付き URL 生成）に自動注入し、SigV4 署名の前に注入
• 🔑 多様な認証：AK/SK、STS 一時認証情報（session token）、AWS profile（assume-role 含む）、匿名
• 🗂 リストキャッシュ：一覧表示済みの内容はデフォルトでローカルにキャッシュされ、再一覧表示/エクスポート/ダウンロードが即座に完了（-d のような全量スキャンが必要なシナリオでは数百倍高速化）
• 📤 ファイルリストのエクスポート：フィルタ条件に従って txt / csv / xlsx / yaml / markdown にエクスポート（--export）
• ⬇️ フィルタ付き一括ダウンロード：cp -r で --include/--exclude/--prefix に一致するすべてのファイルをダウンロードし、key のディレクトリ構造を維持
• 🔍 バケット所属の検索：find でバッチ（コマンドラインで複数指定/標準入力）にバケットがどのクラウドストレージにあるかを検出、 バケット名と完全なバケット URL をサポート；匿名で検出し、同時に匿名でディレクトリ一覧が可能かを識別、匿名で一覧可能なバケットは コマンドラインで明るい緑の ★ でハイライト、--export で専用の listable_url フィールドを含む txt/csv/xlsx/yaml/md をエクスポート
• 🔌 外部向けサービス：oss serve で 1 つのポートに REST API + OpenAPI 3 ドキュメント + MCP ツールエンドポイントを提供、 oss mcp stdio|http|sse で ls/stat/cat/presign/find を MCP ツールとして Claude などのクライアントから呼び出し可能
• 🎨 ターミナルフレンドリー：対話型ターミナルでは自動でカラー強調、パイプ/スクリプトのシナリオでは自動的にプレーンテキストを出力（--color auto|always|never）
• 🌍 中日英ヘルプ：システム言語を自動認識し、中国語環境では中国語ヘルプ、それ以外では英語を表示（OSS_LANG=zh|en で強制可能）
• 📄 大規模バケット最適化：ストリーミングページング一覧表示（定数メモリ）、NDJSON ストリーミング出力、有界並行ダウンロード、数百万オブジェクトでもメモリを消費しない
• 🚀 並列転送：複数ファイルの並行 + 単一ファイルの分割並行、プログレスバー、レジュームスキップ、.part アトミック書き込み
• 🛠 ネットワーク制御：-x プロキシ、-H カスタムヘッダ（UA / Cookie …）、-k 証明書検証スキップ

インストール

方法 1：Homebrew（macOS / Linux、推奨）```bash brew install ejfkdev/tap/oss

**方法二：go install**（Go 1.24+ が必要）```bash
go install github.com/ejfkdev/oss@latest

方法三：コンパイル済みバイナリ

GitHub Releases から対応プラットフォームの圧縮パッケージ （linux/darwin/windows × amd64/arm64）をダウンロードし、解凍するだけで使用できます。Release 成果物はシンボルテーブルが削除済みで、 Linux/Windows 版は UPX で圧縮されています（macOS 版は非圧縮：UPX でパックされた Mach-O はカーネルにブロックされるため）。 各バージョンには SHA256 チェックサムファイルが付属しています。

方法四：ソースからコンパイル（Go 1.24+ が必要）：```bash git clone https://github.com/ejfkdev/oss && cd oss make build # 产物为 ./oss make install # 安装到 $GOPATH/bin make release # 本地交叉编译全部平台到 dist/

## クイックスタート```bash
# 匿名浏览公共桶（无需凭证）
oss ls https://noaa-nwm-pds.s3.amazonaws.com/?delimiter=/
oss ls "https://noaa-nwm-pds.s3.amazonaws.com/?prefix=nwm.20250101/&delimiter=/&max-keys=20"
oss cp -r https://noaa-nwm-pds.s3.amazonaws.com/nwm.20250101/ ./nwm/ --jobs 32

# 阿里云 OSS
oss ls oss://mybucket/logs/ --ak <AK> --sk <SK> --region cn-hangzhou
export OSS_ACCESS_KEY_ID=xxx OSS_SECRET_ACCESS_KEY=yyy   # 或者用环境变量
oss ls mybucket --provider aliyun                         # 裸桶名写法

# 腾讯云 COS / 华为云 OBS
oss ls s3://bucket-1250000000 --provider tencent --region ap-guangzhou
oss ls https://bucket.obs.cn-north-4.myhuaweicloud.com/prefix/

# Yandex / Exoscale / Arvan
oss ls s3://mybucket --provider yandex
oss ls s3://mybucket --provider exoscale --region ch-gva-2

# MinIO / 自建 S3
oss ls s3://mybucket -e http://127.0.0.1:9000 --ak minioadmin --sk minioadmin
oss ls http://127.0.0.1:9000/mybucket/prefix/             # IP/端口自动识别为 path-style

# 走代理、自定义 UA / Cookie
oss ls s3://mybucket -x http://127.0.0.1:7890 \
    -H "User-Agent: my-agent/1.0" -H "Cookie: session=abc"

# 目录形式转发的桶（反代把桶挂在路径下，S3 API 透传）
oss ls "https://files.example.com/mybucket/?prefix=2026/&max-keys=10"
oss cp "https://files.example.com/mybucket/<key>" ./

# 附带额外参数的访问（token 等会自动带到每个请求）
oss ls "http://gateway.example.com/bucket?token=abc"
oss cp "http://gateway.example.com/bucket/file.bin?token=abc" ./

Target の書き方

形式	例
scheme	s3://bucket/prefix、oss://、cos://、obs://
バケット名のみ	mybucket/prefix（--provider / -e と併用）
HTTP URL	https://bucket.s3.us-east-1.amazonaws.com/prefix?prefix=logs/

URL から自動認識されるベンダードメイン（endpoint / region / bucket を解析）：

ベンダー	ドメイン例
AWS	bucket.s3.region.amazonaws.com、s3.region.amazonaws.com/bucket
阿里雲	bucket.oss-cn-hangzhou.aliyuncs.com（accelerate 含む）
騰訊雲	bucket-appid.cos.ap-guangzhou.myqcloud.com
華為雲	bucket.obs.cn-north-4.myhuaweicloud.com
百度雲 BOS	bucket.s3.bj.bcebos.com、s3.bj.bcebos.com/bucket
金山雲 KS3	bucket.ks3-cn-beijing.ksyuncs.com
UCloud US3	bucket.s3-cn-sh2.ufileos.com
京東雲 OSS	s3.cn-north-1.jdcloud-oss.com/bucket（path-style）
天翼雲 OOS	bucket.oos-cn.ctyunapi.cn（リソースプールおよび香港ノード endpoint を含む）
聯通雲 OSS	bucket.obs-helf.cucloud.cn（業界雲リージョン）
移動雲 EOS	bucket.eos-wuxi-1.cmecloud.cn（30 リージョン）
青雲 QStor	bucket.s3.pek3a.qsstor.com（S3 互換ドメイン qsstor.com）
Scaleway	bucket.s3.fr-par.scw.cloud（fr-par/nl-ams/pl-waw）
Wasabi	bucket.s3.us-east-1.wasabisys.com（14 リージョン）
DigitalOcean Spaces	nyc3.digitaloceanspaces.com/bucket（9 リージョン）
Yandex	bucket.storage.yandexcloud.net
Exoscale SOS	bucket.ch-gva-2.sos.exoscale.com（6 リージョン）
Arvan Cloud	bucket.s3.ir-thr-at1.arvanstorage.ir
Cloudflare R2	bucket.<account_id>.r2.cloudflarestorage.com
GCS	storage.googleapis.com/bucket（HMAC キー）

その他のホスト（MinIO、Ceph、リバースプロキシ経由のバケット転送、CNAME…）は一律 path-style として解析： 最初のパスセグメントをバケット名、残りを key とする。例： https://files.example.com/mybucket/sub/key.jpg → バケット mybucket、key sub/key.jpg。 ホストが直接バケットを指す場合（CNAME）は --bucket NAME で明示的に指定する。URL が空の場合（oss ls）はすべてのバケットを列挙する。

URL クエリパラメータは 2 種類に分類される：

• リスト API パラメータ（prefix delimiter max-keys continuation-token marker start-after encoding-type list-type）→ 列挙フィルタ条件として解釈
• その他のパラメータ（例：token=abc）→ 追加パラメータとして扱い、そのターゲットへの各リクエストに透過的に渡す （ListObjects / GetObject / PutObject / Presign など）。認証パラメータ付きゲートウェイに適する； パラメータは SigV4 署名前に注入され署名に含まれるため、AK/SK 認証情報と同時に使用可能

認証

以下の順序で解析し、ヒットした時点で終了：

1. --ak / --sk / --token（STS session token）
2. 環境変数 OSS_ACCESS_KEY_ID / OSS_SECRET_ACCESS_KEY / OSS_SESSION_TOKEN
3. 環境変数 AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN
4. --profile NAME または ~/.aws/credentials|config（assume-role などの STS profile をサポート）
5. いずれもない → 匿名アクセス（--anonymous で強制可能）

コマンド

oss ls — バケット/オブジェクトの列挙```bash

oss ls # 列举所有桶 oss ls s3://b/dir/ --limit 50 # 默认目录式（delimiter=/），首页 50 条 oss ls s3://b/dir/ --limit 50 # 再次运行自动从断点继续（token 已缓存） oss ls s3://b/dir/ --reset # 忽略缓存，从头列举 oss ls s3://b/dir/ --next-token # 显式指定 token（覆盖缓存） oss ls s3://b/dir/ -d # 只列目录（PRE=目录/公共前缀） oss ls s3://b/dir/ -f --include "*.gz" # 只列文件，glob 过滤 oss ls s3://b --all # 流式列举全部（常数内存） oss ls s3://b -r # 平铺所有 key（不分目录） oss ls s3://b --all -j > list.ndjson # NDJSON 流式输出，适合管道处理 oss ls s3://b --export list.xlsx # 导出文件列表为 Excel

ls は「見る」ことだけを担当する（一覧表示/フィルタ/エクスポート）。**ダウンロード/アップロードには `cp` を使用**（後述）。

パラメータ分類（`oss ls -h` で完全な説明を確認可能）：