mirror of
https://github.com/glitternetwork/pinme.git
synced 2026-09-01 15:33:43 +08:00
docs: update readme
This commit is contained in:
junchi.zhang
@@ -6,26 +6,27 @@
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Deploy your frontend in one command.
|
||||
Create and deploy your web in one command.
|
||||
</p>
|
||||
|
||||
# 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 <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 <name>`
|
||||
- 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 <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 <folder>
|
||||
```
|
||||
|
||||
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 <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 <name>` 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 `<cid>.car` into the output directory.
|
||||
|
||||
```bash
|
||||
pinme export <CID>
|
||||
pinme export <CID> --output ./exports
|
||||
```
|
||||
|
||||
### Remove uploaded content
|
||||
|
||||
`rm` accepts several input formats, including direct CID, subname, and supported URL forms.
|
||||
|
||||
```bash
|
||||
pinme rm
|
||||
pinme rm <CID>
|
||||
pinme rm <subname>
|
||||
pinme rm https://<subname>.<root-domain>
|
||||
```
|
||||
|
||||
## 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 <cid>
|
||||
pinme export <cid> --output ./exports
|
||||
```
|
||||
|
||||
### Remove uploaded content
|
||||
|
||||
```bash
|
||||
pinme rm
|
||||
pinme rm <value>
|
||||
```
|
||||
|
||||
## Command Reference
|
||||
|
||||
| Command | What it does |
|
||||
| --- | --- |
|
||||
| `pinme upload [path]` | Upload a file or directory to IPFS |
|
||||
| `pinme bind <path> --domain <name>` | Upload and bind a domain |
|
||||
| `pinme import [path]` | Import a CAR file |
|
||||
| `pinme export <cid> [--output <dir>]` | 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 <name>]` | 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 <name>]` | 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 <name>` | Upload and bind a domain |
|
||||
| `pinme import [path]` | Import a CAR file |
|
||||
| `pinme export <cid> [--output <dir>]` | 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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user