Skip to content
Bynk

Start a new project with `bynk new`

Goal: go from nothing to a running service in three commands — no manifest to hand-write, no layout to remember, no blank file to stare at.

Terminal window
bynk new hello
cd hello
bynk dev          # already serving on http://localhost:8787

bynk new scaffolds a complete, runnable project: a bynk.toml, a .gitignore, and a starter HTTP service under src/. The scaffold is chosen so bynk dev serves it unmodified — that end-to-end loop is the whole point. bynk new is the first step of the driver arc is my machine ready (bynk doctor) → make me something (bynk new) → run it (bynk dev).

bynk new needs no toolchain. Unlike dev, it only writes files — it shells nothing, compiles nothing, and reads no network. It works before bynkc, Node, or wrangler are installed, which is exactly why it can be your very first command. (Run bynk doctor once you want to build or serve.)

What it writes

Section titled “What it writes”
hello/
├── bynk.toml            # [project] name/version + [paths] src/tests
├── .gitignore           # /.bynk — the build dir `bynk dev` writes
└── src/
    └── hello.bynk       # context hello — a GET "/" HTTP service

The starter is a minimal but real service — the single-file analogue of the hello-world example:

context hello


consumes bynk { Logger }


service api from http {
  on GET("/") by v: Visitor () -> Effect[HttpResult[String]] given Logger {
    let _ <- Logger.info("hello from hello")
    Ok("Hello from hello!")
  }
}

That is everything you need to compile and serve. From here, edit src/hello.bynk and let bynk dev reload it.

Naming the project

Section titled “Naming the project”

By default the project takes its name from the target directory’s final component, and that name is used for both the [project] name and the starter’s context — so the name must be a legal Bynk identifier: a letter followed by letters, digits, or underscores (no dashes or dots).

A directory whose name isn’t a legal identifier (my-app, 2048) is refused with a fix-it rather than silently mangled — pass --name to choose the identifier:

Terminal window
bynk new my-app --name myapp     # directory my-app/, project + context `myapp`

Choosing the location

Section titled “Choosing the location”

PATH is the directory to create:

Terminal window
bynk new hello          # create ./hello
bynk new ./apps/hello   # create ./apps/hello (parent dirs are created)

bynk new never overwrites. If the target already exists and isn’t empty, it fails before writing anything and touches nothing. An empty directory is fine (the common “I just mkdired it” case) — and VCS/OS cruft like .git or .DS_Store doesn’t count as non-empty, so a freshly git inited directory still works.

bynk new doesn’t run git init or write anything outside the project — the scaffold drops cleanly into an existing repository, and git init is one command away if you want a new one.

Next steps

Section titled “Next steps”