kpm

Kotlin/Java package manager for Gradle. Search, pick, done.

kpm is a CLI tool that lets you search Maven Central and Google Maven interactively, pick a version, and add the dependency to your build.gradle or build.gradle.kts — including required plugins and annotation processors.

$ kpm add room
┌  kpm add
│
◇  Search complete
│
◆  Choose a library (12 results)
│  ● androidx.room:room-runtime (2.8.4 • 45 versions • aar • 2d ago)
│  ○ androidx.room:room-ktx
│  ○ androidx.room:room-compiler
│  ○ → Refine search...
│
◆  Choose a version
│  2.8.4 ✓ latest stable
│  2.8.3
│  2.8.2
│  ── pre-release ──
│  2.9.0-alpha01
│
◇  Added androidx.room:room-runtime:2.8.4 to app/build.gradle.kts

Features

• Search across sources — queries Maven Central and Google Maven in parallel
• Ranked results — official/first-party libraries appear first, sorted by popularity
• Smart hints — shows version count, packaging type, and last update for each result
• Stable vs pre-release — clearly separated in the version picker
• Auto plugin management — detects libraries that need KSP, kapt, or Compose plugins and adds them automatically
• Auto processor detection — adds annotation processors (Room compiler, Hilt compiler, etc.) alongside the main dependency
• Idempotent — running kpm add twice won't duplicate entries
• Multi-module support — detects and lets you choose which module to add the dependency to
• Refine search — if too many results, refine your query without restarting
• List dependencies — view all dependencies in your project
• Update dependencies — update to latest stable version
• Search without adding — explore libraries without modifying your project

Installation

Requires Bun v1.3+.

From npm (recommended)

npm install -g @hmh-3080/kpm

From source

git clone https://github.com/HMH-3080/kpm.git
cd kpm
bun install
bun run dev

Build standalone binary

bun run build
./kpm add <library>

Usage

Add a dependency

# Search and add interactively
kpm add coil-compose

# Specify a module
kpm add retrofit --module app

# Search with a specific query
kpm add "ktor client"

List dependencies

# List all dependencies in the current project
kpm list

# Specify a module
kpm list --module app

Update a dependency

# Update interactively
kpm update

# Specify a module
kpm update --module app

Search without adding

# Search for libraries
kpm search "image loading"

# Search for specific library
kpm search coil-compose

How it works

1. Search — queries Maven Central (Solr API) and Google Maven (XML API) in parallel
2. Pick library — shows top 10 results ranked by popularity; use → Refine search... to narrow down
3. Pick version — stable versions listed first, pre-release clearly marked
4. Choose module — if multiple modules exist, pick one
5. Write — adds implementation(...) line (and plugins/processors if needed)

Auto-detected libraries

These libraries get automatic plugin and processor handling:

| Library | Plugin | Processor | |---------|--------|-----------| | androidx.room:room-runtime | KSP | room-compiler (ksp) | | androidx.room:room-ktx | KSP | room-compiler (ksp) | | androidx.room:room-paging | KSP | room-compiler (ksp) | | com.google.dagger:hilt-android | Hilt | hilt-android-compiler (kapt) | | com.google.dagger:dagger | KSP | dagger-compiler (ksp) | | com.squareup.moshi:moshi-kotlin | — | moshi-kotlin-codegen (ksp) | | androidx.compose.ui:ui | Compose | — | | androidx.compose.material3:material3 | Compose | — | | androidx.compose.runtime:runtime | Compose | — | | androidx.compose.foundation:foundation | Compose | — | | androidx.compose.ui:ui-tooling-preview | Compose | — | | org.jetbrains.kotlinx:kotlinx-serialization-json | Serialization | — | | org.jetbrains.kotlinx:kotlinx-serialization-core | Serialization | — | | com.github.bumptech.glide:glide | KSP | glide:ksp | | androidx.paging:paging-runtime | KSP | paging-common (ksp) | | androidx.work:work-runtime-ktx | KSP | work-runtime (ksp) |

For example, adding room-runtime will:

1. Add id("com.google.devtools.ksp") to the plugins {} block
2. Add implementation("androidx.room:room-runtime:2.8.4") to dependencies {}
3. Add ksp("androidx.room:room-compiler:2.8.4") to dependencies {}

Ranking system

Search results are ranked by:

1. Group match — libraries whose group ID matches the query get a massive boost (official libraries first)
2. Version count — more versions = more mature project
3. Recency — recently updated libraries score higher

This ensures io.ktor:ktor appears before third-party wrappers when you search for "ktor".

Project structure

kpm/
├── index.ts                    # CLI entry point
├── src/
│   ├── commands/
│   │   ├── add.ts              # Add command
│   │   ├── list.ts             # List command
│   │   ├── update.ts           # Update command
│   │   └── search.ts           # Search command
│   └── lib/
│       ├── types.ts            # Artifact, SpecialDep interfaces
│       ├── ranking.ts          # Popularity scoring algorithm
│       ├── mavenCentral.ts     # Maven Central Solr API + metadata.xml
│       ├── googleMaven.ts      # Google Maven XML API
│       ├── findGradleFile.ts   # Recursive walk for build.gradle(.kts)
│       ├── gradleWriter.ts     # Writes dependencies into Gradle files
│       ├── gradleParser.ts     # Parses dependencies from Gradle files
│       ├── specialDeps.ts      # Auto-detected plugin/processor map
│       └── __tests__/          # Test files
├── package.json
└── README.md

Dependencies

| Package | Purpose | |---------|---------| | commander | CLI framework | | @clack/prompts | Interactive terminal UI | | picocolors | Terminal colors |

Zero runtime dependencies beyond these three.

Development

# Install
bun install

# Run in dev mode
bun run dev

# Build standalone binary
bun run build

# Run tests
bun test

# Type check
bunx tsc --noEmit

Contributing

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Run bun test to verify tests pass
5. Run bunx tsc --noEmit to verify types
6. Submit a PR

See ARCHITECTURE.md for codebase structure and IMPROVEMENTS.md for planned features.

License

MIT