Swiftpack.co - Package - yonaskolb/Beak

Beak 🐦

SPM Linux Git Version Build Status license

Peck into your Swift files from the command line

Beak can take a standard Swift file and then list and run any public global functions in it via a command line interface.

This is useful for scripting and for make-like files written in Swift. You can replace make or rake files with code written in Swift!

An example Swift script:

// This links https://github.com/kylef/PathKit as a dependency
// beak: kylef/PathKit @ 1.0.0

import PathKit // from the dependency listed above
import Foundation

/// Releases the product
/// - Parameters:
///   - version: the version to release
public func release(version: String) throws {
    // implementation here
    print("version \(version) released!")

/// Installs the product
public func install() throws {
    // implementation here
$ beak list
    release: Releases the product
    install: Installs the product
$ beak run release --version 1.2.0
  version 1.2.0 released!

How does it work?

Beak 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.

Beak can parse special comments at the top of your script so it can pull in dependencies via the Swift Package Manager.

By 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. This repo itself has a Beak file for running build scripts.


Make sure Xcode 10.2+ is installed first.

Mint 🌱

$ mint install yonaskolb/beak


$ brew tap yonaskolb/Beak https://github.com/yonaskolb/Beak.git
$ brew install Beak

Swift PM and Beak 🐦

This 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!

$ git clone https://github.com/yonaskolb/Beak.git
$ cd Beak
$ swift run beak run install


List functions:

This shows all the functions that can be run

$ beak list

  release: Releases the product
  install: Installs the product

Run a function:

This runs a specific function with parameters. Note that any top level expressions in the swift file will also be run before this function.

$ beak run release --version 1.2.0
version 1.2.0 released

Run the swift file

It's also possible to just run the whole script instead of a specific function

$ beak run

Edit the swift file

This generates and opens an Xcode project with all dependencies linked, which is useful for code completion if you have defined any dependencies. The command line will prompt you to type c to commit any changes you made in Xcode back to the original file

$ beak edit
generating project

You can always use --help to get more information about a command or a function. This will use information from the doc comments.


For 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.

Functions 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


Any parameters without default values will be required.

Param 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.

Function parameters without labels will can be used with positional arguments:

public func release(_ version: String) { }
beak run release 1.2.0


Sometimes 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:

// beak: {repo} {library} {library} ... @ {version}`

where items in {} are:

  • 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
  • library: a space delimited list of libraries to include from this package. This defaults to the repo name, which is usually what you want.
  • 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
    • branch:develop or .branch("develop")
    • revision:ab794ebb or .revision("ab794ebb")
    • exact:1.2.0 or .exact("1.2.0")
    • .upToNextMajor(from: "1.2.0")
    • .upToNextMinor(from: "1.2.3")

Some examples:

// beak: JohnSundell/ShellOut @ 2.0.0
// beak: kylef/PathKit @ upToNextMajor:0.9.0
// beak: apple/swift-package-manager Utility @ branch:master

import Foundation
import Pathkit
import ShellOut
import Utility

You can use beak edit to get code completion for these imported dependencies.


If 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.


#!/usr/bin/env beak --path

public func foo() {
    print("hello foo")

public func bar() {
    print("hello bar")
$ chmod a+x tasks.swift
$ ./tasks.swift run foo
  hello foo

If you then place this file into usr/local/bin you could run this file from anywhere:

$ cp tasks.swift /usr/local/bin/tasks
$ tasks run bar
  hello bar

To automatically insert the run option, you can change your shebang to #!/usr/bin/env beak run --path.



Beak is licensed under the MIT license. See LICENSE for more info.


Stars: 528

Used By

Total: 1


0.5.1 - 2019-04-06 10:53:37


  • Fixed homebrew installations @yonaskolb


0.5.0 - 2019-03-30 06:15:18


  • Fixed installation when building in Swift 5 #44 yonaskolb


  • Updated to Swift 5 and dropped Swift 4.2 #44 @yonaskolb


0.4.0 - 2018-06-03 05:15:35


  • Added support for reading from input in beak files (stdin) #29 @jakeheis
  • Added support for cancellation (SIGINT forwarding) #29 @jakeheis
  • Added support for passing nil to optional parameters #29 @jakeheis
  • Added Linux support #33 @yonaskolb


  • Fixed running on case sensitive file systems #27 @tflhyl
  • Fixed homebrew installations #32 @yonaskolb


  • Changed beak cache path from ~/Documents/beak/builds to ~/.beak/builds #30 @tflhyl


  • Replaced SwiftPM and SwiftShell with SwiftCLI #29 @jakeheis
  • Created seperate BeakCLI target #31 @yonaskolb


0.3.5 - 2018-04-16 08:15:06


  • Fix parsed docs not matching to the correct functions in some cases #21


0.3.4 - 2018-03-31 05:17:45


  • Fixed swift package manager dependency targeting so that BeakCore can be used as a dependency #19


  • Updated PathKit, SWXMLHash, swift-package-manager, and SwiftShell


0.3.3 - 2018-03-02 10:42:04


  • Fixed a installation issue due to a dependency on a Swift PM commit that no longer existed #17


0.3.2 - 2018-02-24 11:17:40


  • Fixed the parsing of files with anonymous functions within the public functions #15


0.3.1 - 2018-01-06 10:30:12


  • Added shebang documentation #!/usr/bin/env beak --path


  • Fixed dependency declarations not being parsed if they didn't start on the first line, for example if you have a shebang


0.3.0 - 2018-01-05 14:05:07


  • added homebrew formula
  • added automatic copying back of edited script from Xcode in beak edit
  • added ability to simply run file as a script without specifying a function


  • moved --path parameter before subcommands


0.2.0 - 2018-01-04 07:03:36


  • Unnamed params are now parsed to positional arguments
  • Added beak edit command
  • Added beak --version
  • Added release to beak.swift


  • Improved error logging
  • Show param defaults in run --help
  • Removed unused dependencies
  • Use dynamic argument lookup from Swift PM PR
  • Don't write build files if unchanged


  • Fixed build path of beak files
  • Fixed build errors when multiple dependency libraries are imported
  • Fixed install beak function


0.1.0 - 2017-12-31 14:43:05

Initial release