@piezas/cli

Set up Piezas in your project with one command. Installs the SDK and configures your AI coding agent (Claude Code, Cursor, Codex, Windsurf) to use Piezas as your backend.

Quick Start

npx @piezas/cli init

Or create and initialize a new folder:

npx @piezas/cli init my-app

Choose a deployment mode when you already know it:

npx @piezas/cli init --mode next-bff
npx @piezas/cli init --mode static

For server-capable apps, add an SDK-backed MCP route for agent tool access:

npx @piezas/cli init --mode next-bff --mcp

Add recipe guidance for common product shapes:

npx @piezas/cli init --recipe booking-site
npx @piezas/cli init --recipe crm-project-finance --recipe client-services-os

This will:

• Install @piezas/sdk
• Create package.json when one does not exist
• Create piezas.manifest.json as the app/Piezas ownership and deployment-mode source of truth
• Add recipe ownership and setup-order guidance when --recipe is provided
• Optionally scaffold app/api/piezas/mcp/route.ts when --mcp is used with a server-capable mode
• Add Piezas instructions to CLAUDE.md, .cursor/rules/piezas.mdc, .cursorrules, AGENTS.md, and .windsurfrules
• Create a .claude/commands/piezas.md slash command for Claude Code

The generated instructions are an operating manual for AI coding agents. They cover the Piezas/app ownership boundary, static vs server-runtime deployment mode, server-side API key handling, SDK usage, live OpenAPI specs, integration OAuth rules, app-scoped connector configuration, public sessions, durable access logs, durable/sync jobs, document extraction, e-signature state, accounting posting helpers, search/import/export, reconciliation helpers, thin server adapters, SDK-backed MCP routes, and common CRM, public intake, booking, finance, and project-tracker patterns.

Guardrail Scan

After an AI coding agent generates or edits the app, run:

npx @piezas/cli doctor

doctor checks for architecture mistakes that sparse prompts often miss:

• PIEZAS_API_KEY exposed to browser/client code
• static deployments that accidentally contain server routes or server actions
• admin tokens/passwords passed through URL query params
• public booking flows that trust hidden time fields without server-side slot revalidation
• local database dependencies that may duplicate Piezas-owned business records
• OAuth token storage in app code
• dynamic route params that appear unused
• hardcoded integration action IDs without connector action discovery
• coverage configs that exclude app/API/server-action code

Use strict mode in CI when you want warnings to fail:

npx @piezas/cli doctor --strict

Print machine-readable output:

npx @piezas/cli doctor --json

What is Piezas?

Piezas by Softmax Data is a suite of backend services so you don't have to build your own. It includes:

• Entity Records — Store any business data (contacts, products, cases)
• Pipeline Engine — Kanban boards and stage workflows
• Task Engine — Task management with priorities and due dates
• Notifications — Email and in-app notifications
• Calendar — Event scheduling
• Messaging — Sequences and campaigns
• Workflow — Automation and triggers
• Durable Jobs — Deferred work, retries, stale-lock recovery, reminders, imports, and sync state
• Forms — Form builder and submissions
• Documents — File storage and management
• Document Workflows — Extraction jobs and signature request state
• Reporting — Analytics and dashboards
• Pricing — Product and pricing management
• Discussion — Threaded conversations
• Knowledge Base — Document ingestion, semantic search, and AI Q&A
• Integrations — OAuth connections, scoped grants, and provider actions
• Connector Pack — Google Calendar, Gmail, Google Drive, Zoom, HubSpot, DocuSign, QuickBooks, and AWS Textract-compatible proxy actions
• Admin/access — Tenant users, invite-only signup, app registry, public sessions, durable access logs, and audit events
• MCP-ready SDK surface — Server apps can expose Piezas entity, pipeline, and task tools to approved agents through piezasMcp

App-Scoped Integrations

For products with multiple generated apps, domains, OAuth callback URLs, or provider permission sets, create one Piezas tenant app per app/use case. The tenant app stores allowed origins, redirect URIs, auth policy metadata, and connector/purpose policy. Integrations can then store provider client credentials with appId and purpose, and OAuth calls pass the same appId/purpose.

That means a booking app that needs Google Calendar and Zoom can stay separate from an internal app that only needs Google identity or Gmail-backed sending. Generated apps should store only the Piezas tenant app slug/id, connection IDs, grant IDs, and business record references.

MCP Route

@piezas/sdk includes piezasMcp, so there is no separate public MCP package to install. For Next.js/server-runtime apps:

npx @piezas/cli init --mode next-bff --mcp

This creates app/api/piezas/mcp/route.ts, wired to piezasMcp from @piezas/sdk. The generated route rejects anonymous requests until the app supplies auth plus tenant/user context. Replace the placeholder guard with your real session check before exposing it to users or agents. Static deployments should not host this route; use a separate server adapter if agent tool access is needed.

Next Steps

1. Get an API key at app.piezas.ai
2. Add PIEZAS_API_KEY=sk_live_xxx to your server-side environment
3. Tell your AI agent what to build
4. Run npx @piezas/cli doctor before deployment

SDK Usage

import { Piezas } from '@piezas/sdk';

const piezas = new Piezas({
  apiKey: process.env.PIEZAS_API_KEY,
  entitiesUrl: 'https://api.piezas.ai/entities',
  pipelineUrl: 'https://api.piezas.ai/pipeline',
  tasksUrl: 'https://api.piezas.ai/tasks',
  notificationsUrl: 'https://api.piezas.ai/notify',
  integrationsUrl: 'https://api.piezas.ai/integrations',
  calendarUrl: 'https://api.piezas.ai/calendar',
  workflowUrl: 'https://api.piezas.ai/workflow',
  messagingUrl: 'https://api.piezas.ai/messaging',
  formsUrl: 'https://api.piezas.ai/forms',
  documentsUrl: 'https://api.piezas.ai/documents',
  reportingUrl: 'https://api.piezas.ai/reporting',
  pricingUrl: 'https://api.piezas.ai/pricing',
  discussionUrl: 'https://api.piezas.ai/discussion',
  knowledgeBaseUrl: 'https://api.piezas.ai/knowledge-base',
  adminUrl: 'https://api.piezas.ai/admin',
});

// Define entity types (idempotent — safe to re-run)
await piezas.defineEntities({
  contact: {
    fields: {
      email: { type: 'email', required: true },
      status: { type: 'select', options: ['active', 'lead'] },
    },
  },
});

// CRUD
const record = await piezas.contacts.create({ title: 'Jane', data: { email: '[email protected]' } });
const list = await piezas.contacts.list({ limit: 50 });
const search = await piezas.contacts.search({ q: 'jane' });
const slots = await piezas.calendar.getAvailableSlots({
  calendarId: 'calendar-id',
  dateFrom: '2026-05-25T00:00:00Z',
  dateTo: '2026-05-26T00:00:00Z',
});
await piezas.workflow.enqueueJob({ type: 'followup.reminder', payload: { recordId: record.id } });
await piezas.workflow.enqueueSyncJob({ connector: 'gmail', resource: 'messages', direction: 'pull' });
await piezas.documents.createExtractionJob({
  documentId: 'document-id',
  provider: 'aws_textract',
  requestedFields: ['invoice_number', 'total'],
});
await piezas.documents.createSignatureRequest({
  title: 'MSA',
  documentId: 'document-id',
  provider: 'docusign',
  signers: [{ name: 'Jane Client', email: '[email protected]' }],
});
await piezas.admin.createTenantApp('tenant-id', {
  slug: 'booking-portal',
  name: 'Booking portal',
  allowedOrigins: ['https://book.example.com'],
  allowedRedirectUris: ['https://book.example.com/integrations/connected'],
  integrationPolicy: {
    connectors: {
      google_calendar: { purposes: ['calendar_availability'] },
      zoom: { purposes: ['meeting_links'] },
    },
  },
});
const authUrl = await piezas.integrations.getAuthorizationUrl('google_calendar', {
  appId: 'booking-portal',
  purpose: 'calendar_availability',
  userId: 'app-user-1',
  returnUrl: 'https://book.example.com/integrations/connected',
});

See the full SDK documentation for more.

License

MIT