PinMe
Create and deploy your web in one command.
# PinMe
[PinMe](https://pinme.eth.limo/) is a zero-config deployment CLI focused on one-command creation and deployment for full-stack projects.
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/)
> **PinMe Skill**
>
> Install the PinMe skill before using PinMe in agent workflows:
>
> ```bash
> npx skills add glitternetwork/pinme
> ```
## Table of Contents
- [Quick Start](#quick-start)
- [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)
- [Development and Testing](#development-and-testing)
- [Limits and Operational Notes](#limits-and-operational-notes)
- [Examples](#examples)
- [Support](#support)
## Quick Start
### Prerequisites
- Node.js `>= 16.13.0`
### Create a new Worker project
```bash
npm install -g pinme
pinme login
pinme create my-app
cd my-app
pinme save
```
What this workflow gives you:
- 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
### Update only the part you changed
```bash
pinme update-worker
pinme update-db
pinme update-web
```
### Upload a static build when you do not need the project workflow
```bash
pinme login
pinme upload dist
```
Common build directories are `dist`, `build`, `out`, and `public`.
## For AI Agents
Prefer the PinMe project workflow when the user wants a frontend plus backend plus database, or when the repo already contains `pinme.toml`.
### Project-mode protocol
Use this flow when the user wants a Worker app, database migrations, or ongoing project updates.
1. Check Node.js:
```bash
node --version
```
2. Ensure the CLI is available:
```bash
npm install -g pinme
```
3. Authenticate:
```bash
pinme login
```
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
```
2. Find the built output directory in this order:
- `dist/`
- `build/`
- `out/`
- `public/`
3. Verify the directory exists and contains built assets such as `index.html`.
4. Upload it:
```bash
pinme upload
```
### Guardrails
- 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
Install from npm:
```bash
npm install -g pinme
```
Verify installation:
```bash
pinme --version
```
## PinMe Project Workflow
### What `create` sets up
`pinme create ` does more than scaffold files. The command:
- 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
```
If the target directory already exists, the CLI asks before overwriting it unless `--force` is used.
### Deploy the whole project
Run this from the project root that contains `pinme.toml`:
```bash
pinme save
pinme save --domain my-site
pinme save --domain example.com
```
`save` performs the full deploy path:
- 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
### 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
pinme delete my-app
pinme delete my-app --force
```
This deletes the platform-side Worker, domain binding, and D1 database. Local files remain unchanged.
## Authentication and Account Commands
### Login and AppKey
```bash
pinme login
pinme login --env test
pinme set-appkey
pinme set-appkey
pinme show-appkey
pinme appkey
pinme logout
```
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 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 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 |
## Development and Testing
PinMe uses Vitest for unit/integration tests, real `dist/index.js` CLI smoke tests, npm package checks, and Stryker for slower mutation testing.
```bash
npm run test # Unit and integration tests
npm run test:coverage # Coverage gate for core modules
npm run test:cli # Real CLI black-box tests
npm run test:pack # npm pack/package-shape checks
npm run verify # Full pull-request gate
npm run test:mutation # Slow mutation tests for manual/nightly runs
```
Tests must not call live PinMe/IPFS/CAR services. Use `nock`, local loopback servers, fixtures, and temporary HOME directories for API and CLI scenarios.
For the full testing policy, layout, and mutation-testing guidance, see
[TESTING.md](TESTING.md).
## Limits and Operational Notes
- 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
This repo includes example projects and docs:
- [example/docs](./example/docs)
- [example/pinme-blog](./example/pinme-blog)
- [example/supabase](./example/supabase)
## Support
- Website: [https://pinme.eth.limo/](https://pinme.eth.limo/)
- GitHub: [https://github.com/glitternetwork/pinme](https://github.com/glitternetwork/pinme)