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. Log in and choose a workspace root

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

bowline login --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 mounts 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 mount an existing workspace there.
• --headless runs login without opening a browser, which is useful on remote hosts.

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

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 approve

3. Watch the workspace appear

Once the device is trusted, your whole ~/Code tree becomes visible before every byte is local. Bowline shows the structure immediately and hydrates file contents the moment you touch a project.

bowline status
ls ~/Code

bowline status defaults to the current project when you're inside one, with a compact summary of the whole workspace when another project needs attention. Run it with --workspace to see the whole tree, 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 and run it. Bowline hydrates the project on touch, 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. Explore safe next actions

When something needs your attention, Bowline tells you what to do next instead of making you guess. Ask for the safe next actions for your current state:

bowline actions

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

bowline tui

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.