v2.0.11

pinme

glitternetwork@glitternetwork⭐ 3.8k stars· last commit 4mo ago· 5 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

6.7/10
Verified
Oct 11, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 3.8k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
6.7/10
📍

Not yet listed on ClawHub or SkillsMP

// README

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

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
  1. Ensure the CLI is available:
npm install -g pinme
  1. Authenticate:
pinme login
  1. 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
  1. If the repo contains pinme.toml, run project commands from that directory.

  2. 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>
  1. Find the built output directory in this order:
  • dist/
  • build/
  • out/
  • public/
  1. Verify the directory exists and contains built assets such as index.html.

  2. 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

CommandWhat 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-workerBuild and upload Worker code only
pinme update-dbUpload SQL migrations from db/ only
pinme update-webB

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/pinme/SKILL.md15 KBe7c47337ed47upstream ↗
    ---
    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
    ```
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/glitternetwork-pinme-skills-pinme.md

// REPO STATS

3.8k stars
5 open issues
Last commit: 4mo ago