# file-share

> Convert local files to shareable URLs. Use this tool when: (1) You generate files that need to be shared with users - get accessible URLs instead of outputting raw content; (2) You generate HTML/web pages that need to reference assets (images, CSS, JS) - upload assets first to get URLs for embedding. Also supports transferring third-party URLs to your own domain.

- Author: wangyaoyao
- Repository: yyobject/file-share
- Version: 20260129210005
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/yyobject/file-share
- Web: https://mule.run/skillshub/@@yyobject/file-share~file-share:20260129210005

---

---
name: file-share
description: Convert local files to shareable URLs. Use this tool when: (1) You generate files that need to be shared with users - get accessible URLs instead of outputting raw content; (2) You generate HTML/web pages that need to reference assets (images, CSS, JS) - upload assets first to get URLs for embedding. Also supports transferring third-party URLs to your own domain.
---

# File Share

Upload files and get shareable URLs. Uses pre-compiled Go binaries, **no dependencies required**.

## Entry Point

Use `./file-share` script, **auto-detects platform**, no need to select binary manually:

```bash
./file-share [options] <files...>
```

## Pre-flight Check (Important)

Before uploading, **must check if configuration is ready**:

```bash
./file-share --check
```

Output example:
```json
{
  "ready": false,
  "env_vars": {
    "access_key_id": false,
    "access_key_secret": false,
    "bucket_name": false,
    "endpoint": false
  },
  "missing": ["access_key_id", "..."],
  "suggestions": ["Missing config: ...", "Configuration methods: ..."]
}
```

If `ready: false`, guide user to configure based on `suggestions`.

## Configuration

All configuration uses `.env` file format. **Priority from low to high**:

### 1. User home directory (global default)
```bash
~/.oss-upload.env
```

### 2. Skill directory
```bash
<skill-dir>/.env
```

### 3. Current working directory
```bash
.env
```

### 4. Environment variables (highest priority)
```bash
export OSS_ACCESS_KEY_ID=xxx
```

Higher priority config overrides lower priority values.

## Configuration Options

| Environment Variable | Required | Description |
|---------------------|----------|-------------|
| `OSS_ACCESS_KEY_ID` | ✅ | Alibaba Cloud AccessKey ID |
| `OSS_ACCESS_KEY_SECRET` | ✅ | Alibaba Cloud AccessKey Secret |
| `OSS_BUCKET_NAME` | ✅ | Bucket name |
| `OSS_ENDPOINT` | ✅ | Region endpoint |
| `OSS_DOMAIN` | ❌ | Custom domain |
| `OSS_PREFIX` | ❌ | File path prefix |

## Configuration File Example

Copy `.env.example` to `.env` and fill in your credentials:

```bash
# Required
OSS_ACCESS_KEY_ID=your-access-key-id
OSS_ACCESS_KEY_SECRET=your-access-key-secret
OSS_BUCKET_NAME=your-bucket-name
OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com

# Optional
OSS_DOMAIN=
OSS_PREFIX=uploads
```

## Usage

### Single file upload

```bash
./file-share file.txt
```

### Upload from URL (transfer from third-party)

Download from URL and re-upload to OSS:

```bash
./file-share https://example.com/image.png
```

Multiple URLs:

```bash
./file-share https://example.com/a.png https://other.com/b.jpg
```

Mix local files and URLs:

```bash
./file-share local.txt https://example.com/remote.png
```

### Multiple files upload separately (one URL per file)

```bash
./file-share file1.txt file2.txt file3.txt
```

### Multiple files bundled as zip (one URL)

```bash
./file-share --zip file1.txt file2.txt file3.txt

# Specify zip filename
./file-share --zip --zip-name archive.zip file1.txt file2.txt
```

### Specify OSS path prefix

```bash
./file-share --prefix uploads/2024 file.txt
```

## Output Format

JSON format output for easy parsing:

**Single/multiple files upload separately:**
```json
{
  "success": true,
  "mode": "separate",
  "results": [
    {"file": "file1.txt", "url": "https://..."},
    {"file": "file2.txt", "url": "https://..."}
  ]
}
```

**Zip upload:**
```json
{
  "success": true,
  "mode": "zip",
  "zip_name": "archive.zip",
  "files_included": ["file1.txt", "file2.txt"],
  "url": "https://..."
}
```

## Command Line Options

| Option | Description |
|--------|-------------|
| `--check` | Check if configuration is ready |
| `--zip` | Bundle files into zip before upload |
| `--zip-name NAME` | Specify zip filename (auto-generated by default) |
| `--prefix PATH` | Specify OSS path prefix |
| `--no-timestamp` | Don't add timestamp suffix (keep original filename) |
| `--recursive` | Recursively upload directory |
| `--preserve-path` | Preserve directory structure when zipping |
| `--quiet` | Quiet mode, only output URLs (for scripting) |
| `--dry-run` | Preview mode, only show file list |
| `--config FILE` | Specify config file path |
| `--version` | Show version |

## Advanced Usage

### Output URLs only (for piping/scripting)
```bash
./file-share --quiet file.txt
# Output: https://bucket.oss-cn-hangzhou.aliyuncs.com/file_20240129_123456.txt

# Combine with other commands
URL=$(./file-share --quiet file.txt)
echo "File uploaded: $URL"
```

### Keep original filename (no timestamp)
```bash
./file-share --no-timestamp file.txt
```

### Recursively upload directory
```bash
./file-share --recursive ./dist/
```

### Preview files to upload
```bash
./file-share --dry-run --recursive ./dist/
# Output:
# Will upload 5 files:
#   ./dist/index.html
#   ./dist/style.css
#   ...
```

### Preserve directory structure when zipping
```bash
./file-share --recursive --zip --preserve-path ./src/
# zip will contain paths like src/components/Button.tsx
```

### Specify config file
```bash
./file-share --config /path/to/.env file.txt
```

### Combine options
```bash
# Recursively upload directory as zip, output URL only
./file-share --recursive --zip --quiet ./build/
```

## Supported Platforms

Script auto-detects and uses corresponding binary:
- macOS (Apple Silicon / Intel)
- Linux (x86_64 / ARM64)
- Windows (x64)

## Troubleshooting

### macOS: "cannot be opened because the developer cannot be verified"

This only happens on macOS when downloaded via browser. Run:

```bash
xattr -cr ./file-share ./bin/*
```

### Permission denied (any platform)

If execute permission is missing:

```bash
chmod +x ./file-share ./bin/*
```

## Notes

- Filenames automatically get timestamp suffix to avoid overwriting
- Supports wildcards like `*.txt`
- No dependencies required, works out of the box
- URLs (http:// or https://) are automatically detected and downloaded before upload