@geekmidas/cli

A powerful CLI tool for building and managing TypeScript-based backend APIs with serverless deployment support. Generate AWS Lambda handlers, OpenAPI documentation, and server applications from your endpoint definitions.

Features

- Project Scaffolding: Interactive init command to bootstrap new projects with templates
- Multi-Provider Support: Generate handlers for AWS Lambda (API Gateway v1/v2) and server applications
- Development Server: Hot-reload development server with file watching
- Telescope Integration: Laravel-style debugging dashboard for inspecting requests, logs, and exceptions
- OpenAPI Generation: Auto-generate OpenAPI 3.0 specifications from your endpoints
- Docker Support: Generate optimized Dockerfiles with multi-stage builds, turbo prune for monorepos
- Secrets Management: Secure credential generation, encryption, and stage-based secrets storage
- Deploy Commands: One-command deployment to Docker registries and Dokploy with encrypted secrets
- Authentication: Store credentials locally for seamless deployment without environment variables
- Type-Safe Configuration: Configuration with TypeScript support and validation
- Endpoint Auto-Discovery: Automatically find and load endpoints from your codebase
- Flexible Routing: Support for glob patterns to discover route files
- Environment Integration: Seamless integration with @geekmidas/envkit for configuration
- Logger Integration: Built-in logging configuration and integration
- Monorepo Support: Optional pnpm workspace monorepo setup with shared packages

Installation

``bash
npm install @geekmidas/cli
`

$3

`bash
npm install -g @geekmidas/cli
`

Quick Start

$3

The fastest way to get started is with the interactive init command:

`bash
npx @geekmidas/cli init my-api
`

This will guide you through setting up a new project with your preferred options.

$3

$3

Create a gkm.config.ts file in your project root:

`typescript
import { defineConfig } from '@geekmidas/cli/config';

export default defineConfig({
// Glob pattern to find endpoint files
routes: 'src/routes/*/.ts',

// Optional: Functions
functions: 'src/functions/*/.ts',

// Optional: Cron jobs
crons: 'src/crons/*/.ts',

// Optional: Event subscribers
subscribers: 'src/subscribers/*/.ts',

// Environment parser configuration
envParser: './src/env.ts#envParser',

// Logger configuration
logger: './src/logger.ts#logger',

// Optional: Telescope debugging dashboard (enabled by default in dev)
telescope: {
enabled: true,
path: '/__telescope',
},
});
`

$3

Create src/env.ts:

`typescript
import { EnvironmentParser } from '@geekmidas/envkit';

export const envParser = new EnvironmentParser(process.env)
.create((get) => ({
database: {
url: get('DATABASE_URL').string().url(),
},
api: {
port: get('PORT').string().transform(Number).default('3000'),
},
aws: {
region: get('AWS_REGION').string().default('us-east-1'),
},
}))
.parse();
`

$3

Create src/logger.ts:

`typescript
import { ConsoleLogger } from '@geekmidas/logger/console';

export const logger = new ConsoleLogger({
level: process.env.LOG_LEVEL || 'info',
pretty: process.env.NODE_ENV !== 'production',
});
`

$3

Create endpoint files in src/routes/:

`typescript
// src/routes/users.ts
import { e } from '@geekmidas/constructs/endpoints';
import { z } from 'zod';

export const getUsers = e
.get('/users')
.output(z.array(z.object({ id: z.string(), name: z.string() })))
.handle(async () => {
return [{ id: '1', name: 'John Doe' }];
});

export const createUser = e
.post('/users')
.body(z.object({ name: z.string() }))
.output(z.object({ id: z.string(), name: z.string() }))
.handle(async ({ body }) => {
return { id: '2', name: body.name };
});
`

$3

Create event subscribers in src/subscribers/:

`typescript
// src/subscribers/userSubscriber.ts
import { SubscriberBuilder } from '@geekmidas/constructs/subscribers';
import type { Service } from '@geekmidas/services';
import type { EventPublisher, PublishableMessage } from '@geekmidas/events';
import type { EnvironmentParser } from '@geekmidas/envkit';

// Define event types
type UserEvents =
| PublishableMessage<'user.created', { userId: string; email: string }>
| PublishableMessage<'user.updated', { userId: string }>;

// Create event publisher service
const userEventPublisher = {
serviceName: 'userEventPublisher' as const,
async register(envParser: EnvironmentParser<{}>) {
const config = envParser.create((get) => ({
publisherUrl: get('EVENT_PUBLISHER_URL').string()
})).parse();

const { Publisher } = await import('@geekmidas/events');
return Publisher.fromConnectionString(config.publisherUrl);
}
} satisfies Service<'userEventPublisher', EventPublisher>;

// Create subscriber
export const userCreatedSubscriber = new SubscriberBuilder()
.publisher(userEventPublisher)
.subscribe(['user.created'])
.handle(async ({ events, logger }) => {
for (const event of events) {
logger.info({ userId: event.payload.userId }, 'Processing user.created event');
// Process event...
}
});
`

$3

`bash


Generate AWS Lambda handlers

npx gkm build --provider aws-apigatewayv1

Generate server application

npx gkm build --provider server

Generate OpenAPI TypeScript module

npx gkm openapi --output src/api.ts
`

CLI Commands

$3

Scaffold a new project with interactive prompts.

`bash
gkm init [name] [options]
`

Arguments:
- [name]: Project name (optional, will prompt if not provided)

Options:
- --template