diff --git a/README.md b/README.md index 7db7602..a61166a 100644 --- a/README.md +++ b/README.md @@ -6,26 +6,27 @@

- Deploy your frontend in one command. + Create and deploy your web in one command.

# PinMe -[PinMe](https://pinme.eth.limo/) is a zero-config deployment CLI for static sites and PinMe full-stack projects. +[PinMe](https://pinme.eth.limo/) is a zero-config deployment CLI focused on one-command creation and deployment for full-stack projects. -Build your app, upload the output folder, and PinMe prints the best available public URL. For larger projects, PinMe can also create and deploy a template with a frontend, a Worker backend, and database migrations. +It lets you quickly set up and launch a complete project with an integrated frontend, Worker backend, and database, without tedious configuration. PinMe is built to make full-stack delivery much simpler and significantly improve development efficiency. Website: [https://pinme.eth.limo/](https://pinme.eth.limo/) ## Table of Contents - [Quick Start](#quick-start) -- [Worker and Full-Stack Projects](#worker-and-full-stack-projects) -- [Static Uploads](#static-uploads) - [For AI Agents](#for-ai-agents) - [Installation](#installation) +- [PinMe Project Workflow](#pinme-project-workflow) +- [Authentication and Account Commands](#authentication-and-account-commands) +- [Static Uploads and IPFS Utilities](#static-uploads-and-ipfs-utilities) - [Command Reference](#command-reference) -- [Limits and Notes](#limits-and-notes) +- [Limits and Operational Notes](#limits-and-operational-notes) - [Examples](#examples) - [Support](#support) @@ -35,70 +36,47 @@ Website: [https://pinme.eth.limo/](https://pinme.eth.limo/) - Node.js `>= 16.13.0` -Check your version: - -```bash -node --version -``` - -### Create and deploy a full-stack project +### Create a new Worker project ```bash +npm install -g pinme pinme login pinme create my-app cd my-app pinme save ``` -If you want the Worker-based project flow first, start with [Worker and Full-Stack Projects](#worker-and-full-stack-projects). +What this workflow gives you: -### Upload a static site +- a generated PinMe project from the official template +- platform-side Worker and database provisioning +- local project config in `pinme.toml` +- frontend and Worker deployment from one CLI -If you only want to upload a built frontend, jump to [Static Uploads](#static-uploads). - -1. Install the CLI: +### Update only the part you changed ```bash -npm install -g pinme +pinme update-worker +pinme update-db +pinme update-web ``` -2. Authenticate: +### Upload a static build when you do not need the project workflow ```bash pinme login - -# Or use an AppKey for CLI / CI usage -pinme set-appkey -``` - -3. Build your app: - -```bash -npm run build -``` - -4. Upload the build output: - -```bash pinme upload dist - -# Other common output folders -pinme upload build -pinme upload out -pinme upload public ``` -PinMe prints the final public URL after upload. If no custom domain is bound, it can fall back to a preview URL such as `https://pinme.eth.limo/#/preview/*`. +Common build directories are `dist`, `build`, `out`, and `public`. ## For AI Agents -This section is the low-ambiguity workflow for agents using PinMe to deploy static output. +Prefer the PinMe project workflow when the user wants a frontend plus backend plus database, or when the repo already contains `pinme.toml`. -### Goal +### Project-mode protocol -Upload static files with PinMe and return the final public URL printed by the CLI. - -### Required steps +Use this flow when the user wants a Worker app, database migrations, or ongoing project updates. 1. Check Node.js: @@ -106,82 +84,67 @@ Upload static files with PinMe and return the final public URL printed by the CL node --version ``` -2. Ensure PinMe is installed: +2. Ensure the CLI is available: ```bash npm install -g pinme ``` -3. Authenticate before upload: +3. Authenticate: ```bash pinme login +``` -# Or: +4. Choose the right project command: + +- create a new project: `pinme create ` +- deploy everything from a PinMe project root: `pinme save` +- update Worker only: `pinme update-worker` +- update SQL migrations only: `pinme update-db` +- update frontend only: `pinme update-web` + +5. If the repo contains `pinme.toml`, run project commands from that directory. + +6. Return the final project URL printed by the CLI for frontend deploys. For Worker-only or DB-only updates, return the relevant success result instead of fabricating a URL. + +### Static-upload fallback + +Use this only when the task is just "publish the built frontend" and there is no PinMe project workflow involved. + +1. Authenticate: + +```bash +pinme login +``` + +Or for automation: + +```bash pinme set-appkey ``` -4. Find the static output directory in this order: +2. Find the built output directory in this order: - `dist/` - `build/` - `out/` - `public/` -Validation rules: +3. Verify the directory exists and contains built assets such as `index.html`. -- the directory must exist -- it should contain `index.html` for website deployment -- it should contain built static assets rather than source files - -5. Upload the directory: +4. Upload it: ```bash pinme upload ``` -6. Return only the final public URL. +### Guardrails -URL priority: - -1. DNS domain -2. PinMe subdomain -3. short URL -4. preview URL - -### Important guardrails - -- Do not upload `node_modules`, `.git`, `.env`, or source folders such as `src/`. -- Do not upload config files like `package.json` or `tsconfig.json`. -- For SPAs, hash-based routing is safer on IPFS than history mode for deep links. -- If no suitable build directory exists, ask the user for the correct upload path. - -### Machine-readable summary - -```json -{ - "tool": "pinme", - "requirements": { - "node_version": ">=16.13.0" - }, - "install": "npm install -g pinme", - "login": "pinme login", - "set_appkey": "pinme set-appkey ", - "auth_required_for_upload": true, - "upload": "pinme upload {{directory}}", - "upload_with_domain": "pinme upload {{directory}} --domain {{domain}}", - "upload_with_dns": "pinme upload {{directory}} --domain {{domain}} --dns", - "valid_directories": ["dist", "build", "out", "public"], - "required_files": ["index.html"], - "exclude_patterns": ["node_modules", ".env", ".git", "src"], - "limits": { - "single_file_default": "100MB", - "total_directory_default": "500MB" - }, - "output": "public_url", - "url_priority": ["dns_domain", "pinme_domain", "short_url", "preview_url"] -} -``` +- Do not upload source folders such as `src/`. +- Do not upload `node_modules`, `.git`, or `.env`. +- Do not claim unsupported backend hosting outside the PinMe project template flow. +- For project commands, do not run `update-*` commands outside a PinMe project root with `pinme.toml`. ## Installation @@ -197,42 +160,69 @@ Verify installation: pinme --version ``` -## Worker and Full-Stack Projects +## PinMe Project Workflow -PinMe can create and deploy a full-stack template with: +### What `create` sets up -- frontend -- Worker backend -- SQL migrations +`pinme create ` does more than scaffold files. The command: -### Create and deploy +- requires an authenticated session +- creates the platform project resources first +- downloads the official Worker project template +- writes project metadata into `pinme.toml` +- writes backend metadata and frontend config files +- installs workspace dependencies +- builds the Worker +- uploads Worker code and SQL files +- builds the frontend and attempts an initial frontend upload + +After creation, the CLI prints the project management URL and suggests `pinme save` for the next deploy. + +### Create a project ```bash pinme login pinme create my-app -cd my-app -pinme save ``` -`create` downloads the PinMe template and initializes the platform project. `save` builds and deploys the project from the current PinMe project root. +If the target directory already exists, the CLI asks before overwriting it unless `--force` is used. -### Targeted updates +### Deploy the whole project -Use these when only one layer changed: +Run this from the project root that contains `pinme.toml`: ```bash -pinme update-web -pinme update-worker -pinme update-db +pinme save +pinme save --domain my-site +pinme save --domain example.com ``` -Notes: +`save` performs the full deploy path: -- run these commands from a PinMe project root that contains `pinme.toml` -- `update-db` uploads SQL files from `db/` -- the total SQL payload for `update-db` is limited to `10MB` per run +- installs project dependencies +- builds the Worker with `npm run build:worker` +- uploads Worker code and SQL files from `db/` +- builds the frontend with `npm run build:frontend` +- uploads `frontend/dist` +- optionally binds a domain after the frontend deploy -### Delete a platform project +### Update only one layer + +Use targeted commands when only one part changed: + +```bash +pinme update-worker +pinme update-db +pinme update-web +``` + +What each command expects: + +- `update-worker`: builds and uploads Worker code from the current PinMe project +- `update-db`: uploads `.sql` files from `db/` +- `update-web`: builds and uploads `frontend/dist` + +### Delete a project ```bash pinme delete @@ -240,72 +230,11 @@ pinme delete my-app pinme delete my-app --force ``` -This deletes the project on the platform. Local files remain unchanged. +This deletes the platform-side Worker, domain binding, and D1 database. Local files remain unchanged. -## Static Uploads +## Authentication and Account Commands -### Upload files or folders - -`upload` requires authentication. - -```bash -pinme login -pinme upload -pinme upload ./dist -``` - -### Bind a domain - -Domain binding requires wallet balance. - -```bash -pinme upload ./dist --domain my-site -pinme upload ./dist --domain example.com -pinme upload ./dist --domain my-site --dns - -# Or use the dedicated command -pinme bind ./dist --domain my-site -``` - -Domain handling: - -- domains with a dot are treated as DNS domains -- domains without a dot are treated as PinMe subdomains -- `--dns` forces DNS mode - -### Import a CAR file - -`import` also requires authentication. - -```bash -pinme import -pinme import ./site.car -pinme import ./site.car --domain my-site -``` - -### Export a CAR file - -`export` takes a CID and writes `.car` into the output directory. - -```bash -pinme export -pinme export --output ./exports -``` - -### Remove uploaded content - -`rm` accepts several input formats, including direct CID, subname, and supported URL forms. - -```bash -pinme rm -pinme rm -pinme rm -pinme rm https://. -``` - -## Usage - -### Authentication +### Login and AppKey ```bash pinme login @@ -320,53 +249,106 @@ pinme appkey pinme logout ``` -### History and account info +Notes: + +- `pinme login` is the recommended path for project commands. +- `set-appkey` is the alternative authentication method for CLI and automation usage. + +### Domains, wallet, and history ```bash -pinme list -pinme ls -pinme list -l 5 -pinme list -c - pinme my-domains pinme domain pinme wallet pinme wallet-balance pinme balance + +pinme list +pinme ls +pinme list -l 5 +pinme list -c +``` + +## Static Uploads and IPFS Utilities + +These commands are useful when you already have artifacts and do not need the full Worker project flow. + +### Upload a directory or file + +```bash +pinme upload +pinme upload ./dist +pinme upload ./dist --domain my-site +pinme upload ./dist --domain example.com +pinme upload ./dist --domain my-site --dns +``` + +Domain handling: + +- domains containing a dot are treated as DNS domains +- domains without a dot are treated as PinMe subdomains +- `--dns` forces DNS mode + +### Bind while uploading + +```bash +pinme bind ./dist --domain my-site +pinme bind ./dist --domain example.com +``` + +`bind` requires wallet balance. + +### Import or export CAR files + +```bash +pinme import +pinme import ./site.car +pinme import ./site.car --domain my-site + +pinme export +pinme export --output ./exports +``` + +### Remove uploaded content + +```bash +pinme rm +pinme rm ``` ## Command Reference -| Command | What it does | -| --- | --- | -| `pinme upload [path]` | Upload a file or directory to IPFS | -| `pinme bind --domain ` | Upload and bind a domain | -| `pinme import [path]` | Import a CAR file | -| `pinme export [--output ]` | Export a CID as a CAR file into a directory | -| `pinme rm [value]` | Remove uploaded content by CID, subname, or supported URL form | -| `pinme login [--env dev|test|prod]` | Browser-based login | -| `pinme set-appkey [AppKey]` | Set authentication with an AppKey | -| `pinme show-appkey` / `pinme appkey` | Show masked AppKey info | -| `pinme my-domains` / `pinme domain` | List bound domains | -| `pinme wallet` / `pinme wallet-balance` / `pinme balance` | Show wallet balance | -| `pinme create [name]` | Create a new PinMe full-stack project | -| `pinme save [--domain ]` | Build and deploy a PinMe full-stack project | -| `pinme update-web` | Deploy frontend only | -| `pinme update-worker` | Deploy Worker only | -| `pinme update-db` | Run SQL migrations only | -| `pinme delete [name] [--force]` | Delete a platform project | -| `pinme list` / `pinme ls` | Show upload history | -| `pinme help` | Show CLI help | +| Command | What it does | +| --------------------------------------------------------- | ------------------------------------------------------------ | +| `pinme create [name]` | Create a new PinMe Worker project from the official template | +| `pinme save [--domain ]` | Deploy the current PinMe project: Worker, SQL, and frontend | +| `pinme update-worker` | Build and upload Worker code only | +| `pinme update-db` | Upload SQL migrations from `db/` only | +| `pinme update-web` | Build and upload the frontend only | +| `pinme delete [name] [--force]` | Delete a platform project | +| `pinme upload [path]` | Upload a file or directory to IPFS | +| `pinme bind [path] --domain ` | Upload and bind a domain | +| `pinme import [path]` | Import a CAR file | +| `pinme export [--output ]` | Export IPFS content as a CAR file | +| `pinme rm [value]` | Remove uploaded content | +| `pinme login [--env test\|prod]` | Login via browser | +| `pinme set-appkey [AppKey]` | Set authentication with an AppKey | +| `pinme show-appkey` / `pinme appkey` | Show masked AppKey info | +| `pinme my-domains` / `pinme domain` | List domains owned by the current account | +| `pinme wallet` / `pinme wallet-balance` / `pinme balance` | Show current wallet balance | +| `pinme list` / `pinme ls` | Show upload history | +| `pinme help` | Show CLI help | -## Limits and Notes +## Limits and Operational Notes -- Default upload file size limit: `100MB` -- Default upload directory size limit: `500MB` -- These defaults come from the CLI and can be overridden with environment variables -- Domain binding requires wallet balance -- `upload` and `import` require authentication -- PinMe subdomain root is resolved dynamically by the platform, so the CLI prints the exact final URL +- Default single-file upload limit: `100MB` +- Default directory upload limit: `500MB` +- These upload defaults come from the CLI and can be overridden with environment variables +- `update-db` enforces a total SQL payload limit of `10MB` per run +- `upload`, `import`, and project commands require authentication +- domain binding requires wallet balance +- `save`, `update-worker`, `update-db`, and `update-web` expect to run from a PinMe project root with `pinme.toml` ## Examples