{"_id":"@appity/cloche","_rev":"3-5c6c6baad266a370961193d0d803985d","name":"@appity/cloche","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@appity/cloche","version":"0.1.0","keywords":["process","supervisor","service","manager","development","cli","restart","daemon"],"author":{"name":"Scott Tadman","email":"tadman@appity.studio"},"license":"MIT","_id":"@appity/cloche@0.1.0","maintainers":[{"name":"tadman","email":"scott@tadman.ca"}],"homepage":"https://github.com/appity/cloche","bugs":{"url":"https://github.com/appity/cloche/issues"},"bin":{"cloche":"src/cli.js"},"dist":{"shasum":"e1d6689c5e155dccdfb4f7b70262250ac5b6c3d1","tarball":"https://registry.npmjs.org/@appity/cloche/-/cloche-0.1.0.tgz","fileCount":4,"integrity":"sha512-PwDSJ2lXLkuEA5lRGayld13rcNXlxr4OzIfNggA5BdWRzpjkus23lF98YsrIzFPXHJq3/2yj2u2gRpEFrJrsnw==","signatures":[{"sig":"MEYCIQDvOxK2fOXlB0wED42dJrsHvSzYcI9cfwR2/++A1KyxzwIhAIBJOQ2PfSiYVxmqz7U8JQu+FeUWihv0XR8EEMMQvnd4","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":36755},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"9bd3b98b7ba662c9f9c50fe8b2c769d03df4eaed","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"tadman","email":"scott@tadman.ca"},"repository":{"url":"git+https://github.com/appity/cloche.git","type":"git"},"_npmVersion":"11.7.0","description":"A lightweight process supervisor for development — run, restart, and manage services with ease","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^12.1.0","shell-quote":"^1.8.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cloche_0.1.0_1766963979108_0.5911483141841671","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@appity/cloche","version":"0.1.1","keywords":["process","supervisor","service","manager","development","cli","restart","daemon"],"author":{"name":"Scott Tadman","email":"tadman@appity.studio"},"license":"MIT","_id":"@appity/cloche@0.1.1","maintainers":[{"name":"tadman","email":"scott@tadman.ca"}],"homepage":"https://github.com/appity/cloche","bugs":{"url":"https://github.com/appity/cloche/issues"},"bin":{"cloche":"src/cli.js"},"dist":{"shasum":"72da6836a62794799aae7520418fea187b622e15","tarball":"https://registry.npmjs.org/@appity/cloche/-/cloche-0.1.1.tgz","fileCount":4,"integrity":"sha512-krRgXiwBJX1aq7DanLt+T423BQ/QxfrueWtXbeHk58wBfjmtGUUtJH1j15noqMLBIL3oE8GqLkeGG1I4XkGBQw==","signatures":[{"sig":"MEYCIQCZlEpWecCJZqmYV7cbMEtVTjg4PvFdEKZr9JecWnvWJgIhAOYkAPS/8V9dTrSWtAhVvcNBc62rKWNfw1mLtv5n1wrT","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":37442},"type":"module","engines":{"node":">=18.0.0"},"gitHead":"e4aaa6b5d908aea3d23405b741244fe7b39550e7","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"tadman","email":"scott@tadman.ca"},"repository":{"url":"git+https://github.com/appity/cloche.git","type":"git"},"_npmVersion":"11.7.0","description":"A lightweight process supervisor for development — run, restart, and manage services with ease","directories":{},"_nodeVersion":"25.2.1","dependencies":{"commander":"^12.1.0","shell-quote":"^1.8.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/cloche_0.1.1_1766974714427_0.14899151290200274","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@appity/cloche","version":"0.1.2","description":"A lightweight process supervisor for development — run, restart, and manage services with ease","type":"module","bin":{"cloche":"src/cli.js"},"scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"keywords":["process","supervisor","service","manager","development","cli","restart","daemon"],"author":{"name":"Scott Tadman","email":"tadman@appity.studio"},"homepage":"https://github.com/appity/cloche","license":"MIT","repository":{"type":"git","url":"git+https://github.com/appity/cloche.git"},"bugs":{"url":"https://github.com/appity/cloche/issues"},"publishConfig":{"access":"public"},"engines":{"node":">=18.0.0"},"dependencies":{"commander":"^12.1.0","shell-quote":"^1.8.1"},"gitHead":"eff62a080b31f582ed9229842165c6d8643d1893","_id":"@appity/cloche@0.1.2","_nodeVersion":"25.2.1","_npmVersion":"11.7.0","dist":{"integrity":"sha512-Wp/JKgmaVaicf9e/jW+DmLtFd0W+tSoJapQtdxAGnIva+Bk49Z40MYp8DJq7VN9RuUn0hwYfp1GFwOB+0Nlx0A==","shasum":"64437942bf00b347185b031339a3acba26b6b756","tarball":"https://registry.npmjs.org/@appity/cloche/-/cloche-0.1.2.tgz","fileCount":4,"unpackedSize":37842,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDvP9lRIaSbfBe/HuzlJLkkSdn1RddeRR+6kLWzfhnjnAiEAlncSh6oiT0TUFpXY1k2OjLHcB0Ldw0FMDVsuuQRJ/tg="}]},"_npmUser":{"name":"tadman","email":"scott@tadman.ca"},"directories":{},"maintainers":[{"name":"tadman","email":"scott@tadman.ca"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cloche_0.1.2_1767222161787_0.6918325729314023"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-28T23:19:39.004Z","modified":"2025-12-31T23:02:42.231Z","0.1.0":"2025-12-28T23:19:39.257Z","0.1.1":"2025-12-29T02:18:34.569Z","0.1.2":"2025-12-31T23:02:41.993Z"},"bugs":{"url":"https://github.com/appity/cloche/issues"},"author":{"name":"Scott Tadman","email":"tadman@appity.studio"},"license":"MIT","homepage":"https://github.com/appity/cloche","keywords":["process","supervisor","service","manager","development","cli","restart","daemon"],"repository":{"type":"git","url":"git+https://github.com/appity/cloche.git"},"description":"A lightweight process supervisor for development — run, restart, and manage services with ease","maintainers":[{"name":"tadman","email":"scott@tadman.ca"}],"readme":"# cloche\n\nA lightweight process supervisor for development — run, restart, and manage services with ease.\n\n## Features\n\n- **Named units** — Run services with memorable names like `web`, `api`, `worker`\n- **Instant restart** — Press `^T` (Ctrl+T on macOS) to restart the subprocess without leaving your terminal\n- **Process listing** — See all managed processes, their status, and listening ports at a glance\n- **Environment management** — Automatically loads `.env` files, with CLI overrides\n- **Persistent scripts** — Commands are saved, so restarting a unit doesn't require re-typing\n- **Log capture** — STDOUT/STDERR saved to searchable logs with ANSI codes stripped (colors preserved in terminal)\n- **Log search** — Case-insensitive search with grep-style context (`--after`, `--before`, `--context`)\n- **Log tail** — View last N lines of logs (default 500)\n- **Persistent logging** — Use `--log` for full history without trimming\n\n## Installation\n\n```bash\nnpm install -g @appity/cloche\n```\n\nOr run directly with npx:\n\n```bash\nnpx @appity/cloche --help\n```\n\n## Quick Start\n\n```bash\n# Start a web server as the \"web\" unit\ncloche web npm run dev\n\n# In another terminal, start an API server\ncloche api node server.js\n\n# List all running processes\ncloche --ps\n\n# Restart a service (sends SIGUSR1)\ncloche web --restart\n\n# Stop a service\ncloche web --kill\n```\n\n## Usage\n\n```\ncloche [options] [unit] [command...]\n\nArguments:\n unit The name of the service\n command The command to run\n\nOptions:\n -V, --version output the version number\n --restart Restart the service\n --kill Kill the service\n -w, --workdir Working directory for the subprocess\n --ps List all managed processes\n -e, --env Set environment variable (repeatable)\n --env-file Load environment from file (default: .env)\n --no-env-file Disable auto-loading .env\n --log Enable persistent logging (no trimming)\n --dump-log Dump the entire log file\n --search Search log file for matching text (case-insensitive)\n -A, --after Show n lines after each match\n -B, --before Show n lines before each match\n -C, --context Show n lines before and after each match\n -E, --stderr Filter to stderr only\n --tail [n] Show last n lines of log (default: 500)\n -h, --help display help for command\n```\n\n## Examples\n\n### Running Services\n\n```bash\n# Start a Rails server\ncloche rails bin/rails server\n\n# Start with a custom working directory\ncloche api --workdir ./backend node server.js\n\n# Start with environment overrides\ncloche web -e PORT=4000 -e NODE_ENV=development npm start\n\n# Use a custom env file\ncloche api --env-file .env.local npm run dev\n```\n\n### Managing Services\n\n```bash\n# List all services with status and ports\ncloche --ps\n\n# Output:\n# UNIT PID STATUS PORTS COMMAND\n# -----------------------------------------------------------------------------------------------\n# api 12345 RUNNING 3001 node server.js\n# web 12346 RUNNING 3000, 3001 npm run dev\n# worker - STOPPED - node worker.js\n\n# Restart a service (triggers graceful restart)\ncloche api --restart\n\n# Kill a service\ncloche worker --kill\n```\n\n### Restarting from the Terminal\n\nWhen a service is running, press **`^T`** (Ctrl+T) to trigger an instant restart. This sends `SIGINFO` on macOS, which cloche intercepts to restart the subprocess.\n\nYou can also restart programmatically from another terminal:\n\n```bash\ncloche web --restart\n```\n\n### Searching Logs\n\ncloche captures all output (STDOUT/STDERR) to a log file with ANSI codes stripped for easy searching. Search is **case-insensitive** by default.\n\nSTDERR lines are prefixed with `2>` in the log, allowing you to filter errors specifically:\n\n```bash\n# Search for \"error\" in the web service logs (case-insensitive)\ncloche web --search error\n\n# Search only in stderr output\ncloche web --search error --stderr\ncloche web --search error -E # short form\n\n# Show 5 lines of context around each match\ncloche web --search error --context 5\ncloche web --search error -C 5 # short form\n\n# Show 3 lines before and 10 lines after each match\ncloche web --search \"connection refused\" --before 3 --after 10\ncloche web --search \"connection refused\" -B 3 -A 10 # short form\n\n# View the last 100 lines of logs\ncloche api --tail 100\n\n# View only stderr from the last 500 lines\ncloche api --tail --stderr\n\n# View the last 500 lines (default)\ncloche api --tail\n\n# Dump the entire log file (for piping or external processing)\ncloche api --dump-log\ncloche api --dump-log --stderr # dump only stderr\ncloche api --dump-log | grep -i \"warning\"\n```\n\n### Log Persistence\n\nBy default, logs are automatically trimmed to 100,000 lines to prevent unbounded growth. Use `--log` for persistent logging without trimming:\n\n```bash\n# Enable persistent logging (no trimming)\ncloche web --log npm run dev\n```\n\nLogs are stored in `.cloche/.log` and are overwritten each time the service starts (but preserved across `^T` restarts).\n\n## How It Works\n\n- **State directory** — cloche creates a `.cloche/` directory in your current working directory to store PID files, shell scripts, and logs\n- **Shell scripts** — Each unit's command is saved as a shell script (`.cloche/.sh`), allowing you to restart without re-specifying the command\n- **PID tracking** — cloche writes its own PID to `.cloche/.pid`, enabling `--kill` and `--restart` operations\n- **Log capture** — STDOUT/STDERR are captured to `.cloche/.log` with ANSI codes stripped; stderr lines prefixed with `2>` for filtering; auto-trims to 100K lines (unless `--log` is used)\n- **Color support** — When running in a terminal, cloche sets `FORCE_COLOR=1` and `CLICOLOR_FORCE=1` so subprocesses emit colors even though their output is piped; colors display in the terminal but are stripped from logs for clean searching\n- **Signal handling** — `SIGUSR1` and `SIGINFO` (^T on macOS) trigger subprocess restarts; `SIGINT` and `SIGTERM` cleanly shut down\n\n## Configuration\n\nYou can customize cloche behavior by creating a `.cloche/config` file with `.env`-style settings:\n\n```bash\n# Maximum lines to keep in log files (default: 100000)\nCLOCHE_MAX_LOG_LINES=50000\n\n# Trim threshold - when to trigger log trimming (default: 10% over max)\n# Optional: auto-calculated as max * 1.1 if not specified\nCLOCHE_LOG_TRIM_THRESHOLD=55000\n```\n\nThe config file is read each time a service starts, so changes take effect on the next service start or restart.\n\n## Environment Variables\n\ncloche automatically loads `.env` from the current directory. Environment priority (highest to lowest):\n\n1. `-e KEY=VALUE` command line flags\n2. `--env-file` specified file (or `.env` by default)\n3. Inherited environment from parent process\n\n## License\n\nMIT\n","readmeFilename":"README.md"}