Quickstart

This quickstart takes you from a fresh install to a working ~/Code tree. You'll log in, let Bowline observe your workspace, approve the device, and run a project without copying env files or rebuilding worktrees by hand.

This guide assumes you've already installed Bowline.

1. Set up this machine

Start by pointing Bowline at the folder you want as your workspace root. Most people use ~/Code.

bowline setup --root ~/Code

First contact is deliberately safe. Bowline observes your existing workspace without changing it, then reports concrete state. A few things to know:

• If ~/Code already exists, Bowline adopts it as your workspace root and reads what's there. It never silently moves projects from other folders into ~/Code.
• If the root doesn't exist, Bowline can create that empty root or adopt an existing workspace there.
• Bowline handles account login as part of setup when this machine still needs authentication.

2. Approve the device

Logging in proves your account identity. It does not, by itself, hand a new machine the keys to decrypt your workspace; that's a separate, deliberate step.

On your very first device, Bowline establishes trust during login. On any later device, Bowline raises a Device Approval Request that an already-authorized device or a Recovery Key grants. Check pending requests at any time:

bowline status --root ~/Code

When a request is pending, both devices show a short matching code so you can confirm you're approving the right machine. Approve it from a trusted device:

bowline device approve --root ~/Code --code <matching-code>

3. Watch the workspace materialize

Once the device is trusted, Bowline discovers your ~/Code namespace and automatically materializes ordinary files. A path is reported ready only when a normal read returns the intended bytes. Select a project during setup to make that project usable first; the rest continues in the background.

bowline status --root ~/Code
ls ~/Code

Use --project <path> when you want a narrower project view, or --watch to stream changes as they happen.

4. Open a project and run it

Now work the way you always do. Change into a project after status reports it ready and run it. Bowline restores dependencies, applies any Setup Recipe, and materializes the project's env files where your tools expect them.

cd ~/Code/acme/web
pnpm dev

That's the whole promise: cd ~/Code/acme/web && pnpm dev works here exactly like it does on your other machines. The code, the dependencies, and the .env are just there.

5. See what needs your attention

When something needs your attention, Bowline tells you what to do next instead of making you guess. Check status for your current state:

bowline status --root ~/Code

You can also open the terminal UI for an interactive view of workspace health, pending approvals, and conflicts:

bowline tui --root ~/Code

Next steps

• Add a machine: get the same tree on a second device.
• Connect remote hosts: bring up a remote agent host over SSH.
• Workspace model: understand snapshots, heads, and overlays.
• Status and health: what healthy, attention, and limited mean.