nebutra CLI

The unified Nebutra command-line tool — scaffold, manage infra, run migrations, and more.

The nebutra CLI is your primary tool for day-to-day development inside a Nebutra-Sailor monorepo.

Installation

# Inside the monorepo — no install needed
pnpm exec nebutra --help

# Global install (published [email protected]+)
npm install -g nebutra@latest

Command reference

`nebutra init`

Initialize a Nebutra project and create nebutra.config.json.

nebutra init
nebutra init --dry-run          # Preview without writing files (exit code 10)
nebutra init --if-not-exists    # Skip if config already exists

`nebutra add`

Add a component or feature to your project. Supports 21st.dev and v0.dev registries.

nebutra add button card                   # Add from @nebutra/ui
nebutra add --21st pricing-table          # Fetch from 21st.dev
nebutra add --v0 https://v0.dev/r/abc123  # Fetch from v0.dev
nebutra add button --dry-run              # Preview without installing
nebutra add button --yes                  # Skip prompts (Agent mode)
nebutra add button --if-not-exists        # Skip if already installed

Feature registry

nebutra add <feature> accepts both component names and feature IDs drawn from a two-tier registry:

Hardcoded features (in packages/ops/cli/src/utils/registry.ts):

Feature ID	Group	Purpose
`queue`	integrations	Background job queue (Upstash QStash or BullMQ)
`search`	integrations	Full-text search (Meilisearch or Typesense)
`cache`	integrations	Cache adapter (Upstash Redis, Vercel KV, Redis, Dragonfly)
`notifications`	integrations	Notification workflows (Novu, Knock, custom)
`webhooks`	integrations	Outbound webhooks (Svix, custom)
`cms`	integrations	Headless CMS (Sanity, Contentful, Strapi)
`feature-flags`	platform	Feature flags (Vercel Flags, GrowthBook, ConfigCat)
`captcha`	iam	Captcha verification (Turnstile, hCaptcha, Aliyun)

Dynamically discovered features — any workspace package that declares a "nebutra": { "featureId": "..." } block in its package.json. Today this surfaces:

vault, audit, tenant, permissions, metering, license, waitlist, uploads, saga, email, design-sync, agents, mcp.

Listing both tiers:

nebutra add --list                 # All available features (hardcoded + discovered)

Discovered features pin themselves to npm caret ranges (^0.x.y) from the published-versions registry — never workspace:* — so generated package.json files install cleanly outside the monorepo.

`nebutra generate` (alias: `gen`)

Scaffold new apps, packages, API routes, and UI components.

Scaffold a new Next.js 16 app with Tailwind v4:

nebutra generate app my-blog
nebutra gen app my-blog --dry-run

Creates apps/my-blog/ with package.json, tsconfig.json, layout, page, and globals.

Scaffold a new @nebutra/<name> package:

nebutra generate package notifications
nebutra gen package notifications --dry-run

Creates packages/integrations/notifications/ with package.json, tsconfig.json, and src/index.ts.

Scaffold a Hono API route in backends/gateway:

nebutra generate route projects
nebutra gen route projects/members

Creates backends/gateway/src/routes/projects.ts with GET and POST handlers.

Scaffold a UI component with a Storybook story:

nebutra generate component PricingCard
nebutra gen component PricingCard --variants "primary,outlined" --sizes "sm,md,lg"

Creates packages/design/ui/src/components/pricing-card.tsx + .stories.tsx.

`nebutra db`

Database management via Prisma.

Subcommand	Description
`db generate`	Regenerate Prisma client
`db migrate`	Run all pending migrations
`db migrate create <name>`	Create a new named migration
`db push`	Push schema to database (no migration file)
`db seed`	Populate test data
`db studio`	Launch Prisma Studio GUI
`db reset --yes`	⚠️ Reset entire database
`db status`	Show migration status

nebutra db generate
nebutra db migrate
nebutra db migrate create add-user-table
nebutra db push
nebutra db seed
nebutra db studio
nebutra db reset --yes     # DANGEROUS — requires --yes
nebutra db status --format json

Flags: --dry-run, --yes, --format <json|plain>

`nebutra infra`

Docker Compose infrastructure management (PostgreSQL, Redis, Meilisearch, ClickHouse, etc.).

Subcommand	Description
`infra up`	Start the full Docker stack
`infra up --lite`	Start lite stack (PostgreSQL + Redis only)
`infra up --profile search`	Start with Meilisearch profile
`infra down`	Stop all services
`infra status`	Show service status table
`infra logs [service]`	Show last 50 log lines
`infra reset --yes`	⚠️ Remove all containers and volumes

nebutra infra up
nebutra infra up --lite
nebutra infra up --profile search
nebutra infra down
nebutra infra status
nebutra infra status --format json
nebutra infra logs
nebutra infra logs postgres
nebutra infra reset --yes    # DANGEROUS

Flags: --dry-run, --yes, --lite, --profile <name>, --format <json|plain>

`nebutra env`

Environment variable management.

Subcommand	Description
`env validate`	Check all required vars from `.env.example` are set
`env template`	Generate `.env.local` interactively from `.env.example`
`env template --yes`	Generate with defaults (non-interactive)
`env diff`	Compare `.env.local` vs `.env.example`
`env show`	Display current vars (secrets are masked)

nebutra env validate
nebutra env template
nebutra env template --yes
nebutra env diff
nebutra env show
nebutra env show --format json

Variables with KEY, TOKEN, SECRET, or PASSWORD in their name are automatically masked in env show output.

Flags: --dry-run, --yes, --format <json|plain>

`nebutra brand`

Brand management and palette generation.

nebutra brand init                                              # Initialize brand configuration
nebutra brand apply                                             # Apply brand to all packages
nebutra brand palette --primary=#7C3AED --secondary=#F59E0B   # Generate palette
nebutra brand sync                                              # Sync brand assets across packages
nebutra brand verify                                            # Validate brand consistency

`nebutra i18n`

Internationalization utilities.

nebutra i18n sync              # Sync translation files across locales
nebutra i18n validate          # Validate all locale files
nebutra i18n add zh-TW         # Add a new locale
nebutra i18n status            # Show translation coverage per locale

`nebutra preset`

SaaS configuration preset management.

nebutra preset list                   # List available presets
nebutra preset list --format json
nebutra preset show ai-saas           # Show preset details
nebutra preset apply ai-saas          # Apply a preset
nebutra preset env                    # Show env vars for current preset
nebutra preset features               # Show features for current preset
nebutra preset diff ai-saas growth    # Diff two presets

`nebutra dev`

Start development servers with preset filtering.

nebutra dev                           # Start all apps
nebutra dev --preset=ai-saas          # Start AI SaaS preset apps only
nebutra dev --preset=dashboard        # Web + API gateway only
nebutra dev --preset=marketing        # Landing page + Studio

`nebutra test`

Run tests.

nebutra test                          # Run all unit tests (Vitest)
nebutra test e2e                      # Playwright E2E tests
nebutra test e2e --ui                 # E2E tests with Playwright UI mode
nebutra test e2e --ci                 # E2E tests in CI mode (headless)
nebutra test arch                     # Architecture conformance tests
nebutra test --coverage               # With coverage report
nebutra test size                     # Check bundle size against budget
nebutra test size --why               # Detailed bundle composition analysis
nebutra test --app web                # Run tests for a specific app

`nebutra auth`

Authentication configuration.

nebutra auth status                   # Current auth provider and config
nebutra auth setup clerk              # Configure Clerk provider
nebutra auth setup better-auth        # Configure Better Auth
nebutra auth keys                     # Manage auth provider API keys

`nebutra billing`

Billing and subscription management.

nebutra billing status                # Current billing config
nebutra billing setup stripe          # Configure Stripe billing
nebutra billing setup lemonsqueezy    # Configure LemonSqueezy billing
nebutra billing setup polar           # Configure Polar billing
nebutra billing setup chinapay        # Configure ChinaPay billing
nebutra billing webhooks              # Manage billing webhook endpoints

`nebutra ai`

AI provider and SDK configuration.

nebutra ai models                     # List available AI models
nebutra ai agents                     # Manage AI agent configurations
nebutra ai test "hello world"         # Test current AI provider
nebutra ai config                     # Show/edit AI configuration

`nebutra secrets`

Application-layer encrypted secrets (via @nebutra/vault).

nebutra secrets list --tenant org_123
nebutra secrets set openai_key --tenant org_123 --value sk-...
nebutra secrets get openai_key --tenant org_123
nebutra secrets rotate openai_key --tenant org_123
nebutra secrets audit --tenant org_123
nebutra secrets verify --tenant org_123

`nebutra services`

Microservice health and status.

nebutra services status               # Health overview of all services
nebutra services health               # Detailed health check
nebutra services logs api-gateway     # Stream logs for a service
nebutra services restart api-gateway  # Restart a service
nebutra services scale api-gateway 3  # Scale service to N instances

`nebutra search`

Full-text search index management (Meilisearch / Typesense / Algolia).

nebutra search status                 # Search provider status
nebutra search indexes                # List all search indexes
nebutra search reindex products       # Reindex a specific index
nebutra search reindex --force --yes  # Reindex all indexes (no prompt)
nebutra search query products "widget" # Run a test query
nebutra search stats                  # Index statistics

`nebutra admin`

Platform administration.

nebutra admin tenants                 # List all tenants
nebutra admin tenants --format json
nebutra admin health                  # Platform-wide health check

`nebutra community`

Community health and showcase.

nebutra community health              # Community health score
nebutra community health --period 30d # Last 30 days
nebutra community showcase list       # Browse project showcase

The community commands are not yet fully implemented. The interface is defined but output may be limited in the current release.

`nebutra growth`

Growth metrics and analytics.

nebutra growth dashboard              # Growth overview
nebutra growth funnel                 # Conversion funnel
nebutra growth funnel --segment paid  # Filter by segment
nebutra growth pulse                  # AI-powered growth insights
nebutra growth pulse --focus retention

The growth commands are not yet fully implemented. The interface is defined but output may be limited in the current release.

`nebutra ecosystem`

Ecosystem and template marketplace.

nebutra ecosystem status              # Ecosystem dashboard
nebutra ecosystem publish --tag latest  # Publish template
nebutra ecosystem ideas list          # Browse ideas marketplace
nebutra ecosystem opc register        # Join OPC member network

The ecosystem commands are not yet fully implemented. The interface is defined but output may be limited in the current release.

`nebutra schema`

Output the full CLI schema as JSON (useful for AI tools and tooling integrations).

nebutra schema                        # Human-readable schema
nebutra schema --all                  # Full schema for Agents (JSON output)
nebutra schema --list                 # List all commands
nebutra schema --exit-codes           # List all exit codes with descriptions

`nebutra stats`

Monorepo overview and statistics.

nebutra stats                         # Package count, app count, etc.
nebutra stats --format json

`nebutra completions`

Install shell completions for bash, zsh, or fish.

nebutra completions bash              # Install bash completions
nebutra completions zsh               # Install zsh completions
nebutra completions fish              # Install fish completions

`nebutra doctor`

Check your project setup for common issues.

nebutra doctor

The doctor command is not yet fully implemented. Basic checks run, but comprehensive diagnostics are coming in a future release.

`nebutra mcp`

Start the MCP (Model Context Protocol) context server for AI coding tools (Cursor, Windsurf, Claude Code).

nebutra mcp                           # Start the MCP context server

`nebutra workflow`

Scaffold a starter file for a workflow provider into workflows/<provider>/. Refuses to overwrite an existing file.

nebutra workflow init inngest          # workflows/inngest/example.ts
nebutra workflow init n8n              # workflows/n8n/README.md + example.json
nebutra workflow init pusher           # workflows/pusher/example.ts
nebutra workflow init inngest --dry-run

Provider	Files created
`inngest`	`workflows/inngest/example.ts` (Inngest function skeleton)
`n8n`	`workflows/n8n/README.md` + `workflows/n8n/example.json` (self-hosted convention)
`pusher`	`workflows/pusher/example.ts` (channels publisher)

Exit codes: 0 on success, 9 (CONFLICT) if every target file already exists, 10 on --dry-run.

`nebutra backend`

Scaffold a backend service. Two runtimes — TypeScript (backends/gateway/) is the default per ADR 2026-05-10.

# TypeScript gateway (Hono) — only needed in downstream consumer monorepos
nebutra backend init ts

# Python (FastAPI) — only when the ADR justification applies
nebutra backend init py --name translator
nebutra backend init py --name translator --dry-run

Runtime	Output	Notes
`ts`	`backends/gateway/{package.json,src/index.ts,README.md}`	Skipped when `backends/gateway/` already exists
`py`	`backends/python/<name>/{pyproject.toml,README.md,src/main.py,src/__init__.py}`	Generated README cites ADR 2026-05-10 with placeholder for the concrete justification

The --name flag is required for py in non-interactive mode; otherwise it is prompted. Name format: ^[a-z][a-z0-9_-]{0,40}$.

`nebutra e2e`

Run a Playwright suite via its dedicated config in e2e/.

nebutra e2e smoke                      # e2e/playwright.config.ts
nebutra e2e golden                     # e2e/playwright.golden.config.ts
nebutra e2e sleptons                   # e2e/playwright.sleptons.config.ts
nebutra e2e smoke --dry-run            # prints the `playwright test` task that would run

Suite	Config	Suite dir
`smoke`	`e2e/playwright.config.ts`	`e2e/smoke/`
`golden`	`e2e/playwright.golden.config.ts`	`e2e/golden/`
`sleptons`	`e2e/playwright.sleptons.config.ts`	`e2e/sleptons/`

The command exits with the Playwright runner's exit code, or 7 (NOT_FOUND) if the suite directory or config is missing.

Agent mode

All commands support --yes for non-interactive execution in CI/CD pipelines, agent environments, and scripting:

# Safe for CI/CD and AI agents
nebutra init --yes
nebutra add button card --yes
nebutra env template --yes
nebutra db migrate --yes
nebutra generate app analytics --yes

When running in a non-TTY environment (piped output, CI), --yes is automatically implied.

Dry-run mode

Use --dry-run to preview changes without side effects. Returns exit code 10 when dry-run completes successfully:

nebutra init --dry-run
nebutra add button --dry-run
nebutra generate app my-blog --dry-run
nebutra db migrate --dry-run
nebutra infra up --dry-run

Dry-run output is always JSON-structured for easy parsing by agents.

On this page