fuku

fuku is a lightweight CLI orchestrator for running and managing multiple local services in development environments.

Features

• Interactive TUI - Real-time service monitoring with status, CPU, memory, and uptime
• Service Orchestration - Tier-based startup ordering
• Service Control - Start, stop, and restart services interactively
• Graceful Shutdown - SIGTERM with timeout before force kill
• Profile Support - Group services for batch operations
• Readiness Checks - HTTP, TCP, and log-pattern based health checks
• Pre-flight Cleanup - Automatic detection and termination of orphaned processes before starting services
• Hot-Reload - Automatic service restart on file changes
• Log Streaming - Stream logs from running instances via fuku logs

Installation

Homebrew

brew install tab/apps/fuku

Install Script

curl -fsSL https://getfuku.sh/install.sh | sh

Build from Source

git clone git@github.com:tab/fuku.git
cd fuku
go build -o cmd/fuku cmd/main.go
sudo ln -sf $(pwd)/cmd/fuku /usr/local/bin/fuku

Quick Start

# Generate config file
fuku init                       # Creates fuku.yaml template
fuku i                          # Short alias

# Run with TUI (default profile)
fuku

# Run with specified profile without TUI
fuku run core --no-ui
fuku --no-ui run core           # Flags work in any position

# Use short aliases
fuku r core                     # Same as 'fuku run core'

# Stream logs from running instance (in separate terminal)
fuku logs                       # All services
fuku logs api auth              # Specific services
fuku l api db                   # Short alias

# Use custom config file
fuku --config path/to/fuku.yaml run core
fuku -c custom.yaml run core

# Show help
fuku help                       # or --help, -h

# Show version
fuku version                    # or --version, -v

TUI Controls

↑/↓ or k/j       Navigate services
pgup/pgdn        Scroll viewport
home/end         Jump to start/end
r                Restart selected service
s                Stop/start selected service
q                Quit (stops all services)

Configuration

Generate a config template with fuku init, or create fuku.yaml manually in your project root (fuku.yml is also supported as a fallback when fuku.yaml is absent).

Local Overrides

Create fuku.override.yaml (or fuku.override.yml) next to your base config for local customizations that won't be committed:

# fuku.override.yaml — typically .gitignored
services:
  api:
    command: "dlv debug ./cmd/main.go"  # use debugger locally
    watch:
      include: ["*.templ"]              # appended to base includes
  debug-tool:
    dir: tools/debug                    # add a local-only service

logging:
  level: debug

Override merges are applied automatically when using default config discovery. Explicit --config skips override loading. Maps are deep-merged, arrays are concatenated, and setting a key to null removes it.

See the documentation for full details.

Example Configuration

version: 1

services:
  auth:
    dir: auth
    tier: foundation
    command: go run cmd/main.go
    readiness:
      type: http
      url: http://localhost:8081/health
      timeout: 30s

  backend:
    dir: backend
    tier: platform
    readiness:
      type: http
      url: http://localhost:8080/health
      timeout: 30s

  web:
    dir: frontend
    tier: edge
    command: npm run dev

profiles:
  default: "*"
  backend: [auth, backend]

logging:
  format: console
  level: info

For the full configuration reference, examples, and advanced patterns see the documentation.

Documentation

Full documentation is available at getfuku.sh:

• Getting Started - First steps with fuku
• Configuration - All config options explained
• CLI Reference - Commands, flags, and aliases
• Examples - Real-world configuration patterns
• Troubleshooting - Common issues and solutions

Architecture

See ARCHITECTURE.md for detailed architectural patterns and design decisions.

Development

make fmt        # Format code
make vet        # Run go vet
make lint       # Run golangci-lint
make lint:fix   # Run golangci-lint with --fix
make test       # Run unit tests
make test:race  # Run tests with race detector
make build      # Build binary
make test:e2e   # Run e2e tests (requires build)
make coverage   # Generate coverage report

Verification loop:

make vet && make lint && make test && make build && make test:e2e && make test:race

Privacy & Telemetry

Official release binaries include Sentry error tracking to help identify and fix bugs. This is completely transparent and can be disabled.

• Set FUKU_TELEMETRY_DISABLED=1 to opt out
• Build from source to disable telemetry entirely

See Privacy & Telemetry for full details on what is and isn't collected.

About the Name

The name fuku (福) means "good fortune" in Japanese. Inspired by jazz pianist Ryo Fukui, reflecting the tool's focus on orchestration and harmony.

License

Distributed under the MIT License. See LICENSE for more information.