filip-stack CLI

Use the CLI to set up or update a machine's global guidance, agent profiles, output styles, and design system.

Needs: Git and Node.js 22.12+ (installed by Homebrew)
Source checkout: A separate checkout of filip-stack; update needs main

Install

Clone the repository.

git clone https://github.com/filipgutica/filip-stack.git ~/code/filip-stack

Install the CLI with Homebrew.

brew install filipgutica/tap/filip-stack

The default checkout is ~/code/filip-stack. For another location, use filip-stack --repo <dir> <command>. Without Homebrew, run node scripts/host-config.mjs <command> from the checkout, such as node scripts/host-config.mjs status.

If an old ~/.local/bin/filip-stack symlink shadows Homebrew, remove that symlink. Check the active command with command -v filip-stack.

Apply the setup

Inspect the applied and repository commits and each target's state.
```
filip-stack status
```
Write the setup to this machine.
```
filip-stack apply
```

From the checkout	What apply writes
`host-config/guidance/`	A marked block in `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`. Text outside the block stays as it is.
`host-config/claude/`	`~/.claude`: agent templates (critic, explorer, reviewer, worker-high) and output styles.
`host-config/codex/`	`~/.codex`: agent profiles and `rules/filip-stack.rules`.
`host-config/agents/`	`~/.agents/roles.md` and `~/.agents/CODING_STANDARDS.md`.
`host-config/design-system.json`	`~/design-system`, from the pinned `@filipgutica/design-system` package. Apply downloads it once and caches it in `~/.cache/filip-stack`. See Design system.

The manifest at ~/.agents/.filip-stack-host-config.json records the applied commit and file hashes. Apply removes previously managed files when the repository removes them.

Keep up to date

Run filip-stack sync to refresh this machine's guidance, standalone skills, and filip-stack plugins. Your fleet policy selects a shared baseline and per-machine exceptions; existing extras remain. It requires a clean checkout tracking main and preserves local guidance. Conflicts appear in its result.

For every enrolled machine, use the Fleet Sync skill. Offline and unlinked machines remain visible in the fleet report.

Upgrade the CLI launcher separately with Homebrew:

brew update
brew upgrade filipgutica/tap/filip-stack

filip-stack --version shows the launcher version. filip-stack update updates host config from the checkout.

On another branch or a detached HEAD, update stops before pulling or applying. Switch the checkout to main, or use apply to apply its current contents.

Sync your Field Guide preferences

The repository ships no preferences. To share yours between machines, sync this dotfile with your dotfile manager.

~/.config/filip-stack/field-guide.json: With $XDG_CONFIG_HOME set and nonempty, the file is filip-stack/field-guide.json in that folder instead.

On a machine with preferences to keep, export them.
```
filip-stack field-guide-sync
```
Add the file to your dotfile manager, such as chezmoi. Use your configured path.
```
chezmoi add ~/.config/filip-stack/field-guide.json
```
On other machines, restore the dotfile, then run filip-stack apply to import it. Without it, apply prints its expected path and continues.
For later updates, pull your dotfiles first. After update syncs preferences, save the changed dotfile back.
```
chezmoi update
filip-stack update
chezmoi re-add
```

Pulling first lets the sync merge other machines' preferences. chezmoi re-add updates chezmoi's own copy of the file.

Recover from a local edit

If managed text changed locally, apply prints the diff and stops. Choose one:

Move the change into host-config/, commit it, and rerun apply to share it across machines.
Rerun apply with --force to save the local file as <file>.bak and overwrite it.

An existing, nonempty guidance file without a managed block also counts as edited. After forcing, restore machine-local text from the backup below the block.

Keep machine-local notes below the marked block in CLAUDE.md or AGENTS.md. They stay in place and override conflicting shared guidance.

Command reference

Command	What it does
`filip-stack --version`	Shows the installed CLI launcher's version.
`filip-stack status`	Shows the applied and repository commits, then each target's state.
`filip-stack apply`	Writes the setup and imports your preferences dotfile if it exists.
`filip-stack update`	On `main`: runs `git pull --ff-only`, then apply, then `field-guide-sync` if your preferences dotfile exists.
`filip-stack sync`	Applies this machine's declared fleet baseline and refreshes existing filip-stack installations. Add `--dry-run --json` for a local preview.
`filip-stack field-guide-sync`	Imports the preferences dotfile if present, then exports this machine's shared preferences to it.

apply --force and update --force back up and overwrite managed local edits. Use --home <dir> to target another home directory.