{"id":22874428,"url":"https://github.com/hahnavi/komandan","last_synced_at":"2026-05-08T05:56:29.430Z","repository":{"id":267255114,"uuid":"900408288","full_name":"hahnavi/komandan","owner":"hahnavi","description":"Komandan is a server automation tool that uses Lua programming language interface and SSH connection.","archived":false,"fork":false,"pushed_at":"2025-03-30T18:42:30.000Z","size":256,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T19:33:07.589Z","etag":null,"topics":["ansible","automation","lua","rust","server","ssh"],"latest_commit_sha":null,"homepage":"https://komandan.vercel.app","language":"Rust","has_issues":true,"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/hahnavi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"hahnavi","ko_fi":"hahnavi"}},"created_at":"2024-12-08T17:44:29.000Z","updated_at":"2025-02-15T13:37:54.000Z","dependencies_parsed_at":"2024-12-09T10:24:49.385Z","dependency_job_id":"6b43e770-0f70-40d5-b816-521d8612170c","html_url":"https://github.com/hahnavi/komandan","commit_stats":null,"previous_names":["hahnavi/komandan"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hahnavi%2Fkomandan","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hahnavi%2Fkomandan/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hahnavi%2Fkomandan/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hahnavi%2Fkomandan/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hahnavi","download_url":"https://codeload.github.com/hahnavi/komandan/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246472582,"owners_count":20783225,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ansible","automation","lua","rust","server","ssh"],"created_at":"2024-12-13T14:36:15.998Z","updated_at":"2026-05-08T05:56:29.423Z","avatar_url":"https://github.com/hahnavi.png","language":"Rust","funding_links":["https://github.com/sponsors/hahnavi","https://ko-fi.com/hahnavi"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg alt=\"Komandan Logo\" height=\"230\" src=\"assets/komandan.png\" /\u003e\n\n# Komandan\n\n#### Your army commander\n\n[![Build Status]][github-actions] [![License:MIT]][license] [![Coverage]][codecov.io]\n\n[Build Status]: https://github.com/hahnavi/komandan/actions/workflows/rust.yml/badge.svg\n[github-actions]: https://github.com/hahnavi/komandan/actions\n[License:MIT]: https://img.shields.io/badge/License-MIT-blue.svg\n[license]: https://github.com/hahnavi/komandan/blob/main/LICENSE\n[Coverage]: https://codecov.io/gh/hahnavi/komandan/branch/main/graph/badge.svg\n[codecov.io]: https://app.codecov.io/gh/hahnavi/komandan\n\n\u003c/div\u003e\n\nKomandan is a server automation tool that simplifies remote server management by leveraging the power and flexibility of the Lua programming language. It connects to target servers via SSH, following an agentless approach for streamlined operation. Komandan is designed to be easy to learn and use, even for those new to server automation.\n\n\u003e **Notice:** Komandan is in early development and currently supports Linux only. Updates will come as development progresses. Feedback is welcome—thank you for your support!\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n- [`komando` function](#komando-function)\n- [Modules](#modules)\n- [Built-in functions](#built-in-functions)\n- [Default Values](#default-values)\n- [Parallel Execution](#parallel-execution)\n- [Error Handling](#error-handling)\n- [Contributing](#contributing)\n- [License](#license)\n- [Full Documentation](#full-documentation)\n\n## Installation\n\nPre-built binaries for Komandan are available for Linux on the [GitHub Releases](https://github.com/hahnavi/komandan/releases) page.\n\nAn installation script is provided for easy installation:\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/hahnavi/komandan/main/install.sh | sh\n```\n\nThis script will download the latest Komandan release for your system and install Komandan to `$HOME/.local/bin`.\n\n## Getting Started\n\nCreate a new project using the komandan CLI:\n\n```bash\n# Create a new komandan project with scaffolded structure\nkomandan project new myproject\n\n# Navigate to the project directory\ncd myproject\n\n# Execute the main.lua script in the current directory\nkomandan .\n\n# Run in verbose mode to see detailed execution logs\nkomandan -v .\n```\n\nThis will create a new project directory with the following structure:\n- `komandan.json` - Project configuration file\n- `main.lua` - Main script where you define your automation tasks\n- `hosts.lua` - Host definitions and connection details\n\nYou can then edit `main.lua` to define your tasks and `hosts.lua` to configure your target servers.\n\nFor comprehensive documentation, including detailed guides and references, please visit the [Komandan Documentation Site](https://komandan.vercel.app/docs).\n\n\n\n## `komando` function\n\nThe `komando` function is the core of Komandan. It executes tasks on remote hosts via SSH. It takes two arguments:\n\n- `host`: A table containing the connection details for the target server:\n  - `address`: The IP address or hostname.\n  - `port`: The SSH port (default: 22).\n  - `user`: The username for authentication.\n  - `private_key_file`: The path to the SSH private key file.\n  - `private_key_pass`: The passphrase for the private key (if encrypted).\n  - `password`: The password for authentication (if not using key-based auth).\n- `task`: A table defining the task to be executed:\n  - `name`: A descriptive name for the task (optional, used for logging).\n  - `module`: A table specifying the module to use and its arguments.\n  - `ignore_exit_code`: Whether to ignore non-zero exit codes (default: `false`).\n  - `elevate`: Whether to run the task with elevated privileges (default: `false`).\n  - `as_user`: The user to run the task as when elevated (optional).\n  - `env`: A table of environment variables to set for the task (optional).\n\nThe `komando` function returns a table with the following fields:\n\n- `stdout`: The standard output of the executed command or script.\n- `stderr`: The standard error output.\n- `exit_code`: The exit code of the command or script.\n\n## Modules\n\nKomandan provides built-in modules for common tasks, accessible through the `komandan.modules` table. Here's a quick overview of the available modules:\n\n- **`cmd`**: Execute shell commands on the remote host.\n- **`script`**: Run scripts on the remote host, either from a local file or provided directly.\n- **`upload`**: Upload files to the remote host.\n- **`download`**: Download files from the remote host.\n- **`get_url`**: Download files from URLs.\n- **`apt`**: Manage packages on Debian/Ubuntu systems using `apt`.\n- **`dnf`**: Manage packages on Fedora/RHEL systems.\n- **`lineinfile`**: Insert or replace lines in a file.\n- **`file`**: Manage files and file properties.\n- **`template`**: Render a jinja template file on the remote host.\n- **`systemd_service`**: Manage systemd services on the remote host.\n- **`user`**: Manage system users.\n- **`postgresql_user`**: Manage PostgreSQL users.\n\nFor detailed explanations, arguments, and examples of each module, please refer to the [Modules section of the Komandan Documentation Site](https://komandan.vercel.app/docs/modules).\n\n## Built-in functions\n\nKomandan offers built-in functions to enhance scripting capabilities:\n\n- **`komandan.filter_hosts`**: Filters a list of hosts based on a pattern.\n- **`komandan.parse_hosts_json_file`**: Parses a JSON file containing hosts information.\n- **`komandan.parse_hosts_json_url`**: Parses a JSON file from a URL containing hosts information.\n\nFor detailed descriptions and usage examples of these functions, please visit the [Built-in Functions section of the Komandan Documentation Site](https://komandan.vercel.app/docs/functions/).\n\n## Default Values\n\nKomandan provides default values for various parameters, such as the user, private key file path, and SSH port. These values can be set using the `komandan.defaults` userdata.\n\n```lua\n-- set default values\nkomandan.defaults:set_port(22)\nkomandan.defaults:set_user(\"user1\")\nkomandan.defaults:set_private_key_file(os.getenv(\"HOME\") .. \"/.ssh/id_ed25519\")\nkomandan.defaults:set_private_key_pass(\"passphrase\")\nkomandan.defaults:set_host_key_check(false)\nkomandan.defaults:set_password(\"password\")\nkomandan.defaults:set_ignore_exit_code(false)\nkomandan.defaults:set_elevate(false)\nkomandan.defaults:set_elevation_method(\"sudo\")\nkomandan.defaults:set_as_user(\"root\")\nkomandan.defaults:set_known_hosts_file(os.getenv(\"HOME\") .. \"/.ssh/known_hosts\")\nkomandan.defaults:set_env(\"ENV_VAR\", \"value\")\nkomandan.defaults:remove_env(\"ENV_VAR\")\n\n-- get default values\nlocal port = komandan.defaults:get_port()\nlocal user = komandan.defaults:get_user()\nlocal private_key_file = komandan.defaults:get_private_key_file()\nlocal private_key_pass = komandan.defaults:get_private_key_pass()\nlocal host_key_check = komandan.defaults:get_host_key_check()\nlocal password = komandan.defaults:get_password()\nlocal ignore_exit_code = komandan.defaults:get_ignore_exit_code()\nlocal elevate = komandan.defaults:get_elevate()\nlocal elevation_method = komandan.defaults:get_elevation_method()\nlocal as_user = komandan.defaults:get_as_user()\nlocal known_hosts_file = komandan.defaults:get_known_hosts_file()\nlocal env = komandan.defaults:get_env(\"ENV_VAR\")\nlocal env_all = komandan.defaults:get_all_env()\n```\n\n## Parallel Execution\n\nKomandan supports parallel execution of tasks on multiple hosts using the `komando_parallel_hosts` function, and `komando_parallel_tasks` function for parallel execution of tasks on the same host.\n\n```lua\n-- parallel execution of a task on multiple hosts\nlocal hosts = {\n    {\n        name = \"server1\",\n        address = \"localhost\",\n        user = \"usertest\",\n        private_key_file = os.getenv(\"HOME\") .. \"/.ssh/id_ed25519\",\n    },\n    {\n        name = \"server2\",\n        address = \"localhost\",\n        user = \"usertest\",\n        private_key_file = os.getenv(\"HOME\") .. \"/.ssh/id_ed25519\",\n    },\n    {\n        name = \"server3\",\n        address = \"localhost\",\n        user = \"usertest\",\n        private_key_file = os.getenv(\"HOME\") .. \"/.ssh/id_ed25519\",\n    }\n}\n\nlocal task = {\n    name = \"Ping Google\",\n    komandan.modules.cmd({\n        cmd = \"ping google.com -c 5\",\n    }),\n}\n\nkomandan.komando_parallel_hosts(hosts, task)\n```\n\n```lua\n-- parallel execution of a task on the same host\nlocal host = {\n    name = \"My Server\",\n    address = \"localhost\",\n    user = \"usertest\",\n    private_key_file = os.getenv(\"HOME\") .. \"/.ssh/id_ed25519\",\n}\n\nlocal tasks = {\n    {\n        name = \"Task 1\",\n        komandan.modules.cmd({\n            cmd = \"uname -a\",\n        }),\n    },\n    {\n        name = \"Task 2\",\n        komandan.modules.cmd({\n            cmd = \"ping google.com -c 7\",\n        }),\n    },\n    {\n        name = \"Task 3\",\n        komandan.modules.apt({\n            package = \"neovim\",\n            update_cache = true\n        }),\n        elevate = true,\n    }\n}\n\nkomandan.komando_parallel_tasks(host, tasks)\n```\n\n## Error Handling\n\nKomandan provides error information through the return values of the `komando` function. If a task fails, the `exit_code` will be non-zero, and `stderr` may contain error messages. You can use the `ignore_exit_code` option in a task to continue execution even if a task fails.\n\nExample:\n\n```lua\nlocal result = komandan.komando(host, task)\n\nif result.exit_code ~= 0 then\n  print(\"Task failed with exit code: \" .. result.exit_code)\n  print(\"Error output: \" .. result.stderr)\nelse\n  print(\"Task succeeded!\")\n  print(\"Output: \" .. result.stdout)\nend\n```\n\n## Contributing\n\nContributions to Komandan are welcome! If you'd like to contribute, please follow these guidelines:\n\n1. Fork the repository on GitHub.\n2. Create a new branch for your feature or bug fix.\n3. Write your code and tests.\n4. Ensure your code passes all existing tests.\n5. Submit a pull request to the `main` branch.\n\nPlease report any issues or bugs on the [GitHub Issues](https://github.com/hahnavi/komandan/issues) page.\n\n## License\n\nKomandan is licensed under the [MIT License](LICENSE).\n\n## Full Documentation\n\nFor more detailed information, examples, and advanced usage, please visit the [Komandan Documentation Site](https://komandan.vercel.app/docs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhahnavi%2Fkomandan","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhahnavi%2Fkomandan","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhahnavi%2Fkomandan/lists"}