{"id":25860114,"url":"https://github.com/aashari/rag-aws-ssm-command","last_synced_at":"2025-03-01T21:54:04.326Z","repository":{"id":279897962,"uuid":"940126470","full_name":"aashari/rag-aws-ssm-command","owner":"aashari","description":"A utility for executing shell commands and transferring files to AWS EC2 instances via Systems Manager (SSM) with enhanced output formatting, part of the RAG tool suite","archived":false,"fork":false,"pushed_at":"2025-02-28T13:56:05.000Z","size":91,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T19:48:04.167Z","etag":null,"topics":["automation","aws-ec2","aws-ssm","bun","cli-tool","devops","file-transfer","rag-tools","typescript"],"latest_commit_sha":null,"homepage":"https://github.com/aashari/rag-aws-ssm-command#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aashari.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-02-27T16:53:15.000Z","updated_at":"2025-02-28T13:56:01.000Z","dependencies_parsed_at":"2025-02-28T19:48:07.259Z","dependency_job_id":null,"html_url":"https://github.com/aashari/rag-aws-ssm-command","commit_stats":null,"previous_names":["aashari/aws-send-ssm-command","aashari/rag-aws-ssm-command"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Frag-aws-ssm-command","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Frag-aws-ssm-command/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Frag-aws-ssm-command/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aashari%2Frag-aws-ssm-command/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aashari","download_url":"https://codeload.github.com/aashari/rag-aws-ssm-command/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241430319,"owners_count":19961635,"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":["automation","aws-ec2","aws-ssm","bun","cli-tool","devops","file-transfer","rag-tools","typescript"],"created_at":"2025-03-01T21:54:03.422Z","updated_at":"2025-03-01T21:54:04.311Z","avatar_url":"https://github.com/aashari.png","language":"TypeScript","readme":"# rag-aws-ssm-command\n\n**AWS SSM Command and File Transfer Tool for Humans and AI**\n\n`rag-aws-ssm-command` is a utility built with the [AWS SDK](https://aws.amazon.com/sdk-for-javascript/) to send shell commands and transfer files to AWS EC2 instances via Systems Manager (SSM). It provides detailed output formatting and supports both CLI usage for direct operations and potential AI integration (though primarily CLI-focused in this version). Ideal for developers managing EC2 instances and AI systems automating AWS workflows.\n\n- **Version**: 2.1.1\n- **License**: Open-source (MIT, see [LICENSE](LICENSE))\n- **Repository**: [github.com/aashari/rag-aws-ssm-command](https://github.com/aashari/rag-aws-ssm-command) _(Update with actual repo URL)_\n- **Author**: Andi Ashari\n\n---\n\n## Features\n\n- **Command Execution**: Run shell commands on EC2 instances via SSM.\n- **File Transfer**: Upload local files to remote EC2 instances with base64 encoding.\n- **Sudo Support**: Execute commands or write files with elevated privileges.\n- **Wait Option**: Poll for command completion with detailed status reporting.\n- **Output Formatting**: Rich, human-readable output with metadata and error suggestions.\n- **Runtime**: Optimized for [Bun](https://bun.sh/), with Node.js/npm compatibility.\n\n---\n\n## Installation\n\n### Prerequisites\n\n- **Bun** (recommended): `curl -fsSL https://bun.sh/install | bash`\n- **Node.js** (optional): Version 16+ with npm\n- **AWS Credentials**: Configured via `~/.aws/credentials` or environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`).\n\n### Running the Tool\n\nRun directly from GitHub using `bunx` or `npx`:\n\n```bash\n# Using Bun (Recommended)\nbunx github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --command \"df -h\"\n\n# Using Node.js/npm\nnpx -y github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --command \"df -h\"\n```\n\n### Installing Locally\n\nIf you prefer to install the tool locally without publishing to npm, you have two simple options:\n\n#### Option 1: Install Directly from GitHub\n\nThis is the easiest way to install the tool globally on your machine:\n\n```bash\n# Using Bun (Recommended)\nbun install -g github:aashari/rag-aws-ssm-command\n\n# Using npm\nnpm install -g github:aashari/rag-aws-ssm-command\n```\n\nAfter installation, you can run it directly:\n\n```bash\nrag-aws-ssm-command --target i-0123456789abcdef0 --command \"df -h\"\n```\n\n#### Option 2: Clone and Install Locally\n\nFor development or customization:\n\n```bash\n# Clone the repository\ngit clone https://github.com/aashari/rag-aws-ssm-command.git\ncd rag-aws-ssm-command\n\n# Install dependencies\nbun install  # or npm install\n\n# Build the project\nnpm run build\n\n# Link the package globally\nbun link     # or npm link\n```\n\nAfter linking, you can run it directly:\n\n```bash\nrag-aws-ssm-command --target i-0123456789abcdef0 --command \"df -h\"\n```\n\n---\n\n## Usage\n\n### CLI Mode\n\nExecute commands or transfer files to EC2 instances.\n\n#### Run a Command\n\n```bash\n# Using Bun\nbunx github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --command \"df -h\"\n\n# Using Node.js/npm\nnpx -y github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --command \"df -h\"\n```\n\n**Output**: Disk usage info with execution metadata.\n\n#### Transfer a File\n\n```bash\nbunx github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --local-file ./myfile.txt --remote-file /home/ec2-user/myfile.txt\n```\n\n**Output**: File transfer status and metadata.\n\n#### Run a Command with Sudo\n\n```bash\nbunx github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --command \"apt update\" --sudo\n```\n\n**Output**: Command output with sudo execution details.\n\n#### Transfer a File to a Protected Directory\n\n```bash\nbunx github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --local-file ./nginx.conf --remote-file /etc/nginx/nginx.conf --sudo\n```\n\n**Output**: File transfer confirmation with sudo privileges.\n\n#### CLI Options\n\n| Option          | Description                          | Example Value               |\n| --------------- | ------------------------------------ | --------------------------- |\n| `--target`      | EC2 instance ID (required)           | `i-0123456789abcdef0`       |\n| `--command`     | Bash command to run                  | `\"df -h\"`                   |\n| `--local-file`  | Local file to upload                 | `./myfile.txt`              |\n| `--remote-file` | Remote destination path              | `/home/ec2-user/myfile.txt` |\n| `--sudo`        | Use sudo privileges                  | (flag)                      |\n| `--wait`        | Wait for completion (default: true)  | (flag)                      |\n| `--region`      | AWS region (default: ap-southeast-1) | `us-west-2`                 |\n\n---\n\n## ForHumans\n\n### Why Use rag-aws-ssm-command?\n\n- **Simplify EC2 Management**: Execute commands or deploy files without SSH.\n- **Detailed Feedback**: Rich output with timestamps, status, and error suggestions.\n- **Secure Operations**: Leverages AWS SSM for secure, credential-free access.\n\n### Example Workflow\n\n1. Check disk space:\n   ```bash\n   bunx github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --command \"df -h\"\n   ```\n2. Deploy a config file:\n   ```bash\n   bunx github:aashari/rag-aws-ssm-command --target i-0123456789abcdef0 --local-file ./app.conf --remote-file /etc/app/app.conf --sudo\n   ```\n3. Review detailed output for success or troubleshooting.\n\n---\n\n## ForAI\n\n### Integration with AI Systems\n\n`rag-aws-ssm-command` provides structured output suitable for AI system integration. The tool's consistent output format and error handling make it ideal for automated workflows and AI-driven infrastructure management.\n\n### Capabilities\n\n- **Command Execution**: Run any shell command with status tracking.\n- **File Deployment**: Transfer files securely via base64 encoding.\n- **Error Handling**: Detailed error messages and suggestions for resolution.\n\n---\n\n## Roadmap\n\nFuture enhancements planned for `rag-aws-ssm-command`:\n\n1. **MCP Integration**: Add support for Model Control Protocol (MCP) server integration for seamless AI system communication.\n2. **Batch Operations**: Support for executing commands across multiple instances simultaneously.\n3. **Interactive Mode**: Shell-like interactive mode for running multiple commands in sequence.\n4. **Output Templates**: Customizable output formatting templates.\n5. **Enhanced AI Features**: \n   - Structured JSON output mode\n   - AI-friendly error formats\n   - Context-aware command suggestions\n6. **Security Enhancements**:\n   - Command allowlist/blocklist\n   - Enhanced IAM role support\n   - Command audit logging\n\n---\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── commands/    # Command execution and file transfer logic\n├── services/    # AWS SSM client utilities\n├── types/       # TypeScript type definitions\n├── utils/       # Formatting, error handling, file operations\n└── index.ts     # Main entry point\n```\n\n### Build and Run Locally\n\n```bash\nbun install\nbun run src/index.ts --target i-0123456789abcdef0 --command \"uptime\"\n```\n\n### Contributing\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/add-feature`).\n3. Commit changes (`git commit -m \"Add new feature\"`).\n4. Push to the branch (`git push origin feature/add-feature`).\n5. Open a Pull Request.\n\n---\n\n## Troubleshooting\n\n- **Error: \"InvalidInstanceId\"**: Verify the instance ID and ensure SSM Agent is running.\n- **Error: \"AccessDeniedException\"**: Check IAM permissions (`ssm:SendCommand`, `ssm:GetCommandInvocation`).\n- **No Output**: Use `--wait` and check SSM Agent status on the instance.\n\nFile issues at [github.com/aashari/rag-aws-ssm-command/issues](https://github.com/aashari/rag-aws-ssm-command/issues).\n\n---\n\n## License\n\nMIT © Andi Ashari. See [LICENSE](LICENSE) for details.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faashari%2Frag-aws-ssm-command","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faashari%2Frag-aws-ssm-command","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faashari%2Frag-aws-ssm-command/lists"}