devkit

devkit is a multi-command CLI toolkit written in Go that automates common DevOps workflows. It consolidates tasks typically handled by scattered, brittle Bash scripts into a single, portable, cross-platform binary.

---

Table of Contents

• Overview
• Installation
• Commands
  • scaffold
  • health
  • report
• Development

---

Overview

devkit provides three core subcommands:

Command	Description
scaffold	Generate project boilerplate from templates
health	Check reachability and health of hosts/URLs
report	Scan a directory and output a structured summary

---

Installation

git clone https://github.com/Surfs101/devtoolkit.git
cd devtoolkit
go build -o devkit .

Or run directly without building:

go run main.go <command> [flags]

---

Commands

scaffold

Generate realistic project boilerplate from templates. Replaces manual directory and file creation with a single, repeatable command.

Usage:

devkit scaffold --type <type> --name <name> --dir <dir> [--count <n>]

Flags:

Flag	Short	Default	Description
--type	-t	service	Template type: service, k8s, log
--name	-n	(required)	Name of the project
--dir	-d	.	Parent output directory
--count	-c	1	Number of instances to create

Template Types:

• service — Creates a service project with config.yaml, README.md, and .env.example
• k8s — Creates Kubernetes manifests: deployment.yaml, service.yaml, configmap.yaml
• log — Creates a log directory structure with app/, error/, and audit/ subdirectories (each with a .gitkeep)

Examples:

# Scaffold a single service project
devkit scaffold --type service --name auth-api --dir ./projects

# Scaffold Kubernetes manifests
devkit scaffold --type k8s --name my-app --dir ./manifests

# Scaffold a log directory structure
devkit scaffold --type log --name app-logs --dir ./logs

# Scaffold 3 service instances (creates api_1, api_2, api_3)
devkit scaffold --type service --name api --dir ./projects --count 3

Output:

✓ Created service project "auth-api" at ./projects/auth-api

---

health

Diagnose the reachability and health of a list of hosts or URLs in parallel. Reports DNS resolution, TCP connectivity, HTTP status, and latency per host.

Usage:

devkit health --hosts github.com,192.168.1.10,localhost:8080

Flags:

Flag	Short	Default	Description
--hosts	-H	(required)	Comma-separated list of hosts or URLs

Example Output:

HOST              DNS    TCP    HTTP   LATENCY   STATUS
github.com         ✓      ✓     200    180ms     HEALTHY
192.168.1.10       ✓      ✗      -      -        UNREACHABLE
badhost.local      ✗      -      -      -        DNS FAILED
localhost:8080     ✓      ✓     503    4ms       DEGRADED

---

report

Scan a directory recursively and output a structured summary of its contents. Supports table and JSON output modes.

Usage:

devkit report --dir ./projects/auth-api
devkit report --dir ./projects --format json

Flags:

Flag	Short	Default	Description
--dir	-d	.	Directory to scan
--format	-f	table	Output format: table, json

Example Output (table):

Directory Report: ./projects/auth-api
─────────────────────────────────────
Total Files:       12
Total Dirs:        4
Total Size:        48 KB

File Types:
  .yaml            5
  .md              3
  .env             1

Largest Files:
  deployment.yaml  12 KB
  README.md        8 KB
  config.yaml      6 KB

---

Development

# Build
make build

# Vet
make vet

# Test
make test

# Run all checks
make verify

Project Structure:

devtoolkit/
├── cmd/              # Cobra command definitions (thin wrappers)
│   ├── root.go
│   ├── scaffold.go
│   ├── health.go
│   └── report.go
├── internal/         # Core business logic
│   ├── scaffold/
│   ├── health/
│   └── report/
├── docs/specs/       # Feature specifications
├── main.go
└── Makefile

All business logic lives in internal/. The cmd/ layer only reads flags, constructs option structs, and delegates to the internal packages.