### Example of shell completion for ky start Source: https://github.com/mrgnw/kagaya/blob/main/README.md Demonstrates how tab completion works for the `ky start` command, completing project names. This requires shell completion to be set up. ```sh ky start appli # completes to: ky start appligator ``` -------------------------------- ### Install Binary Command Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md Use 'just install' to test the installed binary by installing both the CLI and daemon crates. ```bash just install ``` -------------------------------- ### Install Kagaya prebuilt binary using cargo binstall Source: https://github.com/mrgnw/kagaya/blob/main/README.md Installs a prebuilt binary of kagaya using `cargo-binstall`. Ensure `cargo-binstall` is installed. ```sh cargo binstall kagaya ``` -------------------------------- ### Start Kagaya UI in Development Mode Source: https://github.com/mrgnw/kagaya/blob/main/ui/README.md Run this command to start both the SvelteKit development server and the Tauri window for local development. ```sh cargo tauri dev ``` -------------------------------- ### Projects configuration example (map form) Source: https://github.com/mrgnw/kagaya/blob/main/README.md Example of `projects.toml` mapping project names to their directory paths. This is the basic form for registering projects. ```toml myapp = "~/dev/myapp" api = "~/dev/api-server" frontend = "~/dev/frontend" ``` -------------------------------- ### Quick Start: Managing Services with Kagaya Source: https://github.com/mrgnw/kagaya/blob/main/crates/kagaya/README.md Demonstrates how to initialize a supervisor, define and start a service with a single process, check its status, retrieve output, and stop the service. ```rust use kagaya::{Supervisor, SupervisorConfig, ProcessDef, ServiceType}; use std::collections::HashMap; #[tokio::main] async fn main() { let sup = Supervisor::new(SupervisorConfig { log_dir: "/tmp/myapp/logs".into(), max_log_size: 10 * 1024 * 1024, }); let procs = vec![ProcessDef { name: "web".into(), command: "python -m http.server 8000".into(), service_type: ServiceType::Service, restart: true, max_retries: 3, restart_delay_secs: 1, env: HashMap::new(), autostart: true, pre_start: None, ports: vec![8000], depends_on: vec![], ready: None, ready_timeout: 10, }]; sup.start_service("myapp", "/path/to/app".as_ref(), &procs, true, &[]) .await .unwrap(); // Check status let statuses = sup.status().await; for s in &statuses { println!("{}: {:?}", s.name, s.processes[0].state); } // Get output let output = sup.get_output("myapp", Some("web")).await.unwrap(); let snapshot = output.snapshot().await; println!("{}", String::from_utf8_lossy(&snapshot)); // Stop sup.stop_service("myapp").await.unwrap(); } ``` -------------------------------- ### Start a specific project Source: https://github.com/mrgnw/kagaya/blob/main/README.md Starts all services defined in the `services.toml` for the specified project (`myapp`). ```sh ky start myapp # start one project ``` -------------------------------- ### Start UI development with HMR Source: https://github.com/mrgnw/kagaya/blob/main/README.md Navigates to the UI package, installs dependencies, and starts the UI development server with Hot Module Replacement (HMR). This is for frontend development. ```sh cd ui pnpm install pnpm dev ``` -------------------------------- ### Configure Project to Run Start Script Source: https://github.com/mrgnw/kagaya/blob/main/todos/done/1114-per-project-start-scripts.md Update projects.toml to point the 'run' key to your custom start script for services that need orchestration. ```toml [matrix] dir = "~/dev/matrix" run = "./start.sh" [openchamber] dir = "/Users/m/dev/_run/openchamber" run = "./start.sh" ``` -------------------------------- ### Install Kagaya using gah Source: https://github.com/mrgnw/kagaya/blob/main/README.md Installs kagaya using the GitHub Asset Helper (gah). Ensure `gah` is installed and configured. ```sh gah install mrgnw/kagaya ``` -------------------------------- ### Example of shell completion for ky start/status Source: https://github.com/mrgnw/kagaya/blob/main/README.md Shows tab completion for the `ky` command, suggesting subcommands like `status` and `start`. This requires shell completion to be set up. ```sh ky st # completes to: ky status / ky start / ky stop ``` -------------------------------- ### Projects configuration example (table form) Source: https://github.com/mrgnw/kagaya/blob/main/README.md Shows the table form for `projects.toml`, allowing for more advanced project configurations like enabling autostart on login. This provides more control over project management. ```toml [myapp] dir = "~/dev/myapp" autostart = true # start on login (ky autostart on) ``` -------------------------------- ### Install Kagaya using curl Source: https://github.com/mrgnw/kagaya/blob/main/README.md Installs kagaya using a prebuilt binary via a shell script. Ensure you have `curl` and `zsh` installed. ```sh curl -fsSL https://ky.xcc.es/install.sh | zsh ``` -------------------------------- ### Start all registered projects Source: https://github.com/mrgnw/kagaya/blob/main/README.md Starts all services for all projects that have been registered with kagaya. This is a convenient way to launch your entire development environment. ```sh ky start # or start everything ``` -------------------------------- ### Short label algorithm examples Source: https://github.com/mrgnw/kagaya/blob/main/todos/launchd_updates.md Examples illustrating the algorithm for generating a short label from a full process name, including stripping TLDs and handling multiple segments. ```text - `com.bjango.istatmenus.agent` → `istatmenus.agent` - `com.cloudflare.cloudflared` → `cloudflared` - `com.opencode.serve` → `opencode.serve` - `homebrew.mxcl.syncthing` → `syncthing` - `com.user.gymcalendar` → `gymcalendar` - `com.adobe.ccxprocess` → `ccxprocess` ``` -------------------------------- ### Install Kagaya from source using cargo Source: https://github.com/mrgnw/kagaya/blob/main/README.md Installs kagaya from its source code using the Rust package manager, Cargo. Requires Rust and Cargo to be installed. ```sh cargo install kagaya ``` -------------------------------- ### Autostart Management Commands Source: https://github.com/mrgnw/kagaya/blob/main/README.md Commands to manage the autostart boot agent. Use `on` to install, `off` to remove, and `status` to check the current state. ```sh ky autostart on ky autostart status # check if agent is installed + which projects autostart ky autostart off # remove the boot agent ``` -------------------------------- ### Kagaya TOML Configuration Examples Source: https://github.com/mrgnw/kagaya/blob/main/README.md Examples of `services.toml` and `config.toml` files used for Kagaya configuration. These files define project services, standalone commands, and global daemon settings. ```toml # table form — supports autostart [frontend] dir = "~/dev/frontend" autostart = true # standalone commands (no project directory needed) [tunnel] run = "ssh -N -L 5432:localhost:5432 prod-server" autostart = true [db-backup] run = "pg_dump mydb > backup.sql" type = "task" ``` ```toml # simple form — just the command web = "npm run dev" api = "python server.py" # full form — with options [worker] run = "ruby worker.rb" restart = true max_retries = 5 restart_delay = 2 env = { RAILS_ENV = "development" } # tasks — run once, no auto-restart [migrate] run = "python manage.py migrate" type = "task" # dependencies — start services in order [db] run = "docker compose up postgres" ready = "pg_isready -h localhost" # polled until exit 0 ready_timeout = 30 # seconds (default: 10) [api] run = "python server.py" depends_on = "db" # waits for db to be ready first ports = [8080] # ready when port accepts connections [worker] run = "python worker.py" depends_on = ["db", "api"] # multiple dependencies ``` ```toml [daemon] port = 13369 public_base_url = "https://ky.xcc.es" release_dir = "/srv/ky/releases" [logs] max_size_bytes = 10485760 # 10MB, triggers rotation max_age_days = 7 max_files = 5 [defaults] restart = true max_retries = 3 restart_delay = 1 env = { FORCE_COLOR = "1", CLICOLOR_FORCE = "1" } ``` -------------------------------- ### Kagaya CLI Quick Add Commands Source: https://github.com/mrgnw/kagaya/blob/main/README.md Examples of using the `ky add` command to quickly add services from a project directory. These commands infer names from the directory or allow explicit naming. ```sh cd ~/dev/myapp && ky add # infers name from directory ``` ```sh cd ~/dev/myapp && ky add myapp # uses cwd, custom name ``` ```sh ky add myapp ~/dev/myapp # full form with explicit path ``` ```sh ky add tunnel --run 'ssh -N -L 5432:localhost:5432 prod-server' # standalone command ``` -------------------------------- ### Services definition example for multiple projects Source: https://github.com/mrgnw/kagaya/blob/main/README.md Illustrates `services.toml` files for different projects (`myapp`, `api-server`, `frontend`). Each file defines the specific processes to be managed by kagaya for that project. ```toml # ~/dev/myapp/services.toml web = "npm run dev" api = "python server.py" # ~/dev/api-server/services.toml server = "cargo run" worker = "cargo run --bin worker" # ~/dev/frontend/services.toml dev = "pnpm dev" ``` -------------------------------- ### Define a simple service in services.toml Source: https://github.com/mrgnw/kagaya/blob/main/README.md Example of a `services.toml` file defining three simple services: `web`, `api`, and `worker`, each with a command to run. This file should be placed in the root of your project directory. ```toml # ~/dev/myapp/services.toml web = "npm run dev" api = "python server.py" worker = "ruby worker.rb" ``` -------------------------------- ### Build UI Command Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md Run 'just build-ui' to install UI dependencies and build the user interface. This is an intermediate step in the release process. ```bash just build-ui ``` -------------------------------- ### Ad-hoc Command Chains with '..' Source: https://github.com/mrgnw/kagaya/blob/main/README.md Execute commands sequentially using the '..' operator for ad-hoc chaining of project starts. ```sh ky start db..api worker # db→api sequential, worker starts immediately ky start db..api..worker # all three in sequence ``` -------------------------------- ### Service Dependencies and Readiness in TOML Source: https://github.com/mrgnw/kagaya/blob/main/README.md Define service dependencies and readiness checks using TOML configuration. Services will start in the order specified by `depends_on` and wait for readiness. ```toml [db] run = "docker compose up postgres" ready = "pg_isready -h localhost" [api] run = "python server.py" depends_on = "db" ``` -------------------------------- ### Example of shell completion for ky status Source: https://github.com/mrgnw/kagaya/blob/main/README.md Illustrates tab completion for the `ky status` command, which lists available project names. This requires shell completion to be set up. ```sh ky status # shows all project names ``` -------------------------------- ### Configure Fish shell completion Source: https://github.com/mrgnw/kagaya/blob/main/README.md Installs kagaya's Fish shell completion script by creating a symbolic link in the Fish completions directory. This enables tab completion for `ky` commands in Fish. ```sh ln -s ~/.local/share/kagaya/completions/ky.fish ~/.config/fish/completions/ ``` -------------------------------- ### Watch Mode Examples Source: https://github.com/mrgnw/kagaya/blob/main/README.md Commands that modify services automatically enter watch mode to confirm the operation. The watch behavior adapts based on process status, logs, and port readiness. ```sh ky start myapp # starts, watches for 4s ky stop myapp # stops, exits once confirmed stopped ky restart myapp # restarts, watches for 6s ky restart myapp web # restarts process, watches for 6s ``` -------------------------------- ### Blocking Start with --wait Source: https://github.com/mrgnw/kagaya/blob/main/README.md Use the `--wait` flag to block CLI execution until a project's processes are ready. Useful for scripting and ensuring services are available before proceeding. ```sh ky start db --wait && echo "db is up" ``` -------------------------------- ### Standalone commands configuration example Source: https://github.com/mrgnw/kagaya/blob/main/README.md Defines standalone commands directly within the `projects.toml` using the table format. This allows managing commands like SSH tunnels or sync scripts that are not tied to a specific project directory. ```toml [tunnel] run = "ssh -N -L 5432:localhost:5432 prod-server" autostart = true [sync] run = "watchman-wait . --max-events 0 -p '*.json' | xargs ./sync.sh" type = "task" ``` -------------------------------- ### Get etime and PID for uptime calculation Source: https://github.com/mrgnw/kagaya/blob/main/todos/launchd_updates.md Command to retrieve the elapsed time (etime) and process ID (PID) for running agents, used for calculating and displaying uptime. This command is intended to be run for specific PIDs. ```bash ps -o etime=,pid= -p ``` -------------------------------- ### Build All Command Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md Use 'just build-all' to combine UI builds with a release build for the native target. ```bash just build-all ``` -------------------------------- ### Autostart Configuration in projects.toml Source: https://github.com/mrgnw/kagaya/blob/main/README.md Configure projects for automatic startup on login by setting `autostart = true` in `projects.toml`. This applies to both directory-based projects and standalone commands. ```toml [myapp] dir = "~/dev/myapp" autostart = true [tunnel] run = "ssh -N -L 5432:localhost:5432 prod-server" autostart = true ``` -------------------------------- ### Initialize Kagaya configuration Source: https://github.com/mrgnw/kagaya/blob/main/README.md Creates the default kagaya projects configuration file at `~/.config/kagaya/projects.toml`. Run this command once to set up kagaya. ```sh ky init ``` -------------------------------- ### Build Kagaya UI for Production Source: https://github.com/mrgnw/kagaya/blob/main/ui/README.md Execute this command to build a production-ready version of the Kagaya UI application. ```sh cargo tauri build ``` -------------------------------- ### Local Development Command Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md Use 'just build' for day-to-day development tasks. ```bash just build ``` -------------------------------- ### Distribution Command Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md Use 'just dist' to build the UI, cross-compile for all four targets, and package the results into the 'dist/' directory with latest assets. ```bash just dist ``` -------------------------------- ### Kagaya CLI Basic Commands Source: https://github.com/mrgnw/kagaya/blob/main/README.md Common commands for initializing, adding, and managing projects and standalone commands. ```sh ky init # create projects config file ky add [name] [dir] # register a project directory (uses cwd if omitted) ky add --run # register a standalone command ky status # show all projects ky start [name] # start project(s), or one process with project.process ky stop [name] # stop project(s), or one process with project.process ky reload [name] # restart project(s) (picks up config changes) ky kill [name] # kill process(es) in project(s) ky restart [name] # restart project(s), or one process with project.process ky echo [name] # live stream logs from project(s) ky logs [name] # show last 100 lines of log file ky tail [name] # follow log file (tail -f) ky serve [-p PORT] # start web UI server (default port: 13369) ky autostart on # install boot agent (start services on login) ky autostart off # remove boot agent ky autostart status # show autostart status ``` -------------------------------- ### Build Release Command Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md Run 'just build-release' to perform a release build for the native target only. ```bash just build-release ``` -------------------------------- ### Configure Zsh shell completion Source: https://github.com/mrgnw/kagaya/blob/main/README.md Sets up Zsh shell completion for kagaya by adding the completions directory to `fpath` and initializing `compinit`. Add this to your `.zshrc`. ```sh # Add to ~/.zshrc fpath=(~/.local/share/kagaya/completions $fpath) autoload -Uz compinit && compinit ``` -------------------------------- ### Register a project with a specific path Source: https://github.com/mrgnw/kagaya/blob/main/README.md Adds a project named `myapp` located at `~/dev/myapp` to kagaya's management. This command tells kagaya where to find the project's `services.toml`. ```sh ky add myapp ~/dev/myapp ``` -------------------------------- ### Release Flow Sequence Diagram Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md This sequence diagram illustrates the 'just release' command's interaction with various tools like pnpm, cargo, zigbuild, and GitHub CLI to create a new release. ```mermaid sequenceDiagram participant Dev as Developer participant J as just release participant UI as pnpm (ui/) participant Cargo as cargo participant Zig as cargo zigbuild participant GH as gh (GitHub) Dev->>J: just release J->>UI: pnpm install && pnpm build UI-->>J: ui/build/ ready loop each target alt macOS (aarch64, x86_64) J->>Cargo: cargo build --release --target else Linux (aarch64, x86_64) J->>Zig: cargo zigbuild --release --target end end J->>J: tar archives + latest aliases → dist/ J->>Dev: confirm? [y/N] Dev->>J: y J->>GH: gh release create vX.Y.Z dist/*.tar.gz GH-->>Dev: released Note over Dev: don't forget: cargo publish ``` -------------------------------- ### Define advanced service with type and dependencies Source: https://github.com/mrgnw/kagaya/blob/main/README.md Shows a `services.toml` entry for a `migrate` service. It specifies the run command, sets the type to `task` (runs once), and defines a dependency on the `db` service. ```toml [web] run = "npm run dev" [migrate] run = "python manage.py migrate" type = "task" # runs once, no auto-restart depends_on = "db" # start after db is ready ``` -------------------------------- ### Current launchd list view format Source: https://github.com/mrgnw/kagaya/blob/main/todos/launchd_updates.md This is the existing format for the launchd list view, showing the process symbol, full name, and PID. ```text ● com.bjango.istatmenus.agent /Users/m/Library/Application Support/iStat Menus 7/iStat Men pid 768 ``` -------------------------------- ### Register current project directory Source: https://github.com/mrgnw/kagaya/blob/main/README.md Registers the current directory as a project with kagaya. Kagaya will automatically detect the project name and path. This is a shorthand for `ky add` when run from the project's root. ```sh cd ~/dev/myapp ky add # myapp: added (/Users/you/dev/myapp) ``` -------------------------------- ### Release Command Source: https://github.com/mrgnw/kagaya/blob/main/BUILDING.md Use 'just release' to ship a new version of the project. This command orchestrates UI builds, cross-compilation, and GitHub release creation. ```bash just release ``` -------------------------------- ### Directory-Based Projects Configuration Source: https://github.com/mrgnw/kagaya/blob/main/README.md Define directory-based projects in `projects.toml`. Each project entry maps a name to its directory path. ```toml # directory-based projects (each has its own services.toml) myapp = "~/dev/myapp" api = "~/dev/api-server" ``` -------------------------------- ### Targeting Specific Projects and Processes Source: https://github.com/mrgnw/kagaya/blob/main/README.md Commands can target specific projects by name or use `project.process` notation for individual processes within a project. Omitting the name targets all projects or the current project contextually. ```sh ky status myapp # show status of myapp ky myapp status # same thing, flexible arg ordering ky start jobs.ui # start/restart only the ui process in jobs ky stop jobs.sync # stop only the sync process in jobs ky restart jobs.ui # restart only the ui process in jobs ky status jobs.ui # show only the ui process in jobs ky start # start all projects ky stop # stop all projects cd ~/dev/myapp && ky status # show status of myapp (context-aware) ``` -------------------------------- ### Run Kagaya CLI in dev mode Source: https://github.com/mrgnw/kagaya/blob/main/README.md Executes the kagaya CLI binary directly from the workspace for development purposes. Use this to test CLI commands during development. ```sh cargo run -p kagaya -- status ``` -------------------------------- ### Copy listening_ports_for_pids function Source: https://github.com/mrgnw/kagaya/blob/main/todos/launchd_updates.md Copy the `listening_ports_for_pids()` function from `daemon/supervisor.rs` to `launchd.rs`. This function is necessary for detecting and displaying listening ports for running agents. ```rust Copy `listening_ports_for_pids()` from `daemon/supervisor.rs` into `launchd.rs`. ``` -------------------------------- ### New launchd list view format Source: https://github.com/mrgnw/kagaya/blob/main/todos/launchd_updates.md The proposed new format for the launchd list view, which includes a symbol, short label, status, uptime, PID, and optional port information, matching kagaya's column format. ```text ● istatmenus.agent on 2h15m 768 ● opencode.serve on 2h15m 759 :3000 ⚠ cloudflared exit 1 ◻ espanso not loaded ◻ ccxprocess exit 0 ``` -------------------------------- ### Configure Bash shell completion Source: https://github.com/mrgnw/kagaya/blob/main/README.md Adds kagaya's Bash shell completion script to your `.bashrc` file. This enables tab completion for `ky` commands in Bash. ```sh echo 'source ~/.local/share/kagaya/completions/ky.bash' >> ~/.bashrc ``` -------------------------------- ### Live Log Streaming and Following Source: https://github.com/mrgnw/kagaya/blob/main/README.md Stream logs in real-time or view historical log data. `echo` streams live, `logs` shows recent lines, and `tail` follows the log file. ```sh ky echo myapp # live stream logs from myapp (runs until stopped) ky echo myapp web # live stream from specific process ky logs myapp # show last 100 lines from log file ky tail myapp # follow log file (like tail -f) ``` -------------------------------- ### Detail View Enhancements Source: https://github.com/mrgnw/kagaya/blob/main/todos/launchd_updates.md The detail view for a specific agent (status