S3 Upload

Operate S3-compatible storage (Qiniu Kodo, MinIO, AWS S3, etc.) via

scripts/s3-cli.js

. Configurations come from environment variables, consistent with

src/app-agent/lib/server/s3-storage.ts

and

.env-template

Agent Workflow

Check Configuration First — Do not guess credentials when not configured, prompt the user to complete
```
.env
```
:
bash
```
node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js config
```
Select Command — Use
```
upload
```
for uploading;
```
list
```
for browsing;
```
find
```
for searching by name;
```
url
```
for getting public links.
Prioritize
--json
— Use JSON output when results need to be parsed for subsequent steps.
Execute from Repository Root — Depends on
```
@aws-sdk/client-s3
```
in the root directory's
```
node_modules
```
.
--yes
Required for Deletion — Avoid accidental deletion; confirm with the user before deleting.
Must Provide Correct Feedback on Failure — See "Error Handling" below; do not fabricate URLs or pretend uploads were successful.

Error Handling (Mandatory for Agent)

When the CLI fails, exit code = 1. When adding

--json

, stdout is structured JSON (containing

code

error

hint

), and the Agent must parse it before replying to the user.

User Reply Format

When failing, inform the user in this structure:

What Happened — Reference the
```
error
```
field
Possible Cause — Combine
```
code
```
with context
Next Steps — Reference the
```
hint
```
; if auto-fix is available (e.g.,
```
--no-acl
```
), attempt it first before reporting

Prohibited: Ignore exit code; treat stderr as success; reply with public URL without verification; show complete Secret Key to users.

Error Code Reference

`code`	Meaning	Agent Action
`CONFIG_MISSING`	Missing environment variables	List the `missing` variables, point to `.env-template` , ask the user to complete them and re-run `config`
`INVALID_CREDENTIALS`	Invalid credentials	Ask the user to check AK/SK, do not blindly retry with the same invalid credentials
`ACCESS_DENIED`	Permission denied	Explain insufficient permissions; if the hint mentions `--no-acl` during upload, automatically retry once
`ACL_NOT_SUPPORTED`	ACL not supported	Retry upload with `--no-acl`
`BUCKET_NOT_FOUND`	Bucket does not exist	Check if `S3_BUCKET_NAME` matches `S3_ENDPOINT`
`OBJECT_NOT_FOUND`	Object does not exist	Suggest using `list --prefix` / `find` to locate the correct key
`LOCAL_FILE_NOT_FOUND`	Local file does not exist	Check the path and whether cwd is in the repository root
`DELETE_REQUIRES_CONFIRM`	`--yes` not added	Confirm with the user before adding `--yes`
`USAGE_ERROR`	Missing parameters	Correct the command according to the hint, do not guess parameters
`NETWORK_ERROR`	Network/endpoint unreachable	Check endpoint, region, and proxy
`DEPENDENCY_MISSING`	Missing SDK	Retry after running `bun install` in the repository root
`S3_ERROR`	Other S3 errors	Report `error` + `details` / `httpStatus` , suggest running `config`

Diagnostic Flow

Command failed (exit 1)
  ├─ Re-run with --json, read code
  ├─ CONFIG_* / INVALID_CREDENTIALS → config
  ├─ OBJECT_NOT_FOUND → list/find to locate key
  ├─ ACCESS_DENIED + upload → try --no-acl
  └─ Still failed → Report error/hint/details as is, do not modify credentials without permission

Example: User Feedback

Missing Configuration:

S3 is not fully configured, missing
S3_SECRET_ACCESS_KEY
. Please complete it in the
.env
file at the project root (refer to
.env-template
), and I will verify it after saving.

Upload ACL Failure (Agent should retry first):

The storage does not support ACL. Has re-uploaded successfully using
--no-acl
. Public URL: …

Object Not Found:

The object
assets/demo/missing.png
does not exist in the bucket. There are 3 files under current
assets/demo/
: …

Quick Start

bash

node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js --help
node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js config

Upload and get public URL:

bash

node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js upload ./local.png --prefix assets/demo/

List / Find:

bash

node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js list --prefix uploads/ --max 50
node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js find "photo" --prefix assets/
node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js find "*.png" --prefix assets/

Download / Delete / URL:

bash

node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js download assets/demo/photo.png --output ./photo.png
node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js url assets/demo/photo.png
node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js delete assets/demo/old.png --yes

Environment Variables

Variable	Required	Description
`S3_BUCKET_NAME`	Yes	Storage bucket
`S3_ACCESS_KEY_ID`	Yes	Access Key
`S3_SECRET_ACCESS_KEY`	Yes	Secret Key
`S3_ENDPOINT`	Yes	Service endpoint (e.g., `https://s3.cn-south-1.qiniucs.com` )
`S3_REGION`	No	Defaults to `cn-south-1` (Qiniu); fill in `cn-hangzhou` etc. for Alibaba Cloud
`S3_CDN`	No	CDN domain name; `url` / upload results will use CDN to generate public URLs first
`S3_PROVIDER`	No	Provider identifier ( `kodo` / `aliyun` / `minio` etc.); when `aliyun` is set, upload does not include ACL by default

The CLI automatically reads the

.env

file in the repository root (does not overwrite existing

process.env

). You can also explicitly pass

node --env-file-if-exists=.env

Do NOT write credentials into skills, scripts, or commit to git. Only read from

.env

or user-provided env.

Alibaba Cloud OSS (

S3_PROVIDER=aliyun

)

env

S3_BUCKET_NAME=<bucket>
S3_ACCESS_KEY_ID=<RAM AccessKey ID>
S3_SECRET_ACCESS_KEY=<RAM AccessKey Secret>
S3_ENDPOINT=https://<bucket>.s3.oss-<region>.aliyuncs.com
S3_REGION=cn-hangzhou
S3_CDN=https://<your-cdn-domain>
S3_PROVIDER=aliyun

Key Points:

Endpoint — Recommended S3-compatible format:
```
https://<bucket>.s3.oss-cn-hangzhou.aliyuncs.com
```
(consistent with
```
S3_BUCKET_NAME
```
); you can also use
```
https://s3.oss-cn-hangzhou.aliyuncs.com
```
(path-style). The CLI will automatically detect whether the endpoint contains a bucket subdomain.
Region — Consistent with the region in the endpoint (e.g.,
```
cn-hangzhou
```
), do not use placeholder
```
<your-region>
```
.
ACL — New OSS buckets usually disable Object ACL; the CLI does not upload ACL by default when
```
aliyun
```
is set. If you still get an ACL error, explicitly add
```
--no-acl
```
.
Public URL — When
```
S3_CDN
```
is configured:
```
https://cdn.example.com/<objectKey>
```
; ensure the CDN is bound to the bucket and origin-pull is enabled.
RAM Permissions — The credentials need permissions like
```
oss:PutObject
```
,
```
oss:GetObject
```
,
```
oss:ListObjects
```
,
```
oss:DeleteObject
```
for the target bucket.

Command Reference

Command	Purpose
`config`	Verify configuration, output credentials in desensitized format
`upload <file>`	Upload; options: `--key` / `--prefix` / `--content-type` / `--acl` / `--no-acl`
`list`	List by `--prefix` ; `--max` limits the number of items
`find <pattern>`	Substring or wildcard ( `*` `?` ) search for keys; use with `--prefix`
`head <key>`	Check existence and metadata
`download <key>`	Download; `--output` specifies the path
`delete <key> --yes`	Delete object
`url <key>`	Output public URL

Global options:

--json

-h

--help

Relationship with Application Code

Server-side upload logic can be found in
```
src/app-agent/lib/server/s3-storage.ts
```
(Presigned POST, CDN URL parsing, etc.).
Agent operation/one-time upload uses this skill's CLI; do not rewrite SDK logic in conversations.
In-app functions continue to use
```
s3-storage.ts
```
or existing OSS pipelines; do not mix with the CLI.

Common Scenarios

User wants to upload screenshots/build artifacts and share links

bash

node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js upload ./dist/bundle.zip --key releases/v1.2.0/bundle.zip --json

Extract

publicUrl

from JSON to reply to the user.

User asks which files are under a certain prefix

bash

node --env-file-if-exists=.env .cursor/skills/s3-upload/scripts/s3-cli.js list --prefix static/_next/ --max 100 --json

User provides a CDN URL and wants to confirm if the key exists

Use the logic of

objectKeyFromPublicUrl

: remove the CDN prefix to get the key, then run

head

Configuration Error

Missing required env → CLI returns

CONFIG_MISSING

and

missing

array → Ask the user to complete it by referring to

.env-template

→ Re-run

config

until

ok: true

CLI JSON Error Example

json

{
  "ok": false,
  "code": "ACL_NOT_SUPPORTED",
  "error": "Current storage does not support ACL field",
  "hint": "Retry: upload <file> ... --no-acl",
  "details": "…"
}

The Agent should execute the retry in the hint, then reply to the user after success.

Do NOT Define
S3_*
Repeatedly in
.env

When multiple sets of variables like

S3_BUCKET_NAME

appear in the same file, the later ones will overwrite the earlier ones (Node

--env-file

behavior). Keep only one set of configurations, comment out old ones.

s3-upload

NPX Install

Tags

SKILL.md Content (Chinese)

S3 Upload

Agent Workflow

Error Handling (Mandatory for Agent)

User Reply Format

Error Code Reference

Diagnostic Flow

Example: User Feedback

Quick Start

Environment Variables

Alibaba Cloud OSS (
`S3_PROVIDER=aliyun`
)

Command Reference

Relationship with Application Code

Common Scenarios

s3-upload

NPX Install

Tags

SKILL.md Content (Chinese)

S3 Upload

Agent Workflow

Error Handling (Mandatory for Agent)

User Reply Format

Error Code Reference

Diagnostic Flow

Example: User Feedback

Quick Start

Environment Variables

Alibaba Cloud OSS (S3_PROVIDER=aliyun)

Command Reference

Relationship with Application Code

Common Scenarios

Alibaba Cloud OSS (
`S3_PROVIDER=aliyun`
)