Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (52 loc) · 2.91 KB

AGENTS.md

File metadata and controls

74 lines (52 loc) · 2.91 KB
Raw

Quick Share Agent Notes

Quick Share is a CLI-first bridge to shared public assets in Cloudflare R2.

Use it when a project needs to find shared images, PDFs, exports, handoff files, or public asset URLs without guessing bucket paths.

Preferred Workflow

From any configured project:

quick-share where
quick-share health
quick-share images
quick-share urls
quick-share files client-name/

The CLI reads .quick-share.json from the current directory or a parent directory. If no config file exists, it falls back to QUICK_SHARE_API_URL.

Configure A Project

If there is no hosted Quick Share Worker yet, set it up first:

quick-share setup-service --bucket quick-share-assets --public-url https://YOUR-PUBLIC-BUCKET.r2.dev

This checks Wrangler, installs a local Wrangler dev dependency when needed, checks Cloudflare authentication, creates the R2 bucket, writes wrangler.toml, and deploys the Worker.

If authentication is missing, do not guess credentials. Ask Jack to run wrangler login or provide a scoped CLOUDFLARE_API_TOKEN.

From the project root:

quick-share init https://quick-share-api.example.workers.dev project-prefix/

Or configure another project from anywhere:

quick-share init https://quick-share-api.example.workers.dev project-prefix/ --project /path/to/project

This writes .quick-share.json and adds a short Quick Share section to that project's AGENTS.md if needed.

Important Boundaries

  • The asset-discovery CLI is read-only: it does not upload, delete, move or overwrite objects. The optional Raycast extension separately uploads a file explicitly chosen by its user to that user's configured public R2 bucket. It uses bucket-scoped preferences, unique object keys and no fallback to shell credentials.
  • Public-first: treat returned URLs as public.
  • Not authentication: do not use this for private client assets without adding signed URLs or auth.
  • Durability depends on the R2 object and public asset domain staying available.

Stable Commands

  • quick-share init <api-url> [prefix] [--project <dir>]
  • quick-share setup-service [--bucket <bucket>] [--public-url <url>] [--no-deploy]
  • quick-share health
  • quick-share manifest
  • quick-share files [prefix]
  • quick-share urls [prefix]
  • quick-share images [prefix]
  • quick-share open <filename-or-index> [prefix]
  • quick-share copy <filename-or-index> [prefix]
  • quick-share where

Jack’s Files browser application

The separate Pages app in assets/jack-files/ has authenticated upload and collection creation routes. Its config is deploy/jack-files/wrangler.json; deploy using npm run deploy:jack-files with the existing scoped Cloudflare credential. The public library and collection reads remain public. Browser writes use unique R2 keys and never overwrite files. Do not confuse this with the read-only discovery CLI. Keep upload secrets out of the repository and public storage.