# pinme

Adopt this skill: https://proskills.md/skills/other/glitternetwork-pinme-skills-pinme

Page: https://proskills.md/skills/other/glitternetwork-pinme-skills-pinme
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/pinme/SKILL.md
size: 15400
sha: e7c47337ed4786120582b360a76ef7362aac49cf
upstream: https://github.com/glitternetwork/pinme/blob/main/skills/pinme/SKILL.md

````text
---
name: pinme
description: Use this skill when the user mentions "pinme", or needs to upload files, store to IPFS, create/publish/deploy websites or full-stack services (including frontend pages, backend APIs, database storage, email sending, etc.), or any feature requiring backend database/server support.
---

# PinMe

Zero-config deployment tool: upload static files to IPFS, or create and deploy full-stack web projects (React+Vite + Cloudflare Worker + D1 database). Workers also support sending emails via the PinMe platform API.

## When to Use

```dot
digraph pinme_decision {
    "User Request" [shape=doublecircle];
    "Needs backend API or database?" [shape=diamond];
    "Upload Files (Path 1)" [shape=box];
    "Full-Stack Project (Path 2)" [shape=box];

    "User Request" -> "Needs backend API or database?";
    "Needs backend API or database?" -> "Upload Files (Path 1)" [label="No"];
    "Needs backend API or database?" -> "Full-Stack Project (Path 2)" [label="Yes"];
}
```

## Path 1: Upload Files / Static Sites

> Login required. Use `pinme login` or `pinme set-appkey <AppKey>` before `pinme upload` or `pinme import`.

```dot
digraph upload_flow {
    "Install/update pinme to latest" [shape=box];
    "Authenticate" [shape=box];
    "Determine build artifacts" [shape=box];
    "pinme upload <path>" [shape=box];
    "Return preview URL" [shape=doublecircle];

    "Install/update pinme to latest" -> "Authenticate";
    "Authenticate" -> "Determine build artifacts";
    "Determine build artifacts" -> "pinme upload <path>";
    "pinme upload <path>" -> "Return preview URL";
}
```

**1. Check installation and update to latest:**
```bash
LOCAL=$(pinme --version 2>/dev/null || echo "0.0.0")
LATEST=$(npm view pinme version)
[ "$LOCAL" != "$LATEST" ] && npm install -g pinme@latest || echo "pinme is up to date ($LOCAL)"
```

**2. Authenticate:**
```bash
pinme login
# or: pinme set-appkey <AppKey>
```

**3. Determine upload target** (priority order):
1. `dist/` — Vite / Vue / React
2. `build/` — Create React App
3. `out/` — Next.js static export
4. `public/` — Plain static files

**4. Upload:**
```bash
pinme upload <path>
pinme upload ./dist --domain my-site  # Optional: bind subdomain (wallet balance required)
```

**5. Return** the final URL printed by PinMe to the user. URL priority is: DNS domain > PinMe subdomain > short URL > preview URL. If it falls back to preview, return the **full URL** including all hash characters — do not truncate.

### Common Examples

```bash
pinme upload ./document.pdf          # Single file
pinme upload ./my-folder             # Folder
pinme upload dist                    # Vite/Vue build artifacts
pinme upload build                   # CRA build artifacts
pinme upload out                     # Next.js static export
pinme upload ./dist --domain my-site # Bind PinMe subdomain (wallet balance required)
pinme import ./my-archive.car        # Import CAR file
```

### Do NOT Upload
- `node_modules/`, `.env`, `.git/`, `src/`
- Only upload build artifacts, never upload source code

---

## Path 2: Full-Stack Project

> Login required. Uses React+Vite frontend + Cloudflare Worker backend + D1 SQLite database.
> When designing frontend projects, use Ant Design as the primary design reference, and prioritize following its conventions for layout, components, spacing, and interaction patterns.

```dot
digraph fullstack_flow {
    "Install/update pinme to latest" [shape=box];
    "pinme login" [shape=box];
    "pinme create <name>" [shape=box];
    "Modify template code" [shape=box];
    "pinme save" [shape=box];
    "Return preview URL" [shape=doublecircle];

    "Install/update pinme to latest" -> "pinme login";
    "pinme login" -> "pinme create <name>";
    "pinme create <name>" -> "Modify template code";
    "Modify template code" -> "pinme save";
    "pinme save" -> "Return preview URL";
}
```

### Architecture

| Layer | Tech Stack | Deploy Target |
|-------|-----------|---------------|
| Frontend | React + Vite (`frontend/`) | IPFS |
| Backend | Cloudflare Worker (`backend/src/worker.ts`) | `{name}.pinme.pro` |
| Database | D1 SQLite (`db/*.sql`) | Cloudflare D1 |
| Object storage | R2 (`env.R2`) | Cloudflare R2 |

### Capability-Specific Skills

- For Worker file uploads, downloads, images, attachments, media, or object storage, use the `pinme-r2` skill. PinMe injects the project bucket as `env.R2`; do not replace it with D1 BLOBs or Worker filesystem state.

### Core Commands

```bash
pinme login                  # Login (only needed once)
pinme create <dirName>       # Clone template and create project (auto-fills API URL)
pinme save                   # First deploy / full update (frontend + backend + database, single command)
pinme update-worker          # Update backend only (when only backend/src/worker.ts was modified)
pinme update-web             # Update frontend only (when only frontend/src/ was modified)
pinme update-db              # Run SQL migrations only (when only db/ was modified)
```

> `pinme save` deploys frontend + backend + database all at once. Only use `pinme update-*` when you're certain only one part was modified.

### Project Structure

```
{project}/
├── pinme.toml              # Root config (auto-generated, do not modify)
├── package.json            # Monorepo root (workspaces: frontend + backend)
├── backend/
│   ├── wrangler.toml       # Worker config (auto-generated, do not modify)
│   ├── package.json
│   └── src/
│       └── worker.ts       # Backend entry — primarily used for JSON APIs in this template
├── db/
│   └── 001_init.sql        # SQL table definitions
├── frontend/
│   ├── package.json
│   ├── vite.config.ts      # Dev proxy: /api → localhost:8787
│   ├── index.html
│   ├── .env                # Auto-generated: VITE_API_URL (do not modify)
│   └── src/
│       ├── main.tsx
│       ├── App.tsx
│       ├── utils/
│       │   ├── api.ts      # export const API = import.meta.env.VITE_WORKER_URL || ''
│       │   └── config.ts   # Auto-generated: public_client_config (only when auth is enabled)
│       └── pages/
│           └── Home/
│               └── index.tsx
└── .gitignore
```

### First Deployment

```bash
LOCAL=$(pinme --version 2>/dev/null || echo "0.0.0")
LATEST=$(npm view pinme version)
[ "$LOCAL" != "$LATEST" ] && npm install -g pinme@latest
pinme login
pinme create my-app
cd my-app
```

`pinme create` generates a working Hello World template (includes frontend page + backend API routes + database schema). **Modify the template** to match the user's business logic — do not write from scratch:

- Modify `backend/src/worker.ts` — replace API routes
- Modify `frontend/src/pages/` — replace page components
- Modify `db/001_init.sql` — replace table definitions

```bash
pinme save
# Single command deploys frontend + backend + database
# Outputs preview URL: https://pinme.eth.limo/#/preview/{CID}
```

**Return** the preview URL to the user. Note: return the **full URL** including all hash characters — do not truncate.

The backend Worker is deployed at `https://{name}.pinme.pro`. Frontend API requests are automatically configured to point to that address — no manual setup needed.

### Subsequent Updates

| Changes | Command | Notes |
|---------|---------|-------|
| Backend only (`backend/src/worker.ts`) | `pinme update-worker` | Faster |
| Frontend only (`frontend/src/`) | `pinme update-web` | Generates new CID |
| Database only (`db/`) | `pinme update-db` | Runs new migrations |
| Multiple changes or uncertain | `pinme save` | Safe full deployment |

> Each frontend deployment generates a new CID and preview URL. Old URLs remain accessible.

---

## Worker Code Patterns (`backend/src/worker.ts`)

In this template, the Worker backend is primarily used for JSON APIs. Prefer standard Web APIs and simple manual routing by default. Worker-compatible libraries can be added when needed, but the default template does not rely on extra frameworks. Avoid packages that depend on a full Node.js runtime, a persistent local filesystem, native binaries, or child processes.

```typescript
export interface Env {
  DB: D1Database;           // When using database
  R2: R2Bucket;             // Project object storage; injected by PinMe
  API_KEY?: string;         // When using email sending
  JWT_SECRET: string;       // When using JWT auth
  ADMIN_PASSWORD: string;   // When using password auth
}

const CORS_HEADERS = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-API-Key',
};

function json(data: unknown, status = 200): Response {
  return Response.json(data, { status, headers: CORS_HEADERS });
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { pathname } = new URL(request.url);
    const method = request.method;

    if (method === 'OPTIONS') return new Response(null, { status: 204, headers: CORS_HEADERS });

    try {
      if (pathname === '/api/items' && method === 'GET')  return handleGetItems(env);
      if (pathname === '/api/items' && method === 'POST') return handleCreateItem(request, env);
      return json({ error: 'Not found' }, 404);
    } catch {
      return json({ error: 'Internal server error' }, 500);
    }
  },
};
```

### Worker Constraints and Default Conventions

| Item | Notes |
|------|------|
| Dependency choice | Prefer standard Web APIs and simple manual routing by default. If extra dependencies are needed, prefer Worker-compatible libraries. |
| Node.js capability | Workers now support part of Node.js compatibility, but they are not a full Node.js runtime. Do not assume all Node.js built-in modules are available or behave exactly the same. |
| Filesystem | Do not treat a Worker like a server with a persistent local disk. Even if some `fs` capabilities are available, do not rely on persistence across requests. |
| Response types | This template mainly uses the Worker for JSON APIs. If there is a clear need, it can also be adapted to return HTML or other content. |
| Password storage | Never store passwords in plaintext. Use a dedicated password hashing algorithm such as bcrypt, scrypt, or Argon2. |
| SQL | Do not build SQL by string concatenation. Use parameterized queries such as `.bind()`. |

### Email API Reference (for Worker Backend)

When the backend needs email sending, use the PinMe platform API (`https://pinme.cloud/api/v4/send_email`).

**1. Configure API_KEY**

Add to the `Env` interface:

```typescript
export interface Env {
  DB: D1Database;
  API_KEY?: string;  // Required for email sending
}
```

**2. Email Handler Code**

```typescript
async function handleSendEmail(request: Request, env: Env): Promise<Response> {
  const apiKey = env.API_KEY;
  if (!apiKey) {
    return json({ error: 'API_KEY not configured' }, 500);
  }

  const body = await request.json() as {
    to?: string;
    subject?: string;
    html?: string;
  };

  if (!body.to) return json({ error: 'Email address is required' }, 400);
  if (!body.subject) return json({ error: 'Subject is required' }, 400);
  if (!body.html) return json({ error: 'HTML content is required' }, 400);

  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(body.to)) {
    return json({ error: 'Invalid email address' }, 400);
  }

  const response = await fetch('https://pinme.cloud/api/v4/send_email', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': apiKey,
    },
    body: JSON.stringify({
      to: body.to,
      subject: body.subject,
      html: body.html,
    }),
  });

  const result = await response.json();
  return json(result);
}
```

## Frontend API Utility (frontend/src/utils/api.ts)

```typescript
// Development: Vite proxies /api to localhost:8787
// Production: VITE_API_URL is auto-injected by pinme create
export const API = import.meta.env.VITE_API_URL || '';

export function getApiUrl(path: string): string {
  return API ? `${API}${path}` : path;
}
```

## D1 Database Operations

```typescript
// Query multiple rows
const { results } = await env.DB.prepare('SELECT * FROM t WHERE x = ?').bind(val).all();

// Query single row (returns null if not found)
const row = await env.DB.prepare('SELECT * FROM t WHERE id = ?').bind(id).first();

// Insert and return new row
const row = await env.DB.prepare('INSERT INTO t (a, b) VALUES (?, ?) RETURNING *').bind(a, b).first();

// Update
await env.DB.prepare('UPDATE t SET a = ? WHERE id = ?').bind(val, id).run();

// Delete (check if affected)
const { meta } = await env.DB.prepare('DELETE FROM t WHERE id = ?').bind(id).run();
if (meta.changes === 0) return json({ error: 'Not found' }, 404);
```

### SQL Migration Files

**Format:** `db/NNN_description.sql` (for example, `001_init.sql`). Files are executed in filename order.

**SQLite Type Constraints:**

| Do Not Use | Alternative |
|-----------|-------------|
| `BOOLEAN` | `INTEGER` (0 = false, 1 = true) |
| `DATETIME` / `TIMESTAMP` | `TEXT`, stored as ISO 8601 (default: `datetime('now')`) |
| `JSON` type | `TEXT`, using `JSON.stringify()` / `JSON.parse()` |
| `VARCHAR(n)` | `TEXT` |

## Template Architecture Suggestions

| Scenario | Default Suggestion |
|-----------|-------------|
| File storage (images, attachments, media) | Use the project R2 binding through `env.R2`; use the `pinme-r2` skill for secure routes and metadata patterns |
| Real-time communication | This template defaults to regular HTTP APIs. If there is no clear real-time requirement, start with polling |
| Multiple Workers | This template defaults to combining functionality into a single Worker and separating routes by prefix |
| Multiple databases | This template defaults to combining data into one D1 database and only splitting when isolation is truly needed |

## Important Notes

- `pinme.toml`, `backend/wrangler.toml`, and `frontend/.env` are generated by PinMe. Do not edit them manually by default. If extra runtime configuration is truly needed, prefer doing it through PinMe-supported mechanisms.
- Obtain the frontend API URL from the `VITE_API_URL` environment variable. Do not hardcode it.
- Passwords, tokens, and API keys must be stored in secrets. Never put them in config files.

## Common Errors

| Error | Solution |
|-------|----------|
| `command not found: pinme` | `npm install -g pinme` |
| `No such file or directory` | Verify that the path exists |
| `Permission denied` | Check file or directory permissions |
| Upload failed | Check the network connection and retry |
| Not logged in | Run `pinme login` first |

## Other Commands

```bash
pinme list / pinme ls -l 5     # View upload history
pinme list -c                  # Clear upload history
pinme rm <hash>                # Delete uploaded content
pinme bind <path> --domain <domain>  # Bind domain (VIP + AppKey required)
pinme export <CID>             # Export as CAR file
pinme set-appkey               # Set/view AppKey
pinme my-domains               # List bound domains
pinme delete <project>          # Delete project (Worker + domain + D1)
pinme logout                   # Log out
```
````

## File: README.md
upstream: https://github.com/glitternetwork/pinme/blob/main/README.md

````text
<p align="center">
  <a href="https://pinme.eth.limo/">
    <img src="https://2egc5b44.pinit.eth.limo/" height="92" alt="PinMe logo">
    <h3 align="center">PinMe</h3>
  </a>
</p>

<p align="center">
  Create and deploy your web in one command.
</p>

# 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 <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>
```

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 <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:

```bash
npm install -g pinme
```

Verify installation:

```bash
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

```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 <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 <cid>
pinme export <cid> --output ./exports
```

### Remove uploaded content

```bash
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`                                        | B
````
