Argos

Type-safe command-line argument parsing library for Kotlin Multiplatform

What is Argos?¶

Argos is a modern command-line argument parsing library designed specifically for Kotlin Multiplatform projects. It provides a type-safe, declarative DSL for defining command-line interfaces while supporting advanced features like subcommands, validation rules, and automatic help generation.

Key Features¶

• 🎯 Type Safety: Leverage Kotlin's type system for compile-time argument validation
• 🚀 Easy DSL: Intuitive domain-specific language that reads like natural language
• 🔧 Zero Dependencies: No external runtime dependencies - completely self-contained
• 🌍 Multiplatform: Native support for JVM, Linux Native (x64/ARM64), and Windows
• ⚡ Performance: Efficient parsing with minimal memory overhead
• 🎨 Rich Terminal Support: ANSI colors, plain text, and Markdown output formats
• 🔄 Shell Completions: Generate completion scripts for Bash, Zsh, and Fish
• 📚 Comprehensive Validation: Built-in constraints, custom validation, and conditional requirements
• 🎛️ Subcommands: Full support for git-style subcommand interfaces
• 📝 Automatic Help: Beautiful, customizable help text generation

Quick Example¶

Here's a simple example that demonstrates Argos's key features:

import onl.ycode.argos.Arguments
import onl.ycode.argos.parse

enum class LogLevel { DEBUG, INFO, WARN, ERROR }

class MyApp : Arguments(
    appName = "myapp",
    appDescription = "A sample application built with Argos"
) {
    // Basic options with type conversion
    val verbose by option("--verbose", "-v").bool().default(false)
        .help("Enable verbose logging")
    val level by option("--level", "-l").enum<LogLevel>().default(LogLevel.INFO)
    val count by option("--count", "-c").int().default(1)
        .validate("Count must be at least 1") { it >= 1 }

    // Positional arguments (list must be last)
    val outputFile by positional()
    val inputFiles by positional().list()

    // Conditional requirements
    val backup by option("--backup").requireIfAnyPresent(::outputFile)

    // Built-in help
    val help by help()
}

fun main(args: Array<String>) {
    val app = MyApp()

    app.parse(args,
        onSuccess = {
            println("Verbose: ${app.verbose}")
            println("Level: ${app.level}")
            println("Count: ${app.count}")
            println("Input files: ${app.inputFiles}")
            println("Output file: ${app.outputFile}")
        },
        onError = { error, _ ->
            println("Error: ${error.message}")
            kotlin.system.exitProcess(1)
        }
    )
}

Running this application:

# Show help
./myapp --help

# Basic usage
./myapp --verbose --level DEBUG --count 3 input1.txt input2.txt output.txt

# Short options
./myapp -v -l ERROR -c 5 *.txt result.txt

Why Choose Argos?¶

Compared to Other Libraries¶

Perfect For¶

• ✅ Kotlin Multiplatform Projects: First-class multiplatform support
• ✅ Type-Safe CLIs: Compile-time argument validation
• ✅ Complex Applications: Advanced validation and subcommands
• ✅ Distribution: Zero-dependency, single-file deployment
• ✅ Developer Experience: IntelliJ IDEA integration and auto-completion

Getting Started¶

Ready to build your first CLI with Argos? Check out our comprehensive guides:

Community and Support¶

• 🐛 Issues: GitHub Issues for bug reports and feature requests
• 💡 Discussions: GitHub Discussions for questions and ideas
• 📖 Documentation: You're reading it! Comprehensive guides and examples
• 🔄 Updates: Follow releases on GitHub

License¶

Argos is open source software released under the MIT License.