{"id":15624652,"url":"https://github.com/yonaskolb/beak","last_synced_at":"2025-04-05T04:14:13.408Z","repository":{"id":63921256,"uuid":"115804874","full_name":"yonaskolb/Beak","owner":"yonaskolb","description":"A command line interface for your Swift scripts","archived":false,"fork":false,"pushed_at":"2020-04-28T10:35:21.000Z","size":114,"stargazers_count":585,"open_issues_count":12,"forks_count":19,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-29T03:11:12.434Z","etag":null,"topics":["cli","make","package-manager","script","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/yonaskolb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-30T15:18:07.000Z","updated_at":"2025-02-24T13:20:54.000Z","dependencies_parsed_at":"2023-01-14T14:15:40.218Z","dependency_job_id":null,"html_url":"https://github.com/yonaskolb/Beak","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yonaskolb%2FBeak","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yonaskolb%2FBeak/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yonaskolb%2FBeak/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yonaskolb%2FBeak/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yonaskolb","download_url":"https://codeload.github.com/yonaskolb/Beak/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247284953,"owners_count":20913704,"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","make","package-manager","script","swift"],"created_at":"2024-10-03T10:00:45.598Z","updated_at":"2025-04-05T04:14:13.380Z","avatar_url":"https://github.com/yonaskolb.png","language":"Swift","readme":"# Beak 🐦\n\n[![SPM](https://img.shields.io/badge/Swift_PM-compatible-brightgreen.svg?style=for-the-badge)](https://swift.org/package-manager)\n![Linux](https://img.shields.io/badge/Platforms-macOS_Linux-blue.svg?style=for-the-badge)\n[![Git Version](https://img.shields.io/github/release/yonaskolb/Beak.svg?style=for-the-badge)](https://github.com/yonaskolb/Beak/releases)\n[![Build Status](https://img.shields.io/circleci/project/github/yonaskolb/Beak.svg?style=for-the-badge)](https://circleci.com/gh/yonaskolb/Beak)\n[![license](https://img.shields.io/github/license/yonaskolb/Beak.svg?style=for-the-badge)](https://github.com/yonaskolb/Beak/blob/master/LICENSE)\n\n*Peck into your Swift files from the command line*\n\nBeak can take a standard Swift file and then list and run any public global functions in it via a command line interface.\n\nThis is useful for scripting and for make-like files written in Swift. You can replace `make` or `rake` files with code written in Swift!\n\nAn example Swift script:\n\n```swift\n// This links https://github.com/kylef/PathKit as a dependency\n// beak: kylef/PathKit @ 1.0.0\n\nimport PathKit // from the dependency listed above\nimport Foundation\n\n/// Releases the product\n/// - Parameters:\n///   - version: the version to release\npublic func release(version: String) throws {\n    // implementation here\n    print(\"version \\(version) released!\")\n}\n\n/// Installs the product\npublic func install() throws {\n    // implementation here\n    print(\"installed\")\n}\n```\n```sh\n$ beak list\n    release: Releases the product\n    install: Installs the product\n$ beak run release --version 1.2.0\n  version 1.2.0 released!\n```\n\n## How does it work?\nBeak analyzes your Swift file via SourceKit and finds all public and global functions. It uses information about the function and parameter names, types and default values to build up a command line interface. It also uses standard comment docs to build up descriptive help.\n\nBeak can parse special comments at the top of your script so it can pull in dependencies via the Swift Package Manager.\n\nBy default Beak looks for a file called `beak.swift` in your current directory, otherwise you can pass a path to a different swift file with `--path`.\nThis repo itself has a Beak file for running build scripts.\n\n## Installing\nMake sure Xcode 10.2+ is installed first.\n\n### [Mint](https://github.com/yonaskolb/mint) 🌱\n```sh\n$ mint install yonaskolb/beak\n```\n\n### Homebrew\n\n```\n$ brew tap yonaskolb/Beak https://github.com/yonaskolb/Beak.git\n$ brew install Beak\n```\n\n### Swift PM and Beak 🐦\nThis uses Swift PM to build and run **beak** from this repo, which then runs the `install` function inside the `Beak.swift` file also incuded in this repo. So meta!\n\n```sh\n$ git clone https://github.com/yonaskolb/Beak.git\n$ cd Beak\n$ swift run beak run install\n```\n\n## Usage\n\n#### List functions:\n\nThis shows all the functions that can be run\n\n```sh\n$ beak list\n\n  release: Releases the product\n  install: Installs the product\n\n```\n\n#### Run a function:\nThis runs a specific function with parameters.\nNote that any top level expressions in the swift file will also be run before this function.\n\n```sh\n$ beak run release --version 1.2.0\nversion 1.2.0 released\n```\n\n#### Run the swift file\nIt's also possible to just run the whole script instead of a specific function\n\n```sh\n$ beak run\n```\n\n#### Edit the swift file\nThis generates and opens an Xcode project with all dependencies linked, which is useful for code completion if you have defined any dependencies.\nThe command line will prompt you to type `c` to commit any changes you made in Xcode back to the original file\n\n```sh\n$ beak edit\ngenerating project\n```\n\nYou can always use `--help` to get more information about a command or a function. This will use information from the doc comments.\n\n### Functions\nFor function to be accessible they must be global and declared public. Any non-public functions can be as helper functions, but won't be seen by Beak.\n\nFunctions can be throwing, with any errors thrown printed using `CustomStringConvertible`. This makes it easy to fail your tasks. For now you must include an `import Foundation` in your script to have throwing functions\n\n### Parameters\nAny parameters without default values will be required.\n\nParam types of `Int`, `Bool`, and `String` are natively supported. All other types will be passed exactly as they are as raw values, so if it compiles you can pass in anything, for example an enum value`--buildType .debug`.\n\nFunction parameters without labels will can be used with positional arguments:\n\n```swift\npublic func release(_ version: String) { }\n```\n```sh\nbeak run release 1.2.0\n```\n\n### Dependencies\nSometimes it's useful to be able to pull in other Swift packages as dependencies to use in your script. This can be done by adding some special comments at the top of your file. It must take the form:\n\n```\n// beak: {repo} {library} {library} ... @ {version}`\n```\nwhere items in `{}` are:\n\n- **repo**: is the git repo where a Swift package resides. This can take a short form of `user/repo` or an extended form `https://github.com/user/repo.git`\n- **library**: a space delimited list of libraries to include from this package. This defaults to the repo name, which is usually what you want.\n- **version**: the version of this package to include. This can either be a simple version string, or any of the types allowed by the Swift Package Manager `Requirement` static members eg\n\t- `branch:develop` or `.branch(\"develop\")`\n\t- `revision:ab794ebb` or `.revision(\"ab794ebb\")`\n\t- `exact:1.2.0` or `.exact(\"1.2.0\")`\n\t- `.upToNextMajor(from: \"1.2.0\")`\n\t- `.upToNextMinor(from: \"1.2.3\")`\n\nSome examples:\n\n```\n// beak: JohnSundell/ShellOut @ 2.0.0\n// beak: kylef/PathKit @ upToNextMajor:0.9.0\n// beak: apple/swift-package-manager Utility @ branch:master\n\nimport Foundation\nimport Pathkit\nimport ShellOut\nimport Utility\n```\n\nYou can use `beak edit` to get code completion for these imported dependencies.\n\n## Shebang\nIf you put a beak shebang at the top of your swift file and then run `chmod a+x beak.swift` on it to make it executable, you will be able to execute it directly without calling beak.\n\n**tasks.swift**\n\n```swift\n#!/usr/bin/env beak --path\n\npublic func foo() {\n    print(\"hello foo\")\n}\n\npublic func bar() {\n    print(\"hello bar\")\n}\n```\n\n```sh\n$ chmod a+x tasks.swift\n$ ./tasks.swift run foo\n  hello foo\n```\n\nIf you then place this file into `usr/local/bin` you could run this file from anywhere:\n\n```\n$ cp tasks.swift /usr/local/bin/tasks\n$ tasks run bar\n  hello bar\n```\n\nTo automatically insert the `run` option, you can change your shebang to `#!/usr/bin/env beak run --path`. \n\n## Alternatives\n\n* [swift sh](https://github.com/mxcl/swift-sh)\n* [Marathon](https://github.com/JohnSundell/Marathon)\n\n## License\n\nBeak is licensed under the MIT license. See [LICENSE](LICENSE) for more info.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyonaskolb%2Fbeak","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyonaskolb%2Fbeak","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyonaskolb%2Fbeak/lists"}