Ali OSS Upload CLI

A simple and robust CLI for uploading files or directories to Alibaba Cloud OSS.

Features

• Upload entire directories or specific files.
• Filter files using glob patterns.
• Configure via CLI flags or ".env" file.
• Atomic uploads for entry files (like index.html) to prevent deployment inconsistencies.
• Adjustable request timeout for large files.

Installation

Install locally as a development dependency:

npm install --save-dev ali-oss-upload-cli

Or install globally to use from anywhere:

npm install -g ali-oss-upload-cli

Configuration

Create a .env file in your project root:

# .env
OSS_REGION=your-oss-region
OSS_BUCKET=your-bucket-name
OSS_KEY=your-access-key-id
OSS_SECRET=your-access-key-secret

Remember to add .env to your .gitignore file.

Usage

oss-upload <local-path> -o <remote-path> [options]

• <local-path>: The local file or directory to upload.
• -o, --output <remote-path>: Required. The destination path (prefix) in your OSS bucket.

Options

| Flag | Description | Default | |---|---|---| | -o, --output <path> | Required. Remote destination path (prefix). | — | | --atomic-entry <glob> | Glob pattern for entry files to upload atomically. | null | | --filter <pattern> | Glob pattern to filter which files to upload. | **/* | | --region <region> | OSS region. Overrides .env. | OSS_REGION | | --bucket <name> | OSS bucket name. Overrides .env. | OSS_BUCKET | | --key <id> | Access Key ID. Overrides .env. | OSS_KEY | | --secret <secret> | Access Key Secret. Overrides .env. | OSS_SECRET | | --timeout <ms> | Request timeout in milliseconds. | 60000 | | --envfile <path> | Path to a custom environment file. | .env | | -h, --help | Display the help menu. | — | | -v, --version | Display the tool version. | — |

Examples

1. Upload a build directory

# Uploads the entire 'dist' directory to the '/static' folder in your bucket
oss-upload dist -o /static

2. Upload only specific file types

# Upload only .js files from the 'dist' directory
oss-upload dist -o /assets/js --filter "**/*.js"

3. Atomic Upload for a Single-Page App (SPA)

To prevent users from experiencing a broken site during deployment, you can use atomic uploads. This ensures that your index.html is only updated after all its new JS and CSS assets have been successfully uploaded.

# All assets are uploaded first, then index.html is updated atomically.
oss-upload dist -o / --atomic-entry "index.html"

This is the recommended way to deploy web applications.

4. Use with CI/CD

Provide credentials directly as flags, ignoring any .env file.

oss-upload dist -o / \
  --region oss-cn-hangzhou \
  --bucket my-app-bucket \
  --key $OSS_ACCESS_KEY_ID \
  --secret $OSS_ACCESS_KEY_SECRET

Environment Variables

The tool will automatically use the following variables from your .env file:

• OSS_REGION
• OSS_BUCKET
• OSS_KEY
• OSS_SECRET

CLI flags always take precedence over environment variables.

License

MIT