Syncing Actions

The pillar-sync CLI syncs your action definitions to Pillar's backend, enabling the AI to discover and suggest actions to users. Run this command in your CI/CD pipeline after building your app.

Prerequisites

Before syncing, you need:

1. A Help Center Slug — Your unique identifier (e.g., acme-corp)
2. A Secret Token — For authenticating sync requests

Get both from the Pillar admin dashboard: Actions → Configure Sync

Quick Start

# Set your credentials
export PILLAR_SLUG="your-help-center-slug"
export PILLAR_SECRET="your-secret-token"

# Sync your actions
npx pillar-sync --actions ./lib/pillar/actions.ts

Installation

The CLI is included with the SDK:

npm install @pillar-ai/sdk
# or
pnpm add @pillar-ai/sdk
# or
yarn add @pillar-ai/sdk

Action File Structure

Create a file that exports your action definitions:

// lib/pillar/actions.ts
import type { SyncActionDefinitions } from '@pillar-ai/sdk';

export const actions = {
  open_settings: {
    description: 'Navigate to the settings page',
    type: 'navigate' as const,
    path: '/settings',
    autoRun: true,
    autoComplete: true,
  },

  invite_member: {
    description: 'Open the invite team member modal',
    examples: [
      'invite someone to my team',
      'add a new user',
      'how do I invite people?',
    ],
    type: 'trigger_action' as const,
  },

  export_data: {
    description: 'Export current data to CSV',
    type: 'trigger_action' as const,
    dataSchema: {
      type: 'object',
      properties: {
        format: {
          type: 'string',
          enum: ['csv', 'json', 'xlsx'],
          description: 'Export format',
        },
        includeArchived: {
          type: 'boolean',
          description: 'Include archived records',
        },
      },
      required: ['format'],
    },
  },

  admin_dashboard: {
    description: 'Open the admin dashboard',
    type: 'navigate' as const,
    path: '/admin',
    requiredContext: {
      userRole: 'admin',
    },
  },
} as const satisfies SyncActionDefinitions;

export default actions;

The sync command supports .ts, .tsx, .js, and .mjs files.

Environment Variables

Required

Optional

CLI Arguments

Local Development

Use the --local flag to sync against a local Pillar backend:

# Sync against local Pillar backend (localhost:8003)
PILLAR_SLUG=my-app PILLAR_SECRET=dev-secret \
  npx pillar-sync --actions ./lib/pillar/actions.ts --local

CI/CD Integration

GitHub Actions

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Sync Pillar actions
        env:
          PILLAR_SLUG: ${{ secrets.PILLAR_SLUG }}
          PILLAR_SECRET: ${{ secrets.PILLAR_SECRET }}
          GIT_SHA: ${{ github.sha }}
        run: npx pillar-sync --actions ./lib/pillar/actions.ts

      - name: Deploy
        run: npm run deploy

Store PILLAR_SLUG and PILLAR_SECRET as GitHub repository secrets.

GitLab CI

# .gitlab-ci.yml
stages:
  - build
  - sync
  - deploy

build:
  stage: build
  script:
    - npm ci
    - npm run build

sync-pillar:
  stage: sync
  script:
    - npx pillar-sync --actions ./lib/pillar/actions.ts
  variables:
    PILLAR_SLUG: $PILLAR_SLUG
    PILLAR_SECRET: $PILLAR_SECRET
    GIT_SHA: $CI_COMMIT_SHA

deploy:
  stage: deploy
  script:
    - npm run deploy

Generic CI

#!/bin/bash
set -e

# Build your app
npm ci
npm run build

# Sync actions to Pillar
export PILLAR_SLUG="${PILLAR_SLUG}"
export PILLAR_SECRET="${PILLAR_SECRET}"
export GIT_SHA="${CI_COMMIT_SHA:-$(git rev-parse HEAD)}"

npx pillar-sync --actions ./lib/pillar/actions.ts

# Deploy your app
npm run deploy

How Sync Works

1. Load Actions — The CLI reads and evaluates your actions file
2. Build Manifest — Creates a versioned manifest with platform info
3. Upload — Sends the manifest to Pillar's API
4. Process — Backend processes actions asynchronously (creates, updates, deletes)
5. Complete — CLI polls for completion and reports results

Response Statuses

Debugging

Enable debug mode to write the manifest to disk:

# Enable debug mode to write manifest to disk
PILLAR_DEBUG=1 PILLAR_SLUG=my-app PILLAR_SECRET=xxx \
  npx pillar-sync --actions ./lib/pillar/actions.ts

# Check the generated manifest
cat actions-manifest.json

This creates actions-manifest.json in your project root.

Version Tracking

Each sync creates a versioned deployment. The CLI tracks:

• Version — From PILLAR_VERSION or package.json
• Git SHA — From GIT_SHA or auto-detected from git
• Platform — From PILLAR_PLATFORM
• Timestamp — When the sync occurred

This enables rollback and audit tracking in the Pillar dashboard.

Best Practices

Sync on Deploy

Always sync actions as part of your deployment pipeline to keep actions in sync with your app:

#!/bin/bash
# deploy.sh - Run as part of your deployment

# Build the app
npm run build

# Sync actions before deploying
npx pillar-sync --actions ./lib/pillar/actions.ts

# Deploy (e.g., to Vercel, AWS, etc.)
vercel deploy --prod

Use Environment-Specific Slugs

For staging/production environments, use different help center slugs:

# Staging environment
PILLAR_SLUG=myapp-staging PILLAR_SECRET=$STAGING_SECRET \
  npx pillar-sync --actions ./lib/pillar/actions.ts

# Production environment
PILLAR_SLUG=myapp-production PILLAR_SECRET=$PROD_SECRET \
  npx pillar-sync --actions ./lib/pillar/actions.ts

Next Steps

• Learn how to define actions with full TypeScript support
• Set up context to enable action filtering
• View sync history in the Pillar admin dashboard