postfile

Upload one immutable file and return a share URL. This package belongs to Postfile, the binary-sharing fork of Postplan. Its credentials live separately in ~/.postfile.

Build/pack from the workspace with pnpm pack:cli. Until npm publication is configured, install postfile-cli.tgz locally or run the built executable:

node packages/cli/dist/postfile.js auth set <postfile-key>
node packages/cli/dist/postfile.js upload ./capture.png --kind screenshot --json

After installation, use postfile directly. The default API origin is https://postfile.martinvana.com. POSTFILE_API_KEY and POSTFILE_API_URL override saved credentials. --api-url overrides the URL; a saved key is sent only to its saved origin. Environment-provided keys are sent to the selected origin. HTTPS is required outside loopback. For local development, set POSTFILE_API_URL=http://127.0.0.1:8787. POSTFILE_HOME isolates local credential/retry state for tests.

postfile check ./capture.png --kind screenshot --json
postfile upload ./capture.png --kind screenshot --json
postfile upload ./recording.webm --kind recording --disposable --json
postfile upload ./sensitive.png --kind screenshot --private --json
postfile upload ./important.png --kind screenshot --pin --json
postfile list --json
postfile usage --json
postfile status <file-id> --json
postfile pin <file-id>
postfile unpin <file-id>
postfile private <file-id>
postfile unlisted <file-id>
postfile retain <file-id>
postfile disposable <file-id>
postfile delete <file-id>
postfile key create agent --json
postfile key revoke <key-id>
postfile auth clear

Unlisted links are readable by anyone with the URL. Private links require owner credentials. For browser previews, authenticate at the server's /auth route using username postfile and the key as the password, then open the private file. Never paste the key into a URL. Browsers cache Basic credentials until their authentication cache is cleared or the session ends. Revocation is checked on every private read.

Screenshots default to disposable only with explicit --kind screenshot. Other files, including GIFs and recordings, default to retained. --retain, --disposable, and --pin control cleanup independently of visibility. Eligible captures can be removed under storage pressure after seven days; this is not a promised expiry.

Limits are decimal 20 MB raster image, 50 MB GIF, and 90 MB video/other. --mime-type declares a MIME claim that must agree with the bytes to receive a preview. HTML/SVG and conflicting/unknown formats download as attachments. --metadata <json-file> adds up to 8 KB owner-only JSON.

check never reserves space. An unauthenticated check validates locally with offline: true and quotaReady: null; upload requires credentials. JSON errors are written to stdout and exit with status 1.

After a timeout, repeat the identical upload command. Pending retry state retains the idempotency key and recovers a committed receipt. Each invocation after a completed upload creates a new immutable file. --idempotency-key <key> explicitly controls retries and remains bound to the account and full manifest. A terminal failure needs a fresh key. Folder inputs are rejected. list --cursor <cursor> continues pagination.

The bundled postfile agent skill documents capture sharing, privacy, retention, and retry handling. The distributable bundles its client dependencies and shared contracts; it requires no workspace packages at runtime. The default Cloudflare service is deployed; npm publication remains a separate setup step.