PinMe

PinMe 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/

PinMe Skill

Install the PinMe skill before using PinMe in agent workflows:

npx skills add glitternetwork/pinme

Table of Contents

• Quick Start
• For AI Agents
• Installation
• PinMe Project Workflow
• Authentication and Account Commands
• Static Uploads and IPFS Utilities
• Command Reference
• Development and Testing
• Limits and Operational Notes
• Examples
• Support

Quick Start

Prerequisites

• Node.js >= 16.13.0

Create a new Worker project

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

pinme update-worker
pinme update-db
pinme update-web

Upload a static build when you do not need the project workflow

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:

node --version

2. Ensure the CLI is available:

npm install -g pinme

3. Authenticate:

pinme login

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:

pinme login

Or for automation:

pinme set-appkey <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:

pinme upload <folder>

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:

npm install -g pinme

Verify installation:

pinme --version

PinMe Project Workflow

What create sets up

pinme create <name> 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

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:

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:

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

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

pinme login
pinme login --env test

pinme set-appkey
pinme set-appkey <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

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

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

pinme bind ./dist --domain my-site
pinme bind ./dist --domain example.com

bind requires wallet balance.

Import or export CAR files

pinme import
pinme import ./site.car
pinme import ./site.car --domain my-site

pinme export <cid>
pinme export <cid> --output ./exports

Remove uploaded content

pinme rm
pinme rm <value>

Command Reference

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

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.

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.

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/pinme-blog
• example/supabase

Support

• Website: https://pinme.eth.limo/
• GitHub: https://github.com/glitternetwork/pinme