aliyunoss-cli

aliyunoss-cli

aliyunoss-cli recursively uploads a local directory to Alibaba Cloud Object Storage Service (OSS). It supports reusable JSON configuration, environment-specific source and target paths, and explicit command-line overrides.

• Project website
• Examples
• API documentation

Install

The package requires Node.js 22 or later. Install it as a development dependency in the project that produces the files you want to upload:

npm install --save-dev aliyunoss-cli
Copy

Configure

Create alioss.config.json in the directory where you run the command:

{
  "region": "oss-region-id",
  "accessKeyId": "your-access-key-id",
  "accessKeySecret": "your-access-key-secret",
  "bucket": "your-bucket",
  "releaseEnvConf": {
    "development": {
      "source": "dist/",
      "target": "site/development/"
    },
    "production": {
      "source": "dist/",
      "target": "site/production/"
    }
  }
}
Copy

The final configuration uses this precedence, from lowest to highest:

1. Base values in the JSON file.
2. Values from the selected releaseEnvConf entry.
3. Explicit command-line flags.

The command requires region, accessKeyId, accessKeySecret, bucket, source, and target after merging configuration.

Warning: Never commit real OSS access keys. Keep credentials in a protected local file or inject them through a secured continuous integration environment.

Upload a directory

Select a configured environment:

npx aliyunoss-cli --releaseEnv development
npx aliyunoss-cli --releaseEnv production
Copy

Override individual values for one run:

npx aliyunoss-cli \
  --releaseEnv production \
  --source public/ \
  --target static/
Copy

The command recursively discovers files beneath source and uploads each file beneath target. Do not point it at production credentials or a production bucket until you have verified the resolved paths and configuration.

Command options

Option	Purpose
--help	Show CLI help without starting an upload.
--version	Show the CLI version.
--config	Select a configuration file. The default is ./alioss.config.json.
--releaseEnv	Select an entry from releaseEnvConf.
--source	Override the local source directory.
--target	Override the Alibaba Cloud OSS target path.
--accessKeyId	Override the Alibaba Cloud OSS access key ID.
--accessKeySecret	Override the Alibaba Cloud OSS access key secret.
--bucket	Override the Alibaba Cloud OSS bucket.
--region	Override the Alibaba Cloud OSS region.

Run npx aliyunoss-cli --help to inspect the CLI without uploading files.

Use the package root

The package root re-exports the ali-oss client constructor for compatibility:

const OSS = require("aliyunoss-cli");

const client = new OSS({
  region: "oss-region-id",
  accessKeyId: "your-access-key-id",
  accessKeySecret: "your-access-key-secret",
  bucket: "your-bucket",
});
Copy

Creating a client does not upload data. An OSS operation such as client.put() performs a network request.

Develop

This repository uses pnpm for reproducible dependency installation:

corepack enable
pnpm install
pnpm run typecheck
pnpm run lint
pnpm test
pnpm run build
pnpm run docs
pnpm run format:check
Copy

pnpm run docs creates and validates the final GitHub Pages artifact in docs/. Generated bin/, lib/, dist-dev/, docs/, and coverage/ output must be changed through source or build configuration rather than manual edits.

License

MIT