{"id":917,"url":"https://github.com/nsomar/Swiftline","last_synced_at":"2025-08-06T13:31:54.819Z","repository":{"id":46308698,"uuid":"45925108","full_name":"nsomar/Swiftline","owner":"nsomar","description":"Swiftline is a set of tools to help you create command line applications.","archived":false,"fork":false,"pushed_at":"2021-10-31T17:25:21.000Z","size":2973,"stargazers_count":1199,"open_issues_count":18,"forks_count":98,"subscribers_count":20,"default_branch":"master","last_synced_at":"2024-10-30T00:31:35.066Z","etag":null,"topics":["cli","color","command-line","commandline","framework","swift"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nsomar.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-11-10T16:33:43.000Z","updated_at":"2024-10-25T00:26:16.000Z","dependencies_parsed_at":"2022-11-29T13:20:18.433Z","dependency_job_id":null,"html_url":"https://github.com/nsomar/Swiftline","commit_stats":null,"previous_names":["oarrabi/swiftline","swiftline/swiftline"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nsomar%2FSwiftline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nsomar%2FSwiftline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nsomar%2FSwiftline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nsomar%2FSwiftline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nsomar","download_url":"https://codeload.github.com/nsomar/Swiftline/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":228740058,"owners_count":17965180,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","color","command-line","commandline","framework","swift"],"created_at":"2024-01-05T20:15:34.603Z","updated_at":"2024-12-09T14:30:42.818Z","avatar_url":"https://github.com/nsomar.png","language":"Swift","readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"http://swiftline.github.io/img/intro-bg.svg\" width=\"400\" align=\"middle\"/\u003e\n\u003c/p\u003e\n\n[![Build Status](https://travis-ci.org/oarrabi/Swiftline.svg?branch=master)](https://travis-ci.org/oarrabi/Swiftline)\n[![Platform](https://img.shields.io/badge/platform-osx-lightgrey.svg)](https://travis-ci.org/Swiftline/Swiftline)\n[![Language: Swift](https://img.shields.io/badge/language-swift-orange.svg)](https://travis-ci.org/Swiftline/Swiftline)\n[![CocoaPods](https://img.shields.io/cocoapods/v/Swiftline.svg)](https://cocoapods.org/pods/Swiftline)\n[![Carthage](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![GITTER: join chat](https://img.shields.io/badge/GITTER-join%20chat-00D06F.svg)](https://gitter.im/Swiftline?utm_source=share-link\u0026utm_medium=link\u0026utm_campaign=share-link)\n[![GITTER: join chat](https://img.shields.io/badge/license-MIT-000000.svg)](https://github.com/Swiftline/Swiftline/blob/oarrabi/adding-env-and-args/LICENCE)\n\nSwiftline is a set of tools to help you create command line applications. Swiftline is inspired by [highline](https://github.com/JEG2/highline)\n\nSwiftline contains the following:\n\n- Colorize: Helps adding colors to strings written to the terminal\n- Ask , Choose  and agree: Easily create prompt for asking the user more info\n- Run: A quick way to run an external command and read its standard output and standard error.\n- Env: Read and write environment variables [ruby-flavored](http://ruby-doc.org/core-2.2.0/ENV.html)\n- Args: Parses command line arguments and return a hash of the passed flags\n\n## Contents\n[Usage](#usage)\n[Installation](#installation)\n[Examples](#examples)\n[Docs](http://swiftline.github.io/docs/index.html)\n[Tests](#tests)\n\n## Usage\n\n## Colorize 🎨\nColorize helps styling the strings before printing them to the terminal. You can change the text color, the text background and the text style.\nColorize works by extending `String` struct to add styling to it.\n\nTo change the text color, use either `string.f` or `string.foreground`:\n\n```swift\nprint(\"Red String\".f.Red)\nprint(\"Blue String\".foreground.Blue)\n```\n\nTo change the text background color, use either `string.b` or `string.background`:\n\n```swift\nprint(\"I have a white background\".b.White)\nprint(\"My background color is green\".background.Green)\n```\n\nTo change the text background style, use either `string.s` or `string.style`:\n\n```swift\nprint(\"I am a bold string\".s.Bold)\nprint(\"I have an underline\".style.Underline)\n```\n\nYou can compose foreground, background, and style:\n```swift\nprint(\"I am an underlined red on white string\".s.Underline.f.Red.b.White)\n```\n\n##  Ask, Choose, Agree ❓\nAsk, Choose and Agree are used to prompt the user for more information.\n\n### Ask\nAsk presents the user with a prompt and waits for the user input.\n```swift\nlet userName = ask(\"Enter user name?\")\n```\n`userName` will contain the name entered by the user\n\nAsk can be used to ask for value of Int, Double or Float types, to ask for an integer for example:\n\n```swift\nlet age = ask(\"How old are you?\", type: Int.self)\n```\nIf the user prints something thats not convertible to integer, a new prompt is displayed to him, this prompt will keep displaying until the user enters an Int:\n\n    How old are you?\n    None\n    You must enter a valid Integer.\n    ?  Error\n    You must enter a valid Integer.\n    ?  5\n    5\n\nValidations are added by calling `addInvalidCase` on `AskSettings`.\n\n```swift\nlet name = ask(\"Who are you?\") { settings in\n    settings.addInvalidCase(\"Snuffles is not allowed\") { value in\n        value.containsString(\"Snuffles\")\n    }\n}\n```\nIf the user entered `Snuffles` ask will keep displaying the invalid message passed to `addInvalidCase`\n\n    Who are you?\n    Snuffles\n    Snuffles is not allowed\n    ?  Snuffles\n    Snuffles is not allowed\n    ?  Snowball\n\n    Your name is Snowball\n\n`AskSettings.confirm` will ask the user to confirm his choice after entering it\n\n```swift\nlet name = ask(\"Who are you?\") { settings in\n    settings.confirm = true\n}\n```\n\nThe above will output:\n\n    Who are you?\n    Snuffles\n    Are you sure?  YES\n\n    Your name is Snuffles\n### Choose\nChoose is used to prompt the user to select an item between several possible items.\n\nTo display a choice of programming lanaugage for example:\n```swift\nlet choice = choose(\"Whats your favorite programming language? \",\n    choices: \"Swift\", \"Objective C\", \"Ruby\", \"Python\", \"Java :S\")\n```\n\nThis will print:\n\n    1. Swift\n    2. Objective C\n    3. Ruby\n    4. Python\n    5. Java :S\n    Whats your favorite programming language?\n\nThe user can either choose the numbers (1..5) or the item itself. If the user enters a wrong input. A prompt will keep showing until the user makes a correct choice\n\n    Whats your favorite programming language? JavaScript\n    You must choose one of [1, 2, 3, 4, 5, Swift, Objective C, Ruby, Python, Java :S].\n    ?  BBB\n    You must choose one of [1, 2, 3, 4, 5, Swift, Objective C, Ruby, Python, Java :S].\n    ?  Swift\n\n    You selected Swift, good choice!\n\nYou can customize the return value for each choice element. For example if you want to get an Int from the choice, you would do this\n\n```swift\nlet choice = choose(\"Whats your favorite programming language? \", type: Int.self) { settings in\n    settings.addChoice(\"Swift\") { 42 }\n    settings.addChoice(\"Objective C\") { 20 }\n}\n```\n\nThe number on the left can be changed to letters, here is how you could do that:\n\n```siwft\nlet choice = choose(\"Whats your favorite programming language? \", type: String.self) { settings in\n   //choice value will be set to GOOD\n   settings.addChoice(\"Swift\") { \"GOOD\" }\n\n   //choice value will be set to BAD\n   settings.addChoice(\"Java\") { \"BAD\" }\n\n   settings.index = .Letters\n   settings.indexSuffix = \" ----\u003e \"\n   }\n```\n\nThat will print:\n\n    a ----\u003e Swift\n    b ----\u003e Java\n    Whats your favorite programming language?\n\n### Agree\nAgree is used to ask a user for a Yes/No question. It returns a boolean representing the user input.\n\n```swift\nlet choice = agree(\"Are you sure you want to `rm -rf /` ?\")\n```\n\nIf the user enters any invalid input, agree will keep prompting him for a Yes/No question\n\n    Are you sure you want to `rm -rf /` ?  What!\n    Please enter \"yes\" or \"no\".\n    Are you sure you want to `rm -rf /` ?  Wait\n    Please enter \"yes\" or \"no\".\n    Are you sure you want to `rm -rf /` ?  No\n\n    You entered false\n\n## Run 🏃\nRun provides a quick, concise way to run an external command and read its standard output and standard error.\n\nTo execute a simple command you would do:\n\n```swift\nlet result = run(\"ls -all\")\nprint(result.stdout)\n```\n`result` type is `RunResults`, it contains:\n\n- `exitStatus`: The command exit status\n- `stdout`: The standard output for the command executed\n- `stderr`: The standard error for the command executed\n\nWhile `run(\"command\")` can split the arguments by spaces. Some times argument splitting is not trivial. If you have multiple argument to pass to the command to execute, you should use `run(command: String, args: String...)`. The above translates to:\n\n```swift\nlet result = run(\"ls\", args: \"-all\")\n```\n\nTo customize the run function, you can pass in a customization block:\n\n```swift\nlet result = run(\"ls -all\") { settings in\n    settings.dryRun = true\n    settings.echo = [.Stdout, .Stderr, .Command]\n    settings.interactive = false\n}\n```\n\n`settings` is an instance of RunSettings, which contains the following variables:\n\n- `settings.dryRun`: defaults to false. If false, the command is actually run. If true, the command is logged to the stdout paramter of result\n- `settings.echo`: Customize the message printed to stdout, `echo` can contain any of the following:\n    - `EchoSettings.Stdout`: The stdout returned from running the command will be printed to the terminal\n    - `EchoSettings.Stderr`: The stderr returned from running the command will be printed to the terminal\n    - `EchoSettings.Command`: The command executed will be printed to the terminal\n- `settings.interactive`: defaults to false. If set to true the command will be executed using `system` kernel function and only the exit status will be captured. If set to false, the command will be executed using `NSTask` and both stdout and stderr will be captured.\nSet `interactive` to true if you expect the launched command to ask input from the user through the stdin.\n\n`runWithoutCapture(\"command\")` is a quick way to run a command in interactive mode. The return value is the exit code of that command.\n\n## Env\nEnv is used to read and write the environment variables passed to the script\n```swift\n// Set enviroment variable\nEnv.set(\"key1\", \"value1\")\n\n// Get environment variable\nEnv.get(\"SomeKey\")\n\n// Clear all variables\nEnv.clear()\n\n// Get all keys and values\nEnv.keys()\nEnv.values()\n```\n\n## Args\nReturns the arguments passed to the script. For example when calling `script -f1 val1 -f2 val2 -- val3 val4`\n\n`Args.all ` returns an array of all the raw arguments, in this example it will be `[\"-f1\", \"val1\", \"-f2\", \"val2\", \"--\", \"val3\", \"val4\"`\n\n`Args.parsed ` returns a structure that contains a parsed map of arguments and an array of arguments, for this example:\n\n\n`Args.parsed.parameters` returns `[\"val3\", \"val4\"]`\n\n`Args.parsed.flags` returns a dictinary of flags `[\"f1\": \"val1\", \"f2\", \"val2\"]`\n\n`Args.parsed.command` returns the name of the executable itself `\"script\"`\n\n## Installation\nYou can install Swiftline using CocoaPods, carthage and Swift package manager\n\n### CocoaPods\n    use_frameworks!\n    pod 'Swiftline'\n\n### Carthage\n    github 'swiftline/swiftline'\n\n### Swift Package Manager\nAdd swiftline as dependency in your `Package.swift`\n\n```\n  import PackageDescription\n\n  let package = Package(name: \"YourPackage\",\n    dependencies: [\n      .Package(url: \"https://github.com/Swiftline/Swiftline.git\", majorVersion: 0, minor: 3),\n    ]\n  )\n```\n\n### CocoaPods + Rome plugin\nIf you want to use swiftline in a script you can use [Rome](https://github.com/neonichu/Rome) CocoaPods plugin. This plugin builds the framework from the pod file and place them in a Rome directory.\n\n    platform :osx, '10.10'\n    plugin 'cocoapods-rome'\n\n    pod 'Swiftline'\n\n### Manual\nTo install Swiftline manually, add `Pod/Swiftline` directory to your project.\n\n## Examples\nA list of examples can be found [here](https://github.com/oarrabi/Swiftline/tree/master/Examples)\n\n## Tests\nTests can be found [here](https://github.com/oarrabi/Swiftline/tree/master/SwiftlineTests). They can be normally run from the Xcode\n.\n\n## Documentation\nDocumentation can be found [here](http://swiftline.github.io/docs/index.html)\n\n## Future Improvement\n- Add gather (from [highline](https://github.com/JEG2/highline)) to ask function\n- Figure out a way to eliminate the need of `interactive`\n- Add Glob handling\n- Better documentation\n\n## Credits\nDaniel Beere for creating the logo [@DanielBeere](https://twitter.com/DanielBeere) check out [danielbeere on dribble](https://dribbble.com/danielbeere)\nOmar Abdelhafith current project maintainer [@ifnottrue](https://twitter.com/ifnottrue)\n","funding_links":[],"categories":["Command Line","Libs","Command Line [🔝](#readme)"],"sub_categories":["Linter","Command Line","Other free courses"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnsomar%2FSwiftline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnsomar%2FSwiftline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnsomar%2FSwiftline/lists"}