filehost

name	filehost
description	Upload, replace, version, inspect, and delete hosted files with the filehost CLI. Use when an agent needs to publish a file or manage a filehost URL or ID.
compatibility	Requires the installed filehost binary and network access to a filehost service.
metadata	{"author":"stanley2058","version":"1.0"}

Filehost

FILEHOST_API_URL selects the service. FILEHOST_SECRET supplies optional mutation authentication.

CLI

filehost upload PATH             # create; prints the stable URL
filehost upload ID PATH          # replace contents; prints the stable URL
filehost delete ID               # delete the file and every version

The CLI has no download command; read returned URLs with an HTTP client. Use the bare ID for authenticated replace/delete operations. It is the final path segment of the stable URL.

Versions

The CLI prints only the stable URL. To preserve the current version before a replacement, read its SHA-256 ETag and append the full hash to the URL:

etag=$(curl --fail --silent --show-error --head --output /dev/null --write-out '%header{etag}' "$url")
hash=${etag#\"sha256-}
hash=${hash%\"}
version_url="${url}@${hash}"

Version selectors accept 6-64 case-insensitive hexadecimal characters, but returned version URLs or full hashes are safer than guessed prefixes.

Semantics

• Replace uploads are complete replacements, not binary patches.
• Reads are public and return the content type stored for that version.
• With FILEHOST_SECRET, create, replace, and delete require authentication.
• Without FILEHOST_SECRET, create and replace are public; delete is disabled.
• Delete is irreversible and removes every historical version.

Read api.md only when the CLI is insufficient or the task needs the full JSON upload response.