flow/example/README.md

Example working scenario

This folder contains a complete, practical dotfiles + bootstrap setup that exercises most flow features.

What this example shows

• Dotfiles repository layout with common/ packages and profiles/work/ overrides
• Self-hosted flow config + manifest in common/flow/.config/flow/
• Bootstrap profiles for Linux (auto PM detection), Ubuntu (apt), Fedora (dnf), and macOS (brew)
• Bootstrap actions: requires, hostname, locale, shell, package install, binary install, ssh_keygen, configs, and runcmd
• Package name mapping via package-map (apt/dnf/brew)
• Dotfiles repo workflows: status, pull, push, sync --relink, and edit

Layout

• dotfiles-repo/common/flow/.config/flow/config example flow config
• dotfiles-repo/common/flow/.config/flow/manifest.yaml profiles + package map + binaries
• dotfiles-repo/common/zsh/.zshrc, common/git/.gitconfig, common/tmux/.tmux.conf
• dotfiles-repo/common/nvim/.config/nvim/init.lua
• dotfiles-repo/common/bin/.local/bin/flow-hello
• dotfiles-repo/profiles/work/git/.gitconfig and profiles/work/zsh/.zshrc overrides

Quick start

Use the absolute path to this local example repo:

EXAMPLE_REPO="/ABSOLUTE/PATH/TO/flow-cli/example/dotfiles-repo"

Initialize and link dotfiles:

flow dotfiles init --repo "$EXAMPLE_REPO"
flow dotfiles link
flow dotfiles status

Check repo commands:

flow dotfiles repo status
flow dotfiles repo pull --relink
flow dotfiles repo push

Edit package or file/path targets:

flow dotfiles edit zsh --no-commit
flow dotfiles edit common/flow/.config/flow/manifest.yaml --no-commit

Inspect bootstrap profiles and package resolution:

flow bootstrap list
flow bootstrap packages --resolved
flow bootstrap packages --profile fedora-dev --resolved
flow bootstrap show linux-auto

Run bootstrap in dry-run mode:

flow bootstrap run --profile linux-auto --var TARGET_HOSTNAME=devbox --var USER_EMAIL=you@example.com --dry-run
flow bootstrap run --profile work-linux --var WORK_EMAIL=you@company.com --dry-run

Manifest notes

• linux-auto omits package-manager to demonstrate auto-detection.
• ubuntu-dev uses legacy packages.package key to show compatibility.
• package-map rewrites logical names like fd and python-dev per package manager.
• If mapping is missing for the selected manager, flow uses the original package name and warns.