CLI Reference for Coding Agents

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

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

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

dist/
├── index.js               # Entry point
├── app.module.js
├── modules/
│   ├── auth/
│   ├── products/
│   └── ...
└── ... (all compiled code)

src/widgets/out/           # Built widgets

# 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

src/modules/payments/
├── payments.module.ts       # @Module definition
├── payments.tools.ts        # @Tool definitions
├── payments.resources.ts    # @Resource definitions
├── payments.prompts.ts      # @Prompt definitions
└── payments.service.ts      # @Injectable service

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-cli cursor

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

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

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

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

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

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

# Custom output zip name
nitrostack-cli 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 globally
npm install -g @nitrostack/cli

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

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

# Or terminate process on port gracefully
lsof -ti:3000 | xargs kill -15
lsof -ti:3001 | xargs kill -15

# 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