@streetjs/cli

CLI for the StreetJS framework — scaffold projects, generate code, run dev server, manage migrations.

Install

npm install -g @streetjs/cli

Or use without installing:

npx @streetjs/cli create my-api

Quick start

street create my-api
cd my-api
npm install
street dev
# [street] Starting development server...
# [street] Listening on http://0.0.0.0:3000

Commands

street create <project-name>

Scaffolds a complete, production-ready StreetJS project.

street create my-api
street create my-api --install    # auto-install dependencies
street create my-api -i           # shorthand

Generated structure:

my-api/
├── src/
│   ├── main.ts                        # Application entry point
│   ├── controllers/
│   │   ├── example.controller.ts      # Example CRUD controller
│   │   └── health.controller.ts       # Health check endpoint
│   ├── services/
│   │   └── example.service.ts         # Business logic layer
│   ├── repositories/
│   │   └── example.repository.ts      # Data access layer
│   ├── middleware/
│   │   └── auth.ts                    # JWT auth + role middleware
│   └── gateways/
│       └── chat.gateway.ts            # WebSocket gateway example
├── tests/
│   └── integration.test.ts            # Integration test suite
├── migrations/                        # SQL migration files
├── uploads/                           # File upload storage
├── docker-init/
│   └── 001_enable_pgcrypto.sql
├── package.json
├── tsconfig.json
├── street.config.ts
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
└── README.md

The generated project includes:

• Strict TypeScript with NodeNext module resolution
• Full CRUD REST API with OpenAPI annotations
• JWT authentication middleware
• WebSocket gateway
• PostgreSQL repository with parameterized queries
• Multi-stage Dockerfile
• Docker Compose with PostgreSQL
• Integration test scaffold

street dev

Starts the development server with hot-reload.

cd my-api
street dev

• Compiles TypeScript on startup
• Starts the server (default port 3000)
• Watches src/ for changes with 300ms debounce
• Recompiles and restarts automatically on save
• Handles SIGTERM/SIGINT for clean shutdown

street build

Compiles TypeScript for production.

cd my-api
street build
# [street] Building project for production...
# [street] Build completed in 2.1s
# [street] Output: ./dist/

Uses the project's tsconfig.json. Output goes to ./dist/.

street start

Starts the production server from compiled output.

cd my-api
street build
street start
# [street] Starting production server...
# [street] Node env: production

Requires dist/main.js to exist. Run street build first.

street test

Runs the project's test suite using Node's built-in test runner.

cd my-api
street test

• Compiles TypeScript first
• Discovers *.test.js files in dist/tests/
• Runs with node --test
• No external test framework required

street generate <type> <name>

Generates a controller, service, or repository with full boilerplate.

street generate controller users
street generate service    users
street generate repository users

Valid types: controller, service, repository

Example — street generate controller users:

// src/controllers/users.controller.ts
@Controller('/api/users')
export class UsersController {
  @Get('/')    async findAll(ctx: StreetContext): Promise<void> { ... }
  @Get('/:id') async findById(ctx: StreetContext): Promise<void> { ... }
  @Post('/')   async create(ctx: StreetContext): Promise<void> { ... }
  @Put('/:id') async update(ctx: StreetContext): Promise<void> { ... }
  @Delete('/:id') async delete(ctx: StreetContext): Promise<void> { ... }
}

Name conventions:

| Input | Class | File | Route | |---|---|---|---| | users | Users | users | /api/users | | blog-post | BlogPost | blog-post | /api/blog-posts | | user_profile | UserProfile | user-profile | /api/user-profiles | | category | Category | category | /api/categories |

street migrate:create <name>

Creates a timestamped SQL migration file pair.

street migrate:create create_users_table
# [street] Created migration: 20260101120000_create_users_table.sql
# [street] Created rollback:  20260101120000_create_users_table.rollback.sql

Files are created in migrations/ with a UTC timestamp prefix for deterministic ordering.

Generated up migration:

-- Migration: create_users_table
-- Created: 2026-01-01T12:00:00.000Z

-- Write your SQL migration here.
-- Example:
--   CREATE TABLE create_users_table (
--     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
--     created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
--     updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
--   );

street migrate:run

Runs all pending SQL migrations in order.

cd my-api
street build
street migrate:run

• Connects to PostgreSQL using environment variables
• Tracks applied migrations in a street_migrations table
• Skips already-applied migrations (idempotent)
• Runs .sql files in timestamp order

Required environment variables:

PG_HOST=localhost
PG_PORT=5432
PG_DATABASE=mydb
PG_USER=postgres
PG_PASSWORD=secret

Global flags

street --version    # street v1.0.2
street --help       # show all commands
street -v           # shorthand version
street -h           # shorthand help

Generated project — getting started

After street create my-api:

cd my-api

# 1. Copy environment file
cp .env.example .env
# Edit .env with your database credentials

# 2. Start PostgreSQL (Docker)
docker compose up -d postgres

# 3. Install dependencies
npm install

# 4. Run migrations
street migrate:run

# 5. Start dev server
street dev
# → http://localhost:3000

# 6. Test endpoints
curl http://localhost:3000/health
curl http://localhost:3000/api/items
curl http://localhost:3000/openapi.json

Generated project — available scripts

| Script | Command | Description | |---|---|---| | npm run dev | street dev | Development server with hot-reload | | npm run build | street build | Compile for production | | npm run start | street start | Start production server | | npm run test | street test | Run test suite | | npm run migrate | street migrate:run | Run pending migrations | | npm run migrate:create | street migrate:create | Create new migration |

Docker

The generated Dockerfile uses a multi-stage build:

# Build and run with Docker
docker build -t my-api .
docker run -p 3000:3000 --env-file .env my-api

# Or with Docker Compose (includes PostgreSQL)
docker compose up

Links

• Documentation
• GitHub
• npm — @streetjs/cli
• npm — streetjs
• Changelog

License

MIT © street contributors