Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A versatile, modular library for building command-line apps.

Background / Features

While developing the command-line interface to, I really wanted a simple library to build a high quality, easy-to-use tool with modest styling requirements. I needed to be able to:

  1. Parse command-line arguments in a type-safe way
  2. Compose multiple small, easy-to-understand commands
  3. Output colored text
  4. Output tables of dynamic data with consistent widths
  5. Ship a fully self-contained binary (not an app bundle)
  6. Testable

Using Swift wasn't a viable option because of its lack of support for static libraries and ABI instability. Again, the goal here was to ship a single executable.

To my dismay, there weren't simply any options. After crying a little on the inside, I decided that I wouldn't let this happen to anyone, ever again. And here we are.


The main header YDCommandKit.h integrates with Xcode's Quick Help. After importing YDCommandKit into your project, you should be able navigate through the documentation when referencing the YD namespace.

The headers are really helpful, too. The main ones to pay attention to are:

You can check out the source to emporter-cli to see every feature within YDCommandKit used extensively. Each command is implemented in its own file and should be pretty easy to follow. It even has a custom class for drawing terminal windows using the APIs from this package. A great deal of effort went into making a minimal API without too many assumptions with how it should be used.


Argument parsing

int main(int argc, const char * argv[]) {
   int result = 0;
   @autoreleasepool {
      result = [[MainCommand new] run];
   return result;

@interface MainCommand : YDCommand @end

@implementation MainCommand : NSObject {
   NSString *_foo;

- (instancetype)init {
   self = [super init];
   if (self == nil) return nil;

   self.usage = @"[OPTIONS] [ARGS...]";
   self.variables = @[[YDCommandVariable string:&_foo name:@"--foo" usage:@"Wow, type safety!"]];
   self.allowsMultipleArguments = YES;

   return self;

- (YDCommandReturnCode)executeWithArguments:(NSArray<NSString*>*)args {
   [YDStandardOut appendFormat:@"Foo = %@; args = %@\n", _foo, args];
   return YDCommandReturnCodeOK;

app --foo bar a b c would output Foo = bar; args = (a,b,c)

It's worth noting that --foo=bar is perfectly acceptable, and you can define aliases for variables so that -f bar would work, too. It'd look something like this:

[[YDCommandVariable string:&_foo name:@"--foo" usage:@"Wow, type safety!"] variableWithAlias:@"-f"]

Colored output

YDCommandOutputStyle redForeground = YDCommandOutputStyleWithForegroundColor(YDCommandOutputStyleRedColor);
YDCommandOutputStyle blueBackground = YDCommandOutputStyleWithBackgroundColor(YDCommandOutputStyleBlueColor);

[YDStandardOut applyStyle:redForeground withinBlock:^(id<YDCommandOutputWriter> output) { 
   [output appendString:@"I'm red "];

   // Style blocks are nestable and support inheritance
   [output applyStyle:blueBackground withinBlock:^(id<YDCommandOutputWriter> output) {
      [output appendString:@"and blue"];

You don't have to nest blocks whenever you have "complex" styles. YDCommandOutputStyleMake lets you define a foreground/background color, with text attributes, which can be applied in one block.


The "right" way

  1. Add YDCommandKit.xcodeproj to your Xcode project or workspace
  2. Add a dependency to your target (Build Phases > Target Dependencies) to libYDCommandKit.a
  3. Link libEmporterKit.a to your target (Build Phases > Link Binary With Libraries)
  4. Update your project build settings
    1. Add YDCommandKit/** to Header Search Paths
    2. Add -lstdc++ to Other Linker Flags
  5. #import "YDCommandKit.h" and make something awesome!

The "ain't nobody got time for that" way

Add all files from YDCommandKit/ to your target.

CocoaPods / Carthage

I'm not a CocoaPods / Carthage user, but feel free to make a pull request to add support for either.


BSD 3 Clause. See LICENSE.

(c) 2019 Young Dynasty


A modern command-line library for macOS







No releases published


No packages published