Syncing Tools

The Pillar CLI scans your codebase for usePillarTool, injectPillarTool, and defineTool calls, then syncs them to Pillar's backend. This enables the AI to discover and suggest tools to users.

The scanner uses AST parsing — no barrel file needed. See Setting Up Tools for how to define tools.

Prerequisites

Before syncing, you need:

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

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

Quick Start

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

# Scan and sync your actions
npx pillar-cli sync --scan ./src

Watch mode re-syncs automatically when you save a file:

npx pillar-cli sync --scan ./src --watch

Compare local tools against what's deployed:

npx pillar-cli sync status --scan ./src

See the CLI Reference for all sync options.

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-cli sync --scan ./src --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-cli sync --scan ./src

      - 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-cli sync --scan ./src
  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-cli sync --scan ./src

# Deploy your app
npm run deploy

How Sync Works

1. Scan — The CLI uses TypeScript's compiler API to find usePillarTool, injectPillarTool, and defineTool calls
2. Extract — Tool metadata (name, description, type, inputSchema, etc.) is extracted from the AST
3. Build Manifest — Creates a versioned manifest with platform info
4. Upload — Sends the manifest to Pillar's API
5. Process — Backend processes tools asynchronously (creates, updates, deletes)
6. Complete — CLI polls for completion and reports results

What Gets Synced

The scanner extracts these fields from your tool definitions:

• name — Tool identifier
• description — Used for AI matching
• type — Tool type (navigate, trigger_tool, query, etc.)
• inputSchema — For data extraction from user queries
• examples — Example phrases that trigger the tool
• autoRun — Whether to auto-execute without confirmation
• autoComplete — Whether the tool completes immediately

The execute function stays in your code — only metadata is synced.

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-cli sync --scan ./src

# 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 tools as part of your deployment pipeline to keep tools 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-cli sync --scan ./src

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

Use Environment-Specific Slugs

For staging/production environments, use different project slugs:

# Staging environment
PILLAR_SLUG=myapp-staging PILLAR_SECRET=$STAGING_SECRET \
  npx pillar-cli sync --scan ./src

# Production environment
PILLAR_SLUG=myapp-production PILLAR_SECRET=$PROD_SECRET \
  npx pillar-cli sync --scan ./src

Organize Tools by Feature

Group related tools in dedicated files for better organization:

src/
  hooks/               # React / Vue composables
    usePillarTools.ts
    useNavigationTools.ts
    useAdminTools.ts
  tools/               # Angular components or Vanilla JS modules
    pillar-tools.component.ts
    navigation-tools.component.ts
    admin-tools.component.ts

Migrating from pillar-sync

If you're using the older npx pillar-sync command from @pillar-ai/sdk, replace it with:

npx pillar-cli sync --scan ./src

The old command continues to work but won't receive new features. The CLI adds watch mode, status comparison, force sync, and config file support.

Next Steps

• Learn how to define tools with usePillarTool / injectPillarTool
• Set up context to enable tool filtering
• See the full CLI Reference for all commands
• View sync history in the Pillar admin dashboard