Upfile

About Upfile

Upfile turns a file on the host into a URL an agent can hand to a human or another service. There is no dashboard and no browser step anywhere in the loop: upfile.signup creates an account and saves the key locally, and from then on upfile.upload returns a live, permanent link.

Everything returns JSON. The upload methods emit {id, url, visibility, size, type, expires_at, storage_used, storage_limit}, so an agent reads .url rather than scraping console output.

Three shapes of link. A plain upload is public and permanent — an unauthenticated URL that keeps working. upload_private puts it behind authentication. upload_expiring gives it a TTL in seconds, which is the right choice for build logs, debug dumps, and anything you would rather not leave permanently reachable.

Housekeeping. status shows tier and quota, list enumerates what is stored with each file's id, and remove deletes one by id and reclaims the space. The free tier is 1GB total across all files.

The CLI ships with the app as a per-platform binary verified by sha256 at install, so there is no Node install and no package manager involved on the host.

Methods · 10

upfile.signupSTART HERE if this host has no API key. Creates an Upfile account and saves the key to the local CLI config, so every later call authenticates automatically. No browser, no dashboard, no verification step. The account starts on the free tier: 1GB of storage. Everything else fails with No API key until this has been run.upfile.uploadUpload a file from this host and get back a permanent, immediately-live URL. Returns JSON: {id, url, visibility, size, type, originalName, expires_at, created_at, storage_used, storage_limit}. Read .url. Public by default, which means an unauthenticated permanent link, so use upfile.upload_private or upfile.upload_expiring for anything you would not want to stay reachable.upfile.upload_privateUpload a file as private, so the returned URL requires authentication rather than being open to anyone holding the link. Same JSON shape as upfile.upload, with visibility private.upfile.upload_expiringUpload a file with a time-to-live, so the link stops working on its own. Use this for build logs, debug dumps, and anything you would rather not have permanently indexed. Same JSON shape as upfile.upload, with expires_at set.upfile.statusShow the account tier and how much of the storage quota is used, e.g. Tier: free Storage: 0.01GB / 1GB. Also the quickest way to tell whether this host has a key at all: without one it prints No API key, which means run upfile.signup first.upfile.listList the files stored on this account as JSON, newest first, with each file's id and URL. The ids are what upfile.remove takes.upfile.removeDelete one stored file by its id, reclaiming its space against the quota. IRREVERSIBLE: the URL stops resolving immediately.upfile.versionPrint the Upfile CLI version bundled with this app.upfile.cli_helpThe Upfile CLI's own full help text, listing every subcommand and flag including any not curated as a named method here.upfile.runEscape hatch: run the Upfile CLI with an arbitrary argv array, for anything the named methods do not cover such as config set/get, upgrade, or stdin uploads. Payload is {args:[...]}. Prefer the named methods when one fits, because they return JSON.

Full usage demo

When your agent has produced a file — a render, a report, a screenshot, a log — and needs a URL it can paste somewhere a human or another service will open.

Run this first — Get an account and an API key with one callCall

pilotctl appstore call io.pilot.upfile upfile.signup '{"email":"you@example.com"}'

→Account created. API key: upf_... Tier: free (1GB). Key saved.

The key is written to the CLI config on this host, so every later call just works. No dashboard, no browser.

Worked examples

Upload a file and get a permanent URLCall

pilotctl appstore call io.pilot.upfile upfile.upload '{"path":"/tmp/report.pdf"}'

→{"id":"tRbBqIyEiB","url":"https://cdn.upfile.sh/tRbBqIyEiB.pdf","visibility":"public","size":6941}

The URL is live immediately and permanent. Always JSON, so read .url straight out of it.

Upload something that should not live foreverCall

pilotctl appstore call io.pilot.upfile upfile.upload_expiring '{"path":"/tmp/build.log","expiry":3600}'

→{"id":"...","url":"https://cdn.upfile.sh/....log","expires_at":"2026-08-06T17:00:00.000Z"}

expiry is seconds. Use it for anything you would not want indexed a year from now.

Check what you have storedCall

pilotctl appstore call io.pilot.upfile upfile.status '{}'

→Tier: free Storage: 0.01GB / 1GB

Free tier is 1GB. upfile.list shows individual files; upfile.remove deletes one by id.

Good to know

• Run upfile.signup once per host if there is no key. Everything else fails with No API key until you do.
• Read .url from the JSON — the human-readable output is not stable.
• A plain upload is a permanent, unauthenticated URL. Use upload_private or upload_expiring for anything sensitive.
• expiry is in SECONDS, not minutes. 3600 is an hour.
• Free tier is 1GB total, not per file. Use upfile.remove to reclaim space.

Next

• io.pilot.upfile upfile.help '{}'

What’s New

v0.2.3Latest—

• First release on the Pilot app store.

Platform Compatibility

macOSApple SiliconSupportedmacOSIntelSupportedLinuxarm64SupportedLinuxamd64Supported