Skip to main content

Quickstart

Get up and running with Argus in minutes. This guide walks you through creating your first CLI tool.

Your First CLI​

Let's build a simple file processor that demonstrates Argus's core features:

my_tool.c
#include <argus.h>
#include <stdio.h>

// Define your CLI interface declaratively
ARGUS_OPTIONS(
    options,
    HELP_OPTION(),                    // Automatic --help/-h
    VERSION_OPTION(),                 // Automatic --version/-V
    
    OPTION_FLAG('v', "verbose", 
        HELP("Enable verbose output")),
    
    OPTION_STRING('o', "output", 
        HELP("Output file"), 
        DEFAULT("result.txt")),
    
    OPTION_INT('c', "count", 
        HELP("Number of iterations"), 
        DEFAULT(1),
        VALIDATOR(V_RANGE(1, 100))),   // Built-in validation
    
    POSITIONAL_STRING("input", 
        HELP("Input file to process")),
)

int main(int argc, char **argv)
{
    // Initialize with program info
    argus_t argus = argus_init(options, "my_tool", "1.0.0");
    argus.description = "A simple file processing tool";
    
    // Parse arguments - handles errors automatically
    if (argus_parse(&argus, argc, argv) != ARGUS_SUCCESS) {
        return 1;
    }
    
    // Access parsed values with type safety
    const char *input = argus_get(&argus, "input").as_string;
    const char *output = argus_get(&argus, "output").as_string;
    int count = argus_get(&argus, "count").as_int;
    bool verbose = argus_get(&argus, "verbose").as_bool;
    
    // Your application logic
    if (verbose) {
        printf("Processing %s -> %s (%d times)\n", input, output, count);
    }
    
    printf("File processed successfully!\n");
    
    // Cleanup
    argus_free(&argus);
    return 0;
}

Build and Test​

# Development build (recommended during development)
gcc my_tool.c -o my_tool -largus
./my_tool --help    # See auto-generated help
./my_tool input.txt # Run your tool

# Production build (skip validation for better performance)
gcc -DARGUS_RELEASE my_tool.c -o my_tool-prod -largus
Production Note

Use ARGUS_RELEASE only in production after thorough testing. It disables option structure validation for faster startup time.

What You Get For Free​

Automatic Help Generation​

$ ./my_tool --help
my_tool v1.0.0

A simple file processing tool

Usage: my_tool [OPTIONS] <input>

Arguments:
  <input>                - Input file to process

Options:
  -h, --help             - Display this help message (exit)
  -V, --version          - Display version information (exit)
  -v, --verbose          - Enable verbose output
  -o, --output <STR>     - Output file (default: "result.txt")
  -c, --count <1-100>    - Number of iterations (default: 1)

Input Validation​

$ ./my_tool --count 150 input.txt
my_tool: Value 150 is out of range [1, 100]

Flexible Input Formats​

All equivalent:

./my_tool --output=file.txt --count=5 input.txt
./my_tool -o file.txt -c 5 input.txt  
./my_tool -ofile.txt -c5 input.txt

Key Concepts​

Options are named arguments with -- or - prefix:

// Flag (boolean, no value needed)
OPTION_FLAG('v', "verbose", HELP("Enable verbose mode"))

// String option with default value
OPTION_STRING('o', "output", HELP("Output file"), DEFAULT("out.txt"))

// Integer with validation
OPTION_INT('p', "port", HELP("Port number"), 
           VALIDATOR(V_RANGE(1, 65535)))

Next Steps​

Add Subcommands​

Transform your tool into a multi-command interface like git or docker:

// Define subcommand options
ARGUS_OPTIONS(process_options,
    HELP_OPTION(),
    OPTION_FLAG('f', "force", HELP("Force processing")),
    POSITIONAL_STRING("file", HELP("File to process")),
)

// Add to main options
ARGUS_OPTIONS(options,
    HELP_OPTION(),
    VERSION_OPTION(),
    SUBCOMMAND("process", process_options, 
               HELP("Process files"), 
               ACTION(process_command)),
)

Handle Collections​

Work with multiple values and key-value pairs:

// Array of strings: --tags=web,api,backend
OPTION_ARRAY_STRING('t', "tags", HELP("Tags"))

// Key-value map: --env=DEBUG=1,LOG_LEVEL=info  
OPTION_MAP_STRING('e', "env", HELP("Environment variables"))

🔧 Advanced Features​

  • Environment Variables: Auto-load from env vars
  • Custom Handlers: Parse complex data types
  • Nested Commands: Multi-level command hierarchies
  • Dependency Management: Require/conflict between options

Common Patterns​

ARGUS_OPTIONS(options,
    HELP_OPTION(),
    VERSION_OPTION(),
    OPTION_FLAG('v', "verbose", HELP("Verbose output")),
    OPTION_STRING('o', "output", HELP("Output file")),
    POSITIONAL_STRING("input", HELP("Input file")),
)

Perfect for file processors, converters, simple tools.

tip

Every Argus program automatically gets --help and proper error messages. Focus on your application logic, not argument parsing!