Skip to content
devflow

Quickstart

1. Initialize a project

Section titled “1. Initialize a project”
Terminal window
cd ~/my-project
devflow init

The interactive wizard:

  • detects your VCS (Git or Jujutsu) and primary/default workspace,
  • configures the worktree path and copy policy (every workspace gets its own directory),
  • detects Copy-on-Write support on your filesystem,
  • optionally adds a first service (PostgreSQL, ClickHouse, MySQL, Redis, …),
  • installs the VCS hooks and offers shell integration.

Pass a path (devflow init myapp) to create and initialize a new directory. Git worktrees (or jj workspaces) are always used for additional workspaces in interactive and non-interactive modes.

This writes a .devflow.yml you commit with the repo:

services:
  - name: app-db
    type: local
    service_type: postgres
    default: true
    local:
      image: postgres:17


worktree:
  path_template: "../{repo}.{workspace}"

2. Create an isolated workspace

Section titled “2. Create an isolated workspace”
Terminal window
devflow switch -c feature/auth

One command does all of it:

  • creates the Git ref and linked worktree (or jj workspace) from the current context or --from <parent>,
  • creates a worktree at ../my-project.feature_auth_fc659bd73585 and copies configured files into it,
  • clones the parent’s database into a new isolated service workspace (CoW — near-instant),
  • runs your post-create / post-switch hooks (write .env.local, run migrations, …),
  • cds your shell into the worktree (with shell integration installed).

3. Inspect the environment

Section titled “3. Inspect the environment”
Terminal window
devflow status          # current workspace, services, connection info
devflow list            # parent tree with paths, services, processes, and health
devflow --json list     # stable versioned tree document for automation

4. Use the connection info

Section titled “4. Use the connection info”
Terminal window
devflow connection feature/auth                # URI
devflow connection feature/auth --format env   # KEY=value lines
devflow connection feature/auth --format json  # machine-readable

Most projects don’t call this manually — a hook writes .env.local on every switch:

hooks:
  post-switch:
    env:
      action:
        type: write-env
        path: .env.local
        vars:
          DATABASE_URL: "{{ service['app-db'].url }}"

5. Clean up

Section titled “5. Clean up”
Terminal window
devflow switch --template       # move back to the configured default workspace
devflow remove feature/auth

Preflight always protects the default/current workspace, so move to another workspace before removing the one you finished; --force does not override that protection. A dirty worktree is also refused unless explicitly forced. Removal hooks run while the directory exists; processes and services are cleaned up before the worktree and VCS ref are deleted.

Where to go next

Section titled “Where to go next”