Pikku CLI

The Pikku CLI scans your codebase, analyzes your functions and wirings, and generates type-safe clients, entry points, schemas, and optimized bundles. It also scaffolds new code, manages function versioning, and deploys your project to cloud providers.

Quick Start

npx pikku

This reads your pikku.config.json, scans the configured source directories, and generates everything into your .pikku/ output directory — types, schemas, wiring metadata, RPC maps, and more.

Commands

pikku / pikku all

Generate all Pikku files (types, schemas, wirings, etc.). This is the default command.

npx pikku
npx pikku all

Filtering flags (apply to all):

Flag	Description
--tags, -t	Filter functions by tags (comma-separated)
--types	Filter by wiring types (comma-separated): http, channel, queue, scheduler, rpc, mcp, cli, workflow
--directories, -d	Filter functions by directories (comma-separated)
--http-methods	Filter HTTP routes by methods (comma-separated)
--http-routes	Filter HTTP routes by route patterns (comma-separated)
--names, -n	Filter functions by name patterns (supports wildcards)

# Public HTTP API only
npx pikku --tags public --types http

# Background workers only
npx pikku --types queue,scheduler

# Specific routes
npx pikku --http-routes /api/admin

pikku bootstrap

Generate only type files (setup phase). Useful when you need types before a full generation pass — for example, on first clone or in CI before the main build.

npx pikku bootstrap

pikku watch

Watch for file changes and regenerate automatically. Your generated types stay in sync as you write code.

npx pikku watch
npx pikku watch --hmr   # Enable hot module reload for registered functions

pikku console

Start the Pikku Console — a visual UI for exploring your functions, wirings, workflows, agents, and configuration with live file watching.

npx pikku console
npx pikku console --port 8080   # Custom port (default: 51442)
npx pikku console --open         # Open in browser automatically
npx pikku console --hmr          # Enable hot module reload

See The Console for full documentation.

pikku schemas

Generate JSON schemas for function input/output types.

npx pikku schemas

Client Generation

Generate type-safe clients for specific protocols:

npx pikku fetch       # HTTP fetch client
npx pikku websocket   # WebSocket client
npx pikku rpc         # RPC client wrappers
npx pikku queue-service  # Queue service wrapper
npx pikku openapi     # OpenAPI specification from HTTP routes
npx pikku nextjs      # Next.js backend and HTTP wrappers

These require the corresponding file paths to be set in pikku.config.json (e.g., fetchFile, websocketFile).

pikku new

Scaffold new files from templates:

# Functions
npx pikku new function myFunc                    # Default: sessionless
npx pikku new function myFunc --type func        # Requires session
npx pikku new function myFunc --type void        # No return value

# Wirings
npx pikku new wiring myRoute                     # Default: http
npx pikku new wiring myRoute --type channel      # WebSocket channel
npx pikku new wiring myRoute --type scheduler    # Cron job
npx pikku new wiring myRoute --type queue        # Queue worker
npx pikku new wiring myRoute --type mcp          # MCP resource
npx pikku new wiring myRoute --type cli          # CLI command
npx pikku new wiring myRoute --type trigger      # Event trigger

# Middleware & Permissions
npx pikku new middleware myAuth                   # Default: simple
npx pikku new middleware myAuth --type factory    # Factory pattern
npx pikku new permission myGuard                  # Default: simple
npx pikku new permission myGuard --type factory   # Factory pattern

# Addons
npx pikku new addon my-integration
npx pikku new addon my-integration --secret       # Include secret schema
npx pikku new addon my-integration --variable     # Include variable definition
npx pikku new addon my-integration --oauth        # OAuth2 credential + API service
npx pikku new addon my-integration --credential apikey  # Per-user credential
npx pikku new addon my-integration --openapi ./spec.yaml  # Generate from OpenAPI spec
npx pikku new addon my-integration --mcp          # Expose functions as MCP tools
npx pikku new addon my-integration --camelCase    # Convert snake_case to camelCase in schemas

pikku enable

Enable Pikku features by updating the scaffold section in pikku.config.json:

npx pikku enable rpc          # Enable public RPC endpoint
npx pikku enable console      # Enable console functions
npx pikku enable agent        # Enable public agent endpoints
npx pikku enable workflow     # Enable workflow workers

# Disable auth requirement
npx pikku enable rpc --no-auth

pikku versions

Manage function contract versioning. Tracks input/output schema hashes to detect breaking changes.

npx pikku versions init      # Initialize version manifest (versions.pikku.json)
npx pikku versions init --force  # Overwrite existing manifest
npx pikku versions check     # Validate contracts against manifest
npx pikku versions update    # Update manifest with current hashes

pikku deploy

Deploy your Pikku project to cloud infrastructure.

npx pikku deploy plan                    # Show what will be created/updated/deleted
npx pikku deploy plan --provider aws     # Use AWS provider (default: cloudflare)
npx pikku deploy apply                   # Execute the deployment
npx pikku deploy apply --from-plan       # Deploy from existing plan output
npx pikku deploy info                    # Show current deployment state

Providers: cloudflare (default), aws

The deploy pipeline builds your project, tree-shakes per deployment unit, and provisions infrastructure (workers, queues, cron triggers, secrets) through the provider API.

pikku info

Inspect your Pikku project:

npx pikku info                           # List all functions (default)
npx pikku info functions                 # List all registered functions
npx pikku info functions --verbose       # Include file paths, services, etc.
npx pikku info tags                      # List all tags with associated functions
npx pikku info middleware                # List all middleware definitions
npx pikku info permissions               # List all permission definitions
npx pikku info --limit 100              # Show more rows (default: 50)

Global Options

These flags work with any command:

Flag	Description
--config, -c	Path to pikku.config.json file
--log-level, -l	Set log level (default: info)
--out-dir, -o	Override output directory
--user-session-type	Specify which UserSession type to use (when multiple exist)
--singleton-services-factory-type	Specify which singleton services factory to use
--wire-services-factory-type	Specify which wire services factory to use
--state-output	Save inspector state to JSON file for reuse
--state-input	Load inspector state from JSON (skips inspection)

Common Workflows

Development

# Watch mode with hot reload
npx pikku watch --hmr

# Or use the console for visual exploration
npx pikku console

CI / Production Build

npx pikku

Deploy

# Preview what will change
npx pikku deploy plan

# Ship it
npx pikku deploy apply

Filter by Environment

# Public API only
npx pikku --tags public --types http

# Admin service
npx pikku --tags admin --http-routes /admin

# Background workers
npx pikku --types queue,scheduler

Monorepo with Shared SDK

{
  "clientFiles": {
    "fetchFile": "packages/sdk/pikku-fetch.gen.ts",
    "websocketFile": "packages/sdk/pikku-websocket.gen.ts"
  },
  "packageMappings": {
    "packages/sdk": "@my-app/sdk"
  }
}

Next Steps

• Configuration — Configure pikku.config.json for your project
• Tree-Shaking — Learn how filtering and tree-shaking work
• Errors — CLI error code reference