NitroStack CLI Reference - For AI Code Editors

# Global install (recommended)
npm install -g @nitrostack/cli

# Or run on-demand with npx
npx @nitrostack/cli <command>

nitrostack init <project-name> [options]         # Create new project
nitrostack dev [--port <number>]                 # Start development mode
nitrostack build [--output <path>]               # Build for production
nitrostack start [--port <number>]               # Start production MCP server
nitrostack generate <type> [name] [options]      # Generate code boilerplate
nitrostack upgrade [--dry-run] [--latest]        # Upgrade packages & skills
nitrostack install [--skip-widgets]              # Install root and widget deps
nitrostack cursor [options]                      # Configure Cursor IDE MCP integration
nitrostack pack [options]                        # Package production zip bundle
nitrostack --version                             # Show version
nitrostack --help                                # Show help

# Basic initialization (uses typescript-starter)
npx @nitrostack/cli init my-project

# Using preset shorthand:
npx @nitrostack/cli init my-project --preset starter
npx @nitrostack/cli init my-enterprise --preset enterprise-search
npx @nitrostack/cli init my-codemode --preset code-mode
npx @nitrostack/cli init my-pizzaz --preset pizzaz
npx @nitrostack/cli init my-flights --preset oauth

# Or with full template name:
npx @nitrostack/cli init my-enterprise --template typescript-enterprise-search

cd my-project

# Start development (MCP server + widget dev server)
npm run dev

# Start development (MCP server + widget dev server)
nitrostack-cli dev

# Custom port for widget development server (default: 3001)
nitrostack-cli dev --port 3005

nitrostack-cli build

# After build - use npm script (recommended)
npm start

# Or run directly
node dist/index.js

# Or use CLI
nitrostack-cli start

nitrostack-cli generate module payments

nitrostack-cli generate tools process-payment --module payments

nitrostack-cli generate resources payment-schema --module payments

nitrostack-cli generate prompts payment-help --module payments

nitrostack-cli generate guard admin

@Injectable()
export class AdminGuard implements Guard {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    // Your authorization logic
  }
}

@Tool({ name: 'admin_tool' })
@UseGuards(AdminGuard)
async adminTool(input: any, ctx: ExecutionContext) {}

nitrostack-cli generate middleware logging

@Middleware()
export class LoggingMiddleware implements MiddlewareInterface {
  async use(context: ExecutionContext, next: () => Promise<any>) {
    // Before
    const result = await next();
    // After
    return result;
  }
}

nitrostack-cli generate interceptor transform

@Interceptor()
export class TransformInterceptor implements InterceptorInterface {
  async intercept(context: ExecutionContext, next: () => Promise<any>) {
    const result = await next();
    return { success: true, data: result };
  }
}

nitrostack-cli generate pipe validation

@Pipe()
export class ValidationPipe implements PipeInterface {
  async transform(value: any, metadata: any): Promise<any> {
    // Transform/validate value
    return value;
  }
}

# Generate TypeScript types from tool schemas
nitrostack-cli generate types

# Custom output path
nitrostack-cli generate types --output src/widgets/types/generated.ts

@Tool({
  name: 'get_product',
  inputSchema: z.object({
    product_id: z.string()
  })
})
async getProduct(input: any) {
  return { id: input.product_id, name: 'Product', price: 99 };
}

// Auto-generated by NitroStack CLI
export interface GetProductInput {
  product_id: string;
}

export interface GetProductOutput {
  id: string;
  name: string;
  price: number;
}

import { GetProductOutput } from '../../types/tool-data';

export default function ProductCard({ data }: { data: GetProductOutput }) {
  return <div>{data.name} - ${data.price}</div>;
}

# Configure local .cursor/mcp.json (default: command mode)
nitrostack cursor

# Configure with legacy SSE endpoint
nitrostack cursor --type legacy-sse --port 3000

# Configure with modern MCP 2026-07-28 Streamable HTTP endpoint
nitrostack cursor --type streamable-http --url http://localhost:3000/mcp

# Global configuration with overwrite
nitrostack cursor --global --force

# Create deployment bundle (e.g. my-project.zip in root)
nitrostack pack

# Preview files that would be included/excluded
nitrostack pack --dry-run

# Include environment variables if deploying to secure cloud workers
nitrostack pack --include-env

# Custom output zip name
nitrostack pack --output deploy-v1.0.0.zip

import { McpApp, Module, ConfigModule } from '@nitrostack/core';

@McpApp({
  name: 'my-server',
  version: '1.0.0',
  description: 'My MCP server',
  module: AppModule
})
@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: '.env',
    }),
  ]
})
export class AppModule {}

# Node Environment
NODE_ENV=development

# Server Configuration
PORT=3000
MCP_SERVER_PORT=3000
WIDGET_PORT=3001
LOG_LEVEL=info

# OAuth 2.1 (if using typescript-oauth template)
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_REDIRECT_URI=http://localhost:3000/callback

# Gemini API (for Studio chat)
GEMINI_API_KEY=your-gemini-key

# Install CLI
npm install -g @nitrostack/cli

# Initialize project
npx @nitrostack/cli init my-calculator --template typescript-starter
cd my-calculator

# Start development
npm run dev

# Open Studio
# http://localhost:3000

# Initialize flight booking template
npx @nitrostack/cli init flight-booking --preset oauth
cd flight-booking

# Start development
npm run dev

# Initialize enterprise search template
npx @nitrostack/cli init enterprise-portal --preset enterprise-search
cd enterprise-portal

# Start development
npm run dev

# Initialize QuickJS code mode template
npx @nitrostack/cli init data-engine --preset code-mode
cd data-engine

# Start development
npm run dev

# Generate module
nitrostack-cli generate module payments

# Add to app.module.ts imports
# imports: [ConfigModule.forRoot(), PaymentsModule]

# Generate tools
nitrostack-cli generate tools create-payment --module payments
nitrostack-cli generate tools get-payment --module payments

# Generate types for widgets
nitrostack-cli generate types

# Create widget
mkdir -p src/widgets/app/payment-success
# Create page.tsx in that directory

# Test in Studio
npm run dev

# Start dev server (auto-detects and builds everything)
npm run dev

# The CLI automatically:
# - Installs dependencies (if needed)
# - Builds widgets (on first run)
# - Starts TypeScript watch mode
# - Starts Studio
# - Starts widget dev server
# - Hot reloads everything

# Edit code (auto-reloads)
# - Edit src/modules/**/*.ts (MCP server hot reloads)
# - Edit src/widgets/app/**/* (Widget dev server hot reloads)

# Test in Studio
# - Execute tools manually
# - Test with AI chat
# - Preview widgets

# Add widget dependencies
npm run widget add <package-name>

# Generate types for widgets
nitrostack-cli generate types

# Build for production
npm run build

# Test production build
npm start

# Build project
nitrostack-cli build

# Copy to server
scp -r dist/ user@server:/app/
scp -r src/widgets/.next/ user@server:/app/widgets/
scp package.json user@server:/app/
scp .env.production user@server:/app/.env

# On server
cd /app
npm install --production
node dist/index.js

# Install globally
npm install -g nitrostack

# Or use npx
npx nitrostack-cli init my-project

# Use custom port
nitrostack-cli dev --port 3002

# Or kill process on port
lsof -ti:3000 | xargs kill -9
lsof -ti:3001 | xargs kill -9

# Clean and rebuild
rm -rf dist
rm -rf src/widgets/.next
npm run build

# Check TypeScript errors
npx tsc --noEmit

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# The CLI handles widgets automatically, but if you need to debug:

# Install widget dependencies
npm run widget install

# Check widget dev server
curl http://localhost:3001

# Or restart dev mode (rebuilds everything)
npm run dev

# Check MCP server is running
ps aux | grep node

# Check logs
tail -f logs/server.log

# Restart
npm run dev