⚔️ Hanma CLI

What is Hanma?

Hanma is a specialized CLI engine designed to eliminate the tedious "boilerplate phase" of backend development. Inspired by tools like shadcn/ui but built for the server-side, Hanma doesn't provide a library; it provides source code.

Why Hanma?

• Zero Lock-in: You own the code. Once added, it's just local files in your project. No runtime dependencies on Hanma.
• Composable Architecture: Mix and match templates. Need Express with Drizzle, Clerk Auth, and Socket.io? Hanma builds it for you.
• Framework Aware: Hanma understands whether you're using Express, Hono, or Elysia and adapts the code it gives you accordingly.
• Production Grade: Every snippet and module following industry best practices for security, types, and structure.
• Offline Aware & Faster: Registry data is cached locally, allowing for instant lookups and fallback when offline.

Core Concepts

To get the most out of Hanma, it helps to understand the three types of code it provides:

1. Composable Templates (create)

Scaffolding a project isn't just picking a framework. It's picking a stack. The create command uses a composable engine that stitches together base frameworks with database ORMs, auth handlers, and middleware setups during initialization.

2. Modules (module)

A module is a complex, multi-file feature. Adding a "Better Auth" module doesn't just add one file; it adds routes, middleware, types, and schema files, ensuring everything is wired up correctly from the start.

3. Snippets (add)

The building blocks. Individual files or functions for specific tasks—CORS setup, JWT utilities, validation schemas, or custom error handlers.

Quick Start

# Start the interactive project builder
npx hanma create my-project

# Add a module to an existing project
cd my-project
npx hanma mod drizzle-postgres

# Inject a specific utility snippet
npx hanma add logger

# Sync all registry metadata and verify cache
npx hanma sync --info

Detailed Command Reference

create [name]

The entry point for new projects.

| Flag | Description | |:---|:---| | --framework <fw> | Force a specific framework (e.g., express, hono, elysia) | | --database <db> | Pre-select database (e.g., drizzle-postgres, prisma-mysql) | | --auth <auth> | Pre-select auth provider (e.g., better-auth, clerk, jwt) | | --pm <package-manager> | Select package manager (only shows installed ones) | | --skip-install | Scaffold only, don't run the installer |

Note: The CLI automatically detects which package managers are installed on your system and only shows those as options.

add [snippets...]

Smart snippet injection. Hanma reads your hanma.json to ensure you get the right code for your framework.

# Multi-select interactively (recommened)
hanma add

# Category filtered select
hanma add --category middleware

show <type> [name]

The Discovery Engine. Browse the registry without leaving your terminal.

• hanma show snippets: List all snippets for your detected framework.
• hanma show templates: Browse the scaffolding library.
• hanma show modules: See complex multi-file features.
• hanma show tooling: Browse dev-tools configurations.

sync

Registry & Cache Management. Keep your local registry metadata updated.

• hanma sync: Refresh all registry metadata from the remote source.
• hanma sync --info: View local cache statistics (size, files, last update).
• hanma sync --clear: Wipe the local cache to force a fresh pull on next command.

update

Keep your CLI up to date.

# Check for updates
hanma update --check

# Update to latest version
hanma update

Compatibility Matrix

Hanma is designed to grow. Here is the current state of support:

| Feature Area | Express | Hono | Elysia | Fastify | |:---|:---:|:---:|:---:|:---:| | Core Scaffolding | ✅ | ✅ | ✅ | 🚧 | | Snippet Library | ✅ | ✅ | ✅ | ✅ | | Auth Modules | ✅ | ✅ | ✅ | 🚧 | | DB Integrations | ✅ | ✅ | ✅ | ✅ | | Tooling (Biome, etc) | ✅ | ✅ | ✅ | ✅ |

⚙️ How it Works: hanma.json

When you run hanma init or hanma create, a small configuration file is created. This is the brain of the CLI—it keeps Hanma "framework aware".

{
  "framework": "express",
  "componentsPath": "src",
  "utilsPath": "src/utils"
}

• Framework Awareness: When you run hanma add cors, Hanma checks this file. If it's express, it fetches the Express middleware. If it's hono, it fetches the Hono version.
• Custom Paths: Tired of src/? Change componentsPath to ./lib and Hanma will respect it.

Documentation & Resources

• Full Documentation: hanma-a2n.pages.dev/docs
• Code Patterns: View the source of snippets at our Web Registry.
• GitHub: itstheanurag/hanma

License

MIT © Gaurav Kumar