kmp-commands

name: kmp-commands description: "Essential CLI command reference for Kotlin Multiplatform development. Use when: (1) Running validation before commits, (2) Building Android/Desktop/iOS apps, (3) Running tests across modules, (4) Managing dependencies, (5) Generating changelogs with git-cliff. Keywords: gradle, build, test, validation, CLI commands, git-cliff"

KMP Commands

Essential CLI reference for KMP development.

When to Use This Skill

Use this skill when you need to execute build, test, or maintenance commands. Triggers include: "command", "build", "test", "gradle", "validation", "commit".

Mode Detection

MANDATORY - READ ENTIRE FILE: When encountering CLI command or git commit errors, you MUST read troubleshooting.md (~50 lines) for common issues and solutions.

Do NOT load troubleshooting.md if commands are working correctly.

Related Skills

• @kmp-gradle: For Gradle configuration and convention plugins.

NEVER

• NEVER manually edit CHANGELOG.md. It is auto-generated by git cliff.
• NEVER run iOS builds for routine validation. They take 5-10 minutes. Use the Primary Validation command instead.

Decision Framework

Before running commands, ask yourself:

1. What validation level is needed?

   • Pre-commit → ./gradlew :composeApp:assembleDebug test --continue (45s, ALWAYS run)
   • Full build → Add iOS framework build (5-10min, only when iOS changes)
   • Specific module → ./gradlew :features:<feature>:<layer>:testDebugUnitTest

2. What platform am I targeting?

   • Android → :composeApp:assembleDebug or :composeApp:installDebug
   • Desktop → :composeApp:run (JVM)
   • iOS (native SwiftUI) → Open iosApp/ in Xcode
   • iOS (Compose experimental) → Build framework then open iosAppCompose/ in Xcode

3. What maintenance task is needed?

   • Dependency updates → ./gradlew dependencyUpdates
   • Changelog generation → git cliff -o CHANGELOG.md (NEVER manual edit)
   • Clean build → ./gradlew clean then rebuild

Essential Workflows

Workflow 1: Pre-Commit Validation

1. Save all files and ensure no uncommitted changes
2. Run primary validation: ./gradlew :composeApp:assembleDebug test --continue
3. Wait for completion (~45 seconds)
4. Verify: All tests pass, build succeeds
5. If failures: Fix issues, repeat from step 2
6. Commit with conventional format: type(scope): description

Cross-reference: See @kmp-gradle for build configuration, @kmp-testing-patterns for test debugging

Workflow 2: Running Module-Specific Tests

1. Identify target module (e.g., :features:pokemonlist:presentation)
2. Run tests: ./gradlew :features:pokemonlist:presentation:testDebugUnitTest
3. For all module tests: ./gradlew test --continue
4. Review test output for failures
5. Fix and re-run until all pass

Cross-reference: See @kmp-testing-strategy for test organization, @kmp-architecture for module structure

Workflow 3: Updating Dependencies

1. Check for updates: ./gradlew dependencyUpdates
2. Review stability policy (Stable stays stable, Unstable can upgrade within major.minor)
3. Update gradle/libs.versions.toml with selected versions
4. Refresh: ./gradlew --refresh-dependencies
5. Run full validation: ./gradlew :composeApp:assembleDebug test --continue
6. Commit changes: build(deps): update X to Y

Cross-reference: See @kmp-gradle for version catalog management

Quick Reference (Command Reference)

Primary Validation (ALWAYS RUN FIRST)

# Android build + ALL tests (fastest feedback: ~45 seconds)
./gradlew :composeApp:assembleDebug test --continue

Dependency Management

# Check for available updates
./gradlew dependencyUpdates

# View detailed report
open build/dependencyUpdates/report.html

Stability Rules (configured in root build.gradle.kts):

• ✅ Stable versions stay stable (e.g., 2.8.4 won't upgrade to 2.9.0-alpha01)
• ✅ Unstable versions upgrade within same major.minor:
  • 2.9.0-alpha01 → 2.9.0-alpha03 ✅ (same major.minor)
  • 2.9.0-alpha01 → 2.9.0-beta01 ✅ (same major.minor)
  • 2.9.0-alpha01 → 2.10.0-alpha01 ❌ (different minor)
• ✅ Unstable versions upgrade to ANY stable version:
  • 2.9.0-alpha02 → 3.1.1 ✅ (stable release)

Platform-Specific Commands

# Desktop/JVM
./gradlew :composeApp:run

# Ktor Server (port 8080)
./gradlew :server:run

# Android build
./gradlew :composeApp:assembleDebug

# Unit tests
./gradlew :composeApp:testDebugUnitTest

# Screenshot tests
./gradlew recordRoborazziDebug              # Record baselines
./gradlew verifyRoborazziDebug              # Verify against baselines
./gradlew compareRoborazziDebug             # Compare screenshots

Commits & Changelog

# Commit with Conventional Commits format (required)
git commit -m "type(scope): description"

# Types: feat, fix, docs, test, build, refactor, chore
# Examples:
git commit -m "feat(pokemonlist): add search functionality"
git commit -m "refactor(navigation): align package with folder structure"
git commit -m "docs(conventions): update testing requirements"

# Regenerate CHANGELOG.md from commits (using git-cliff)
git cliff -o CHANGELOG.md

# Preview changelog without writing
git cliff --dry-run

CHANGELOG Policy:

• ❌ DO NOT manually edit CHANGELOG.md — it's auto-generated by git-cliff
• ✅ Use proper Conventional Commits format — git-cliff parses these automatically
• ✅ Regenerate changelog before releases: git cliff -o CHANGELOG.md
• ✅ Commit types map to changelog sections:
  • feat → ✨ Features
  • fix → 🐛 Bug Fixes
  • docs → 📝 Documentation
  • test → ✅ Tests
  • build → 🔧 Build System
  • refactor → ♻️ Refactoring
  • chore → 🧹 Chores

iOS Build Policy ⚠️

NEVER run iOS builds during routine validation (5-10min builds).

Only execute when:

1. Explicitly requested by user
2. Testing iOS framework exports
3. Validating iOS-specific expect/actual implementations
4. Working on SwiftUI integration with shared.framework

iOS Commands (use sparingly):

# Build shared framework for iOS
./gradlew :shared:embedAndSignAppleFrameworkForXcode

# Open iOS projects in Xcode
open iosApp/iosApp.xcodeproj                # Native SwiftUI app (production)
open iosAppCompose/iosAppCompose.xcodeproj  # Compose iOS app (experimental)

Gradle Utility Commands

# Show module structure
./gradlew projects

# Show dependency tree
./gradlew :composeApp:dependencies

# Check for dependency conflicts
./gradlew :composeApp:dependencyInsight --dependency arrow-core

# Refresh dependencies
./gradlew --refresh-dependencies

# Clean build
./gradlew clean

Critical Guardrails

1. NEVER manually edit CHANGELOG.md → use git cliff -o CHANGELOG.md instead (auto-generated from conventional commits, manual edits will be overwritten)

2. NEVER run iOS builds for routine validation → use Primary Validation command (iOS builds take 5-10 minutes vs 45 seconds for Android, blocks development flow)

3. NEVER skip Primary Validation before committing → always run ./gradlew :composeApp:assembleDebug test --continue (catches breaking changes before they reach CI, saves time)

4. NEVER ignore test failures with --continue → always fix failures before committing (--continue is for seeing all failures at once, not for bypassing them)

5. NEVER run full builds for every change → use Primary Validation (full builds including iOS are expensive, reserve for pre-release validation)

6. NEVER commit without conventional commit format → follow type(scope): description (enables automatic changelog generation and semantic versioning)

7. NEVER run dependency updates without validation → always test after updates (dependency changes can introduce breaking changes or regressions)

8. NEVER use stale dependencies → check ./gradlew dependencyUpdates regularly (security patches and bug fixes require timely updates)

Cross-References

Skills (by Category)

Build & Configuration

Testing

Development

Git Operations

Documents