stashx

stashx

一款轻量、高效的命令行工具，助您轻松管理本地与 S3 兼容的云对象存储服务。

stashx 是一款功能强大的跨平台命令行工具，旨在将您从繁琐的网页控制台操作中解放出来。通过它，开发者和团队可以更高效、更安全地在终端中管理云存储桶和文件，完美支持 AWS S3 及任何 S3 兼容的服务（如腾讯云 COS、阿里云 OSS 等）。

核心功能

• ✨ 优雅的交互体验：提供清晰的操作反馈、安全的默认设置和直观的命令设计，日期格式更易读。
• ⚙️ 多配置文件管理：通过 configure 命令轻松管理和切换不同环境（如 dev, staging, prod）的配置。
• ☁️ 兼容多云服务：不仅支持 AWS S3，还支持任何 S3 兼容的存储服务。
• 🌐 自定义域名支持：可在配置文件中设置自定义域名，上传后显示更友好的访问链接。
• 🪣 默认存储桶：可为每个配置文件设置默认存储桶，简化常用命令。
• 🗂️ 强大的文件操作：支持文件和目录的上传 (push)、下载 (pull) 和删除 (rm)。
• 🎯 智能路径推断：push 和 pull 命令在未指定远程/本地路径时，可智能推断目标路径。
• 🔍 精准过滤：push 和 pull 命令支持 --include 和 --exclude 选项，通过 Glob 模式精确控制文件。
• *️⃣ 通配符支持：在下载 (pull) 和删除 (rm) 操作中可使用 Glob 模式进行灵活的文件匹配。
• 🔄 递归操作：使用 --recursive 标志轻松上传整个目录。
• 🧪 空跑模式 (Dry Run)：在执行 push, pull, rm 等敏感操作前，使用 --dry-run 预览变更，确保万无一失。
• 📊 操作摘要：在文件操作完成后，提供清晰的摘要信息（如传输文件数、总大小等）。
• 🛡️ 安全第一：对于删除等破坏性操作，默认启用交互式确认，防止意外数据丢失。

安装

确保您已安装 Node.js (推荐 LTS 版本)，然后执行以下命令进行全局安装：

npm install -g stashx

安装完成后，您就可以在终端的任何位置使用 stashx 命令了。

快速入门

1. 配置您的云服务信息

在使用前，您需要至少创建一个配置文件来存储云服务的凭证。

stashx configure set

工具会引导您输入以下信息：

• Profile name: 配置文件的别名 (例如 default, work-cos)。
• Access Key ID: 您的访问密钥 ID。
• Secret Access Key: 您的访问密钥 Secret。
• Default Region: 服务的默认地域 (例如 ap-guangzhou)。
• Endpoint URL (可选): 使用非 AWS 服务的关键。例如，腾讯云 COS 广州地域请填写 https://cos.ap-guangzhou.myqcloud.com。
• Default Bucket (可选): 设置一个默认存储桶，后续操作将优先使用它。
• Custom domain for S3 URLs (可选): 设置一个自定义域名，上传成功后将显示 https://<your-domain>/<object-key> 格式的链接。

2. 开始使用

配置完成后，即可开始管理您的云存储。

列出所有存储桶：

stashx ls

列出默认存储桶中的对象：

# 如果您在配置文件中设置了 default bucket
stashx ls

# 或者手动指定存储桶
stashx ls --bucket my-bucket

上传一个本地文件夹到存储桶：

# 智能推断远程路径为 my-local-folder/
stashx push ./my-local-folder/ --bucket my-bucket --recursive

# 或者手动指定远程路径
stashx push ./my-local-folder/ remote-folder/ --bucket my-bucket --recursive

命令参考

stashx configure - 管理配置文件

• stashx configure set <name>: 创建或更新一个配置文件。
• stashx configure list: 列出所有已保存的配置文件。
• stashx configure get <name>: 显示指定配置文件的详细信息。
• stashx configure delete <name>: 删除一个指定的配置文件。

stashx ls [remote_prefix] - 列出存储桶或对象

• 列出所有存储桶:

  stashx ls
  

• 列出指定存储桶中的对象:

  stashx ls --bucket <bucket-name>
  

• 列出指定目录下的对象:

  stashx ls my-folder/ --bucket <bucket-name>
  

stashx push <local-path> [remote-key] - 上传文件或目录

• 上传单个文件 (智能推断远程 key):

  stashx push ./local-file.txt --bucket <bucket-name>
  

• 上传单个文件 (指定远程 key):

  stashx push ./local-file.txt remote-file.txt --bucket <bucket-name>
  

• 递归上传整个目录 (智能推断远程 key):

  stashx push ./local-dir/ --bucket my-bucket --recursive
  

• 递归上传整个目录 (指定远程 key):

  stashx push ./local-dir/ remote-dir/ --bucket my-bucket --recursive
  

• 上传时排除特定文件:

  stashx push ./local-dir/ --bucket my-bucket --recursive --exclude "*.log,temp/**"
  

• 上传时只包含特定文件:

  stashx push ./local-dir/ --bucket my-bucket --recursive --include "*.jpg,images/**"
  

• 空跑模式，预览将要上传的文件:

  stashx push ./local-dir/ remote-dir/ --bucket my-bucket --recursive --dry-run
  

stashx pull <remote-key> [local-path] - 下载对象

• 下载单个对象 (智能推断本地路径):

  stashx pull remote-file.txt --bucket <bucket-name>
  

• 下载单个对象 (指定本地路径):

  stashx pull remote-file.txt ./local-file.txt --bucket <bucket-name>
  

• 使用通配符下载多个对象 (智能推断本地路径):

  stashx pull "logs/*.log" --bucket <bucket-name>
  

• 下载时排除特定对象:

  stashx pull "my-folder/**" --bucket my-bucket --exclude "*.tmp,cache/**"
  

• 下载时只包含特定对象:

  stashx pull "my-folder/**" --bucket my-bucket --include "*.json,data/**"
  

• 空跑模式，预览将要下载的对象:

  stashx pull "logs/*.log" ./retrieved-logs/ --bucket <bucket-name> --dry-run
  

stashx rm <remote-key> - 删除对象

• 删除单个对象 (有确认提示):

  stashx rm path/to/remote-file.txt --bucket <bucket-name>
  

• 使用通配符删除多个对象:

  stashx rm "images/old-*.jpg" --bucket <bucket-name>
  

• 强制删除 (无确认提示):

  stashx rm path/to/file.txt --bucket <bucket-name> --force
  

stashx rb <bucket-name> - 删除存储桶

• 删除一个空的存储桶 (有确认提示):

  stashx rb <bucket-name>
  

全局选项

• --profile, -p <name>: 使用指定的配置文件 (默认为 default)。
• --bucket, -b <name>: 指定本次操作的目标存储桶。
• --recursive, -r: 递归操作目录 (仅 push 命令支持)。
• --exclude, -e <patterns...>: 排除符合 Glob 模式的文件或对象。
• --include, -i <patterns...>: 只包含符合 Glob 模式的文件或对象。
• --dry-run: 预览操作，不实际执行。
• --help: 显示帮助信息。

协议

本项目基于 MIT License 开源。