make build && make install-local   # installs to ~/.local/bin/flow
flow setup run linux-work           # bootstrap a machine
flow dotfiles link                  # symlink dotfiles
flow dev create api -i tm0/node     # spin up a dev container
flow dev attach api                 # attach via tmux

Commands

# Dotfiles
flow dotfiles link [--profile NAME] [--dry-run] [--skip PKG...]
flow dotfiles unlink [PACKAGES...] [--dry-run]
flow dotfiles status [PACKAGES...]
flow dotfiles edit PACKAGE [--no-commit]   # pull -> $EDITOR -> commit+push

# Dotfiles repos (unified: dotfiles repo + module repos)
flow dotfiles repos list
flow dotfiles repos status [--repo NAME]
flow dotfiles repos pull [--repo NAME] [--dry-run]
flow dotfiles repos push [--repo NAME] [--dry-run]

# Packages
flow packages install [NAMES...] [--profile NAME] [--dry-run]
flow packages remove NAMES... [--dry-run]
flow packages list [--all]

# Bootstrap
flow setup run [PROFILE|--profile NAME] [--dry-run] [--var KEY=VALUE]
flow setup show PROFILE             # preview profile steps
flow setup list

# Remote targets
flow remote enter TARGET [--dry-run]  # ssh + tmux into a remote target
flow remote list

# Dev containers (docker or podman)
flow dev create NAME -i IMAGE [-p PROJECT] [--dry-run]
flow dev attach NAME               # tmux session into container
flow dev exec NAME [-- CMD...]     # run a command in container
flow dev enter NAME                # interactive shell
flow dev stop NAME [--kill]
flow dev remove NAME [-f]
flow dev respawn NAME              # restart all tmux panes
flow dev list

# Projects
flow projects check [--fetch]      # scan ~/projects for dirty repos
flow projects fetch                # fetch all project remotes
flow projects summary              # quick overview

# Shell completion
flow completion zsh                # print zsh completion script
flow completion install-zsh        # install to ~/.zsh/completions

# Global flags
flow --version
flow --quiet                       # suppress info output
flow --no-color                    # disable colored output

Aliases

dotfiles -> dot
dotfiles repos -> dotfiles repo
packages -> package, pkg
projects -> project; flow sync -> flow projects check --fetch
setup -> bootstrap, provision
remote enter -> enter
dev attach -> dev connect
dev remove -> dev rm

Configuration

Loaded from ~/.config/flow/config.yaml, merged with dotfiles repo overlay at ~/.local/share/flow/dotfiles/_shared/flow/.config/flow/.

repository:
  url: git@github.com:you/dotfiles.git
  branch: main

paths:
  projects: ~/projects

defaults:
  container-runtime: auto           # auto | docker | podman | podman-rootful
  container-registry: registry.example.com
  container-tag: latest
  tmux-session: main

targets:
  personal@orb: personal.orb
  work@ec2:
    host: work.ec2.internal
    identity: ~/.ssh/id_work

Container runtime

container-runtime controls which engine flow dev uses:

auto -- detect docker or podman from PATH (default)
docker -- force docker
podman -- force podman, prefer rootless socket
podman-rootful -- force podman, prefer rootful socket (/run/podman/podman.sock)

When using podman, flow dev create automatically adds --security-opt label=disable for engine socket access. The socket is always mounted to /var/run/docker.sock inside the container (Podman's Docker-compatible API).

Dotfiles layout

_shared/           # Linked for all profiles
  zsh/
    .zshrc
  nvim/
    .config/nvim/
      _module.yaml  # External git module
    .local/bin/
      nvim-wrapper
  dns/
    _root/          # Absolute path marker (needs sudo)
      etc/hosts

linux-work/         # Profile-specific layer
  i3/
    .config/i3/config

External modules

_module.yaml inside a package mounts an external git repo at that location:

source: github:org/nvim-config
ref:
  branch: main

Modules are regular git clones managed by flow (not git submodules). They appear alongside the dotfiles repo in flow dotfiles repos list and are pulled/pushed with the same commands.

Manifest

Packages and profiles defined in YAML files under the flow config directory.

packages:
  - name: fd
    type: pkg
    sources:
      apt: fd-find
      brew: fd

  - name: neovim
    type: binary
    source: github:neovim/neovim
    version: "0.10.4"
    platform-map:
      linux-x64: nvim-linux-x86_64.tar.gz

profiles:
  linux-work:
    os: linux
    hostname: dev-box
    locale: en_US.UTF-8
    shell: zsh
    packages:
      - fd
      - binary/neovim
    ssh-keys:
      - path: ~/.ssh/id_ed25519
        type: ed25519
    runcmd:
      - echo "setup complete"

Architecture

Flow uses an action-centered runtime:

cli parses Typer command arguments and calls app use-cases.
app resolves config/state, builds ActionPlan objects for executor-managed work, and keeps only explicit interactive boundaries outside the executor.
domain modules keep planning and resolution logic pure with frozen dataclasses.
actions are the execution boundary: DomainAction records domain intent, expansion converts it to PrimitiveAction, and ActionExecutor handles dry-run rendering, audit logging, rollback, and dispatch.
adapters provide runtime primitives through SystemRuntime: CommandRunner, FileSystem, GitClient, TmuxClient, ContainerRuntime, download, and archive adapters.

Action audit records are appended to actions.jsonl under the relevant flow state directory.

Security

Rejects root invocation
_root/ dotfile paths require sudo for linking
Package post-install hooks run without sudo by default

Development

make deps                              # create .venv + install deps
.venv/bin/python -m pytest tests/ -v --ignore=tests/e2e
FLOW_RUN_E2E=1 .venv/bin/python -m pytest tests/e2e/ -v  # requires docker or podman