@maktouch/devctl

DevCTL

DevCTL is a CLI app designed to:

• start docker-compose presets for easier onboarding and project switching
• customize what to run depending on what you're working on
• run everything through a local HTTPS proxy for easy HTTPS development
• heavily configurable and extensible using NodeJS

Requirements

• Node 16.18.1+
• pnpm (recommended) or npm
• Docker
• Docker Compose V2

Technology Stack

• TypeScript 5.9 - Modern, type-safe development
• oclif 4 - Industry-standard CLI framework
• pnpm - Fast, efficient package manager
• Docker Compose V2 - Container orchestration

What DevCTL is useful for

• You have a frontend team that prefers to use the staging environment as their backend, so they don't need the API running
• You have a backend team that needs to run MySQL and Redis locally so they can test migrations and new endpoints
• You have a fullstack integration team that requires both frontend and backend to run on their machine, but they don't want to run MySQL, they prefer to use the shared Dev MySQL on the office servers
• You switch between projects back and forth, and they all have their own services to run, and they collide in ports.
• You have a new guy to onboard fast.

DevCTL decreases the onboarding time of new devs in any of our projects. All the new users needs to have installed is docker (with docker compose V2) and NodeJS 16+. Once a project is setup with devctl, its users does not require knowledge of docker.

What DevCTL is NOT

• It is not a thick layer on docker compose. It's a tool to switch "presets" of services. For advanced use cases, you still need to know how docker compose and its networking components works. For simple use cases, the CLI generators should be enought to help you. If you don't understand docker compose, this project will most likely make it more confusing.
• The docker-compose.yaml files that it generates are not meant to be used in production.

Getting Started

# Install globally
pnpm add -g @maktouch/devctl
# or
npm install -g @maktouch/devctl

# Initialize a new project
devctl init

# Switch services and start
devctl switch

# View available commands
devctl --help

Available Commands

• devctl init - Initialize a new devctl project with database presets
• devctl switch - Interactively select services and environment, then start alongside other running projects
• devctl up - Start selected services alongside other running projects
• devctl up --no-merge - Stop other tracked projects before starting selected services
• devctl down - Stop and remove containers for the current project
• devctl down --all - Stop and remove containers for all tracked projects
• devctl status - View current configuration
• devctl logs - View container logs
• devctl exec - Execute commands in running containers
• devctl run - Run one-off commands
• devctl secrets - Pull secrets from configured providers
• devctl compile - Generate docker-compose.yaml (advanced)

Custom Commands (TypeScript Example)

Define a custom command in .devctl.yaml and implement the handler in TypeScript. TypeScript handlers are compiled on the fly using esbuild — no extra dependencies needed in your project.

# .devctl.yaml
commands:
  - name: setup-ssl
    description: Generate local SSL certificates using mkcert
    handler: .devctl/commands/setup-ssl

// .devctl/commands/setup-ssl/index.ts
import type { CustomCommandPayload } from "@maktouch/devctl";

export default async function setupSsl(payload: CustomCommandPayload) {
  const { projectRoot, config, args } = payload;

  console.log("Project root:", projectRoot);
  console.log("Has config:", Boolean(config));
  console.log("Args:", args);
}

Development

This project is built with:

• TypeScript 5.9 for type safety
• oclif for modern CLI architecture
• pnpm for efficient package management

See MIGRATION.md for details on the modern architecture.

Documentation

Guides

• HTTPS Proxy Setup - Complete guide to setting up local HTTPS development with the DevCTL proxy

References

• Configuration Reference - .devctl.yaml and .devconfig.yaml documentation
• Migration Guide - Details on the modern TypeScript architecture