> ## Documentation Index
> Fetch the complete documentation index at: https://collabase.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Collabase documentation. Interface labels are quoted in English, as they appear in the product.
> Features marked Enterprise need the Collabase Enterprise Edition licence.

# Get started with a plug

> Create your first plug with the command line tool, add an action, build it, upload it to an instance and run it in a flow.

This page builds a plug with one action and runs it in a flow. You need Node.js 24 and an instance where you are a system administrator.

## Create the plug

```bash theme={"dark"}
collabase-plug init hello-plug --name hello-plug
cd hello-plug
```

The command creates a folder with `package.json`, `src/index.ts`, a short `README.md` and a `.gitignore`. The folder must be empty. The package name may use lower case letters, digits, dots, dashes and underscores, and it must not equal the name of a plug in the catalog or of a plug that comes with Collabase.

## The generated code

`src/index.ts` holds one action:

```ts theme={"dark"}
import { createAction, createPiece, PieceAuth, Property } from "@collabase/plug-framework";

const greet = createAction({
  name: "greet",
  displayName: "Greet",
  description: "Returns a greeting for a name.",
  props: { name: Property.ShortText({ displayName: "Name", required: true }) },
  run: async (context) => ({ greeting: `Hello ${context.propsValue.name}` }),
});

export const plug = createPiece({
  displayName: "Hello plug",
  description: "A Collabase plug.",
  logoUrl: "https://example.com/logo.svg",
  auth: PieceAuth.None(),
  minimumSupportedRelease: "0.0.1",
  authors: [],
  actions: [greet],
  triggers: [],
});
```

> [!NOTE]
>
> The function names `createPiece` and `PieceAuth` are the names of the framework. In the product, and in everything a person reads, the thing you build is a plug.

## Build

```bash theme={"dark"}
collabase-plug build
```

The command bundles `src/index.ts` and everything it imports into one file, lists the licences of what went in, and packs the result into `dist/`. A dependency with a licence that Collabase may not redistribute stops the build. See [Publish and versions](https://collabase.ch/docs/developer/plugs/publish.md).

## Upload

**1. Get an API token**

A system administrator creates an API token with the write level for **Automation** under **Profile, Security**. The token acts as that person.

**2. Upload the package**

```bash theme={"dark"}
export COLLABASE_API_TOKEN=cb_...
collabase-plug publish dist/hello-plug-0.1.0.tgz --url https://your-instance
```

The tool prints the name, the version and the checksum of the package.

## Use it

Open a flow, select **Add step** and search for **Greet**. The plug is listed with the origin **Own**. Enter a name and run **Test step**. The result shows `{ "greeting": "Hello ..." }`, and the data picker offers `greeting` to the steps after it.

## Next steps

> **[Plug definition](https://collabase.ch/docs/developer/plugs/definition.md)**
>
> All fields of a plug.

> **[Properties](https://collabase.ch/docs/developer/plugs/properties.md)**
>
> Inputs and how they look.

> **[Triggers](https://collabase.ch/docs/developer/plugs/triggers.md)**
>
> Start flows from your system.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.