Skip to content
Pinix

Build Your First Clip

Clips are written in TypeScript. Use the @pinixai/core SDK to define commands, and the pinix daemon runs them.

Prerequisites

Section titled “Prerequisites”

Create a Clip

Section titled “Create a Clip”

  1. Initialize the project

    Terminal window
    mkdir my-clip && cd my-clip
    bun init -y
    bun add @pinixai/core

  2. Create clip.json

    {
      "name": "@yourscope/my-clip",
      "version": "0.1.0",
      "description": "我的第一个 Clip",
      "main": "src/index.ts"
    }

  3. Write the Clip

    Create src/index.ts:

    import { Clip } from "@pinixai/core";
    

    const clip = new Clip({
      name: "@yourscope/my-clip",
      description: "我的第一个 Clip",
    });
    

    clip.command("hello", {
      description: "Say hello",
      input: {
        name: { type: "string", description: "Name to greet", required: true },
      },
      handler: async ({ input }) => {
        return { message: `Hello, ${input.name}!` };
      },
    });
    

    clip.run();

  4. Install and test locally

    Terminal window
    pinix hub add local/my-clip --path .
    pinix invoke my-clip hello --name "World"
    # → { "message": "Hello, World!" }

  5. Iterate

    After you modify src/index.ts, the daemon automatically restarts the Clip process. Invoke it again to test the change.

Project Structure

Section titled “Project Structure”
my-clip/
├── clip.json          # 包描述
├── src/
│   └── index.ts       # 入口文件
├── package.json       # 依赖
└── web/               # 可选：Web UI
    └── index.html

Add More Commands

Section titled “Add More Commands”
clip.command("list", {
  description: "List all items",
  handler: async () => {
    const items = await db.getAll();
    return { items, total: items.length };
  },
});


clip.command("add", {
  description: "Add a new item",
  input: {
    title: { type: "string", required: true },
    priority: { type: "string", enum: ["low", "medium", "high"] },
  },
  handler: async ({ input }) => {
    const item = await db.create(input);
    return item;
  },
});

Invoke Other Clips

Section titled “Invoke Other Clips”

Your Clip can invoke other installed Clips through the Hub:

import { invoke } from "@pinixai/core";


clip.command("research", {
  description: "Research a topic",
  input: {
    topic: { type: "string", required: true },
  },
  handler: async ({ input }) => {
    const results = await invoke("google", "search", {
      query: input.topic,
    });
    return { results };
  },
});

View Clip Information

Section titled “View Clip Information”
Terminal window
# 查看 Clip 的完整信息（命令、参数、版本等）
pinix hub info my-clip


# 查看所有命令
pinix invoke my-clip --help


# 查看单个命令的参数
pinix invoke my-clip hello --help

Next Steps

Section titled “Next Steps”