okfile 1.3.0

Python CLI for uploading files and publishing static sites to OkFile

OkFile

Agent-first file upload and publish service built on Cloudflare Pages Functions, R2, and D1.

• Website: https://www.okfile.com
• Repository: https://github.com/okfilecom/okfile
• License: Apache-2.0

Python CLI

The published Python package name is okfile.

Install the latest release from PyPI:

py -3 -m pip install okfile
okfile --version

Install a pinned version when you need reproducible environments:

py -3 -m pip install okfile==1.3.0

Upgrade to the latest release:

py -3 -m pip install --upgrade okfile

Fallback wheel install:

py -3 -m pip install "https://www.okfile.com/downloads/okfile-1.3.0-py3-none-any.whl"

• PyPI: https://pypi.org/project/okfile/
• CLI skill doc: ./SKILL.md

Common CLI examples:

okfile upload photo.jpg
okfile upload video.mp4 --multipart-concurrency 3
okfile upload archive.zip --multipart-concurrency 6 --max-downloads 10
okfile upload photo.jpg --expires-at 2026-12-31T23:59:59Z
okfile publish ./my-site/
okfile publish ./my-site/ --expires-at 2026-12-31T23:59:59Z
okfile status a3k7m92x
okfile config --key okf_xxxxx

Help examples:

okfile upload --help
okfile publish --help
okfile status --help

Notes:

• okfile upload defaults to --multipart-concurrency 3 for multipart uploads
• larger values can improve throughput for bigger files, but small files may not benefit

What It Does

OkFile is designed for Agents, scripts, and lightweight manual upload use cases.

It supports:

• anonymous uploads
• authenticated uploads with user API keys
• direct file URLs for download or embedding
• preview/playback URLs for image, video, and PDF
• anonymous single-file uploads up to 500MB
• API Key uploads up to 1TB per file
• temporary retention for anonymous uploads, with current default expiry at 24 hours
• multipart upload for larger authenticated files
• phase-1 site directory upload with nested subdirectories and per-site subdomain publish URLs
• automatic shared top-level directory stripping for folder-based site uploads
• directory listing fallback when a published site does not contain root index.html
• retrying only missing parts after incomplete multipart uploads
• email magic-link login and account management
• localized home, upload, and account pages

Main User Flows

1. Anonymous Publish

1. POST /api/upload/prepare
2. PUT uploadUrl or each parts[].uploadUrl
3. POST /api/upload/complete
4. return url and optionally playUrl
5. current single-file limit is 500MB, and uploaded files expire after 24 hours

2. API Key Publish

1. request a magic link and log in
2. create an API key in /account
3. call POST /api/upload/prepare with X-API-Key header
4. upload file data to signed URLs
5. call POST /api/upload/complete
6. current single-file limit is 1TB when a valid API key is used

3. Manual Upload

Users can also use:

• /zh/upload/
• /en/upload/

This path is kept as a fallback entry, while API integration remains the recommended flow.

4. Site Directory Publish

1. select a whole folder in /zh/upload/ or /en/upload/
2. the uploader preserves nested relative paths
3. if every file sits under one shared top-level folder, that folder is stripped and treated as the site root
4. if the site contains root index.html, / renders that page
5. if root index.html does not exist, / renders a directory listing with file name, size, and upload time
6. image and video entries open inline, while other files use download links

Architecture

Runtime

• Cloudflare Pages Functions for routing and API handling
• Cloudflare Worker route for *.ok26.org/* site subdomains
• Cloudflare R2 for file storage
• Cloudflare D1 for auth and API key metadata
• Resend for email magic links

Frontend

• static index.html for homepage
• static upload.html for manual upload
• server-side localization and SEO injection in worker-app.js

Backend Responsibilities

• issue presigned R2 upload URLs
• complete multipart uploads
• activate public file routes
• resolve published site subdomains from request Host
• manage sessions, magic links, and API keys
• enforce anonymous and per-key quota limits

Core Routes

Pages

• /zh/ and /en/: localized home pages
• /zh/upload/ and /en/upload/: manual upload pages
• /account: redirects to localized account page
• /zh/account/ and /en/account/: localized account pages
• /admin: admin console

Upload APIs

• POST /api/upload/prepare
• POST /api/upload/complete
• GET /api/upload/status/{id}
• authenticated automation should send X-API-Key: okf_...

Authenticated prepare example:

curl -X POST "https://www.okfile.com/api/upload/prepare" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: okf_..." \
  --data '{"filename":"photo.jpg","size":12345,"contentType":"image/jpeg"}'

Auth APIs

• POST /api/auth/request-link
• GET /auth/verify?token=...
• GET /api/account/me
• POST /api/account/api-keys

File URLs

• /i/{id}: direct file URL
• /i/{id}?play=1: preview/playback page
• /d/{id}: controlled download route

Site URLs

• https://{subdomain}.ok26.org/: site root or directory listing
• https://{subdomain}.ok26.org/path/to/file: published site asset or document
• https://{subdomain}.ok26.org/path/to/file?download=1: force download for a site file

Repository Layout

.
|- worker-app.js                      # main Pages Function entry
|- index.html                         # homepage
|- upload.html                        # manual upload page
|- schema.sql                         # D1 schema
|- wrangler.toml                      # Cloudflare config
|- SKILL.md                           # root skill document
|- .trae/skills/okfile/SKILL.md       # Trae skill definition
|- okfile-upload-pitfalls.md          # upload pitfalls and debugging notes

Local Development

Install dependencies:

npm install

Run local development:

npx wrangler pages dev .

Deploy to Cloudflare Pages:

npx wrangler pages deploy . --project-name okfile --branch main

Configuration

Store secrets in Cloudflare, not in the repository.

Secrets

• R2_ACCESS_KEY_ID
• R2_SECRET_ACCESS_KEY
• RESEND_API_KEY

Plain-Text Vars

• R2_ACCOUNT_ID
• RESEND_FROM_EMAIL
• ADMIN_EMAILS

Database

The D1 schema is defined in schema.sql and includes:

• users
• magic_links
• sessions
• api_keys
• api_key_usage_windows

Upload Notes

See these repo docs for integration details:

• SKILL.md
• SITE_UPLOAD_DESIGN.md
• .trae/skills/okfile/SKILL.md
• okfile-upload-pitfalls.md

The pitfalls doc includes practical notes such as:

• Cloudflare requiring a normal User-Agent for some requests
• explicit Content-Length on R2 PUT
• multipart retry strategy
• large-file client recommendations on Windows

For site publishing:

• use root index.html when you want the subdomain root to render a page
• if you upload a single wrapper folder such as my-site/..., OkFile strips my-site/ automatically
• if no root index.html exists, users land on a browsable directory listing instead of downloading an arbitrary file

Articles

Published and outward-facing articles are archived in docs/:

• docs/README.md
• docs/devto-agent-delivery-publish-file-or-site-test-guide.md
• docs/aliyun-workbuddy-agent-file-site-publish-test-guide.md

Contributing

Please read CONTRIBUTING.md before opening pull requests.

Security

Please read SECURITY.md for reporting instructions and secret-handling rules.

Changelog

See CHANGELOG.md for release notes tracked in-repo.

License

Apache-2.0