{"id":38242774,"url":"https://github.com/tab/fuku","last_synced_at":"2026-03-08T19:04:13.515Z","repository":{"id":326445566,"uuid":"1036931720","full_name":"tab/fuku","owner":"tab","description":"lightweight CLI orchestrator for running and managing services in development environment","archived":false,"fork":false,"pushed_at":"2026-01-31T20:53:54.000Z","size":1565,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-31T23:43:12.746Z","etag":null,"topics":["developer-tools","go","golang","orchestrator"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tab.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-12T19:52:52.000Z","updated_at":"2026-01-25T19:36:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tab/fuku","commit_stats":null,"previous_names":["tab/fuku"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/tab/fuku","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Ffuku","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Ffuku/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Ffuku/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Ffuku/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tab","download_url":"https://codeload.github.com/tab/fuku/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tab%2Ffuku/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28992629,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T20:57:35.821Z","status":"ssl_error","status_checked_at":"2026-02-01T20:57:29.580Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","go","golang","orchestrator"],"created_at":"2026-01-17T01:17:04.873Z","updated_at":"2026-03-01T17:07:42.413Z","avatar_url":"https://github.com/tab.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fuku\n\n[![CI](https://github.com/tab/fuku/actions/workflows/master.yaml/badge.svg)](https://github.com/tab/fuku/actions/workflows/master.yaml)\n[![codecov](https://codecov.io/github/tab/fuku/branch/master/graph/badge.svg?token=H1PA2DYMIZ)](https://codecov.io/github/tab/fuku)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**fuku** is a lightweight CLI orchestrator for running and managing multiple local services in development environments.\n\n![screenshot](assets/demo.gif)\n\n## Features\n\n- **Interactive TUI** - Real-time service monitoring with status, CPU, memory, and uptime\n- **Service Orchestration** - Tier-based startup ordering\n- **Service Control** - Start, stop, and restart services interactively\n- **Graceful Shutdown** - SIGTERM with timeout before force kill\n- **Profile Support** - Group services for batch operations\n- **Readiness Checks** - HTTP, TCP, and log-pattern based health checks\n- **Pre-flight Cleanup** - Automatic detection and termination of orphaned processes before starting services\n- **Hot-Reload** - Automatic service restart on file changes\n- **Log Streaming** - Stream logs from running instances via `fuku logs`\n\n## Installation\n\n### Download from Releases\n\nDownload the latest binary from [GitHub Releases](https://github.com/tab/fuku/releases)\n\n**macOS (Apple Silicon):**\n```bash\ncd ~/Downloads\ntar -xzf fuku_v0.15.2_macos_arm64.tar.gz\nsudo xattr -rd com.apple.quarantine ~/Downloads/fuku_v0.15.2_macos_arm64/fuku\nsudo mv ~/Downloads/fuku_v0.15.2_macos_arm64/fuku /usr/local/bin/fuku\n```\n\n**macOS (Intel):**\n```bash\ncd ~/Downloads\ntar -xzf fuku_v0.15.2_macos_amd64.tar.gz\nsudo xattr -rd com.apple.quarantine ~/Downloads/fuku_v0.15.2_macos_amd64/fuku\nsudo mv ~/Downloads/fuku_v0.15.2_macos_amd64/fuku /usr/local/bin/fuku\n```\n\n**Linux:**\n```bash\ncd ~/Downloads\ntar -xzf fuku_v0.15.2_linux_amd64.tar.gz\nsudo mv ~/Downloads/fuku_v0.15.2_linux_amd64/fuku /usr/local/bin/fuku\n```\n\n### Build from Source\n\n```bash\ngit clone git@github.com:tab/fuku.git\ncd fuku\ngo build -o cmd/fuku cmd/main.go\nsudo ln -sf $(pwd)/cmd/fuku /usr/local/bin/fuku\n```\n\n## Quick Start\n\n```bash\n# Generate config file\nfuku init                       # Creates fuku.yaml template\nfuku i                          # Short alias\n\n# Run with TUI (default profile)\nfuku\n\n# Run with specified profile without TUI\nfuku run core --no-ui\nfuku --no-ui run core           # Flags work in any position\n\n# Use short aliases\nfuku r core                     # Same as 'fuku run core'\n\n# Stream logs from running instance (in separate terminal)\nfuku logs                       # All services\nfuku logs api auth              # Specific services\nfuku logs --profile core api    # Filter by profile\nfuku l api db                   # Short alias\n\n# Show help\nfuku help                       # or --help, -h\n\n# Show version\nfuku version                    # or --version, -v\n```\n\n### TUI Controls\n\n```\n↑/↓ or k/j       Navigate services\npgup/pgdn        Scroll viewport\nhome/end         Jump to start/end\nr                Restart selected service\ns                Stop/start selected service\nq                Quit (stops all services)\n```\n\n## Configuration\n\nGenerate a config template with `fuku init`, or create `fuku.yaml` manually in your project root:\n\n```yaml\nversion: 1\n\nx-readiness-http: \u0026readiness-http\n  type: http\n  timeout: 30s\n  interval: 500ms\n\nx-readiness-tcp: \u0026readiness-tcp\n  type: tcp\n  timeout: 30s\n  interval: 500ms\n\nx-readiness-log: \u0026readiness-log\n  type: log\n  pattern: \"Service ready\"\n  timeout: 30s\n\nx-logs: \u0026logs\n  output: [stdout, stderr]\n\nx-watch: \u0026watch\n  include: [\"**/*.go\"]\n  ignore: [\"**/*_test.go\"]\n  shared: [\"pkg/common\"]\n  debounce: 1s\n\nservices:\n  postgres:\n    dir: infrastructure/postgres\n    tier: foundation\n    readiness:\n      \u003c\u003c: *readiness-tcp\n      address: localhost:5432\n\n  backend:\n    dir: backend\n    tier: platform\n    readiness:\n      \u003c\u003c: *readiness-http\n      url: http://localhost:8080/health\n    logs:\n      \u003c\u003c: *logs\n    watch:\n      \u003c\u003c: *watch\n\n  web:\n    dir: frontend\n    tier: edge\n    readiness:\n      \u003c\u003c: *readiness-http\n      url: http://localhost:3000/health\n\ndefaults:\n  profiles: [default]\n\nprofiles:\n  default: \"*\"                    # All services\n  backend: [postgres, api]        # Backend services only\n\nconcurrency:\n  workers: 5                      # Max concurrent service starts\n\nretry:\n  attempts: 3                     # Max retry attempts\n  backoff: 500ms                  # Initial backoff duration\n\nlogs:\n  buffer: 100                     # Log streaming buffer size\n\nlogging:\n  format: console\n  level: info\n```\n\n### Tiers\n\nServices are organized into tiers for startup ordering.\nYou can use any tier names you want - the startup order is determined by the first occurrence of each tier name in your `fuku.yaml` file.\n\nCommon tier naming pattern:\n- **foundation** - Base infrastructure (databases, message queues)\n- **platform** - Business logic services\n- **edge** - Client-facing services\n\nYou can also use custom tier names like `infrastructure`, `middleware`, `api`, `frontend`, etc. The key points:\n- Tier order is defined by first appearance in the YAML file\n- Services within each tier are sorted alphabetically by name\n- Services without a tier are placed in a `default` tier that runs last\n- Tier names are case-insensitive and whitespace is trimmed\n\nFor example, if your YAML defines services with tiers in this order: `foundation` → `platform` → `edge`, services will start in that order, tier by tier.\n\n### Readiness Checks\n\n**HTTP** - Wait for HTTP endpoint to respond with 2xx status:\n```yaml\nreadiness:\n  type: http\n  url: http://localhost:8080/health\n  timeout: 30s\n  interval: 1s\n```\n\n**TCP** - Wait for TCP port to accept connections:\n```yaml\nreadiness:\n  type: tcp\n  address: localhost:6379\n  timeout: 10s\n  interval: 1s\n```\n\n**Log** - Wait for pattern in service output:\n```yaml\nreadiness:\n  type: log\n  pattern: \"gRPC server started\"\n  timeout: 30s\n```\n\n### Watch Configuration (Hot-Reload)\n\nEnable automatic service restart on file changes:\n\n```yaml\nservices:\n  api:\n    dir: ./api\n    watch:\n      include: [\"**/*.go\"]           # Glob patterns to watch\n      ignore: [\"**/*_test.go\"]       # Patterns to ignore\n      shared: [\"pkg/common\"]         # Shared paths (triggers restart)\n      debounce: 300ms                # Debounce duration (default: 300ms)\n```\n\n### Per-Service Log Output\n\nControl which output streams are logged to the console per service:\n\n```yaml\nservices:\n  api:\n    dir: ./api\n    logs:\n      output: [stdout]              # Only log stdout (default: both)\n  worker:\n    dir: ./worker\n    logs:\n      output: [stdout, stderr]      # Log both streams explicitly\n```\n\nValid output values: `stdout`, `stderr`. When omitted, both streams are logged.\n\n### YAML Anchors\n\nUse YAML anchors (`\u0026`) and merge keys (`\u003c\u003c: *`) to avoid repeating common configuration:\n\n```yaml\nx-readiness-http: \u0026readiness-http\n  type: http\n  timeout: 30s\n  interval: 500ms\n\nx-watch: \u0026watch\n  include: [\"**/*.go\"]\n  ignore: [\"**/*_test.go\"]\n  debounce: 1s\n\nservices:\n  api:\n    dir: ./api\n    readiness:\n      \u003c\u003c: *readiness-http\n      url: http://localhost:8080/health\n    watch:\n      \u003c\u003c: *watch\n```\n\nTop-level keys prefixed with `x-` are ignored by fuku and serve as anchor definitions.\n\n### Service Requirements\n\nEach service directory must have a Makefile with a `run` target:\n\n```makefile\nrun:\n\tnpm start\n```\n\nCheck examples in the [examples](examples/bookstore) directory for reference.\n\n## Architecture\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for detailed architectural patterns and design decisions.\n\n## Development\n\n### Tests and linters\n\n```bash\n# Run tests\nmake test\n\n# Run linter\nmake lint\n\n# Run vet\nmake vet\n\n# Run coverage\nmake coverage\n\n# Format code\ngo fmt ./...\n\n# Full validation\nmake vet \u0026\u0026 make lint \u0026\u0026 make test\n```\n\n## Privacy \u0026 Telemetry\n\nOfficial release binaries include [Sentry](https://sentry.io) error tracking to help identify and fix bugs. This is completely transparent and can be disabled.\n\n### What is collected\n\n- Error types and stack traces (no file paths with usernames)\n- Performance timing for startup, shutdown, and readiness checks\n- Environment metadata: OS, architecture, Go version, fuku version\n- Command and profile names, service/tier counts\n\n### What is NOT collected\n\n- Hostnames, IP addresses, or usernames\n- Service names, fuku.yaml contents, or log output\n- Environment variable values or file paths\n- Any personally identifiable information\n\n### How to opt out\n\n1. **Set `FUKU_TELEMETRY_DISABLED=1`** — disables all telemetry regardless of DSN\n2. **Build from source** — no Sentry DSN compiled in, telemetry is disabled by default\n\n## About the Name\n\nThe name fuku (福) means \"good fortune\" in Japanese. Inspired by jazz pianist Ryo Fukui, reflecting the tool's focus on orchestration and harmony.\n\n## License\n\nDistributed under the MIT License. See `LICENSE` for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftab%2Ffuku","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftab%2Ffuku","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftab%2Ffuku/lists"}