{"id":30353149,"url":"https://github.com/teabranch/matlas-cli","last_synced_at":"2026-05-03T11:37:48.426Z","repository":{"id":309241358,"uuid":"1025660492","full_name":"teabranch/matlas-cli","owner":"teabranch","description":"Go based CLI that allows users to communicate with both Mongo Atlas and Mongo Databases in 1 tool. There's also support for YAML style resource for a declarative  approach and finally a project discovery feature that finds out all the resource in a single project.","archived":false,"fork":false,"pushed_at":"2025-12-11T12:37:19.000Z","size":2317,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-12T07:26:23.606Z","etag":null,"topics":["atlas","cli","database","iac","infrastructure","mongo"],"latest_commit_sha":null,"homepage":"https://teabranch.github.io/matlas-cli/","language":"Go","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/teabranch.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":null,"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-07-24T15:41:17.000Z","updated_at":"2025-12-11T12:37:23.000Z","dependencies_parsed_at":"2025-08-10T19:45:21.954Z","dependency_job_id":"9493d1a0-9a3b-45db-8b9c-f9a661a04965","html_url":"https://github.com/teabranch/matlas-cli","commit_stats":null,"previous_names":["teabranch/matlas-cli"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/teabranch/matlas-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fmatlas-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fmatlas-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fmatlas-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fmatlas-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/teabranch","download_url":"https://codeload.github.com/teabranch/matlas-cli/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/teabranch%2Fmatlas-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32567879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"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":["atlas","cli","database","iac","infrastructure","mongo"],"created_at":"2025-08-19T01:21:11.276Z","updated_at":"2026-05-03T11:37:48.415Z","avatar_url":"https://github.com/teabranch.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Deploy Documentation](https://github.com/teabranch/matlas-cli/actions/workflows/docs.yml/badge.svg?branch=main)](https://github.com/teabranch/matlas-cli/actions/workflows/docs.yml)\n[![Release](https://github.com/teabranch/matlas-cli/actions/workflows/release.yml/badge.svg)](https://github.com/teabranch/matlas-cli/actions/workflows/release.yml)\n## 🚀 matlas — one CLI for Atlas and MongoDB\n\n\u003e 🌟 **The unified, Go-powered CLI that bridges MongoDB Atlas management and database operations**\n\nMatlas is your **all-in-one command center** for MongoDB Atlas and database management. Think of it as the friendly bridge between the Atlas SDK and the MongoDB Go Driver — spin up projects and clusters, configure network access, and seamlessly dive into database tasks like listing collections or inspecting indexes, all from a single, powerful tool! ⚡\n\n### 💡 Why we built it\n- 🔄 **Context switching hurts**: Cloud management lives in one world (Atlas APIs), while day‑to‑day database tasks live in another (drivers and shells). We wanted both, together.\n- 🧠 **A single mental model**: One set of flags, one config, one output style for both Atlas and database operations.\n- ⚡ **Grease the path**: From \"create a cluster\" to \"inspect collections\" in seconds — no hunting for another CLI.\n\n### 🎯 Inspired by Terraform and kubectl: meet Discover\nWe love how Terraform plans changes before applying, and how kubectl lets you declare desired state. Matlas combines those vibes:\n\n- 📸 **Discover**: Snapshot your Atlas org/project (and optionally databases) into clean YAML:\n  ```bash\n  matlas discover --project-id \u003cid\u003e -o atlas.yaml --include-databases\n  ```\n- 🔍 **Plan/Diff**: Treat that YAML as your desired state, compare it to reality:\n  ```bash\n  matlas infra plan -f atlas.yaml\n  matlas infra diff -f atlas.yaml\n  ```\n- 🚀 **Apply (dry-run first)**: Roll changes out, Terraform‑style:\n  ```bash\n  matlas infra -f atlas.yaml --dry-run\n  matlas infra -f atlas.yaml --auto-approve\n  ```\n\n✨ Matlas doesn't try to be Terraform or kubectl. It borrows the best ideas so Atlas work feels **safe**, **reviewable**, and **repeatable** — and it keeps database tasks close at hand.\n\n## 🛠️ What you can do\n\n| Feature | Description |\n|---------|-------------|\n| 🌐 **Atlas** | List/get/create/update/delete projects, clusters, users, network access, peering, and network containers |\n| 🔍 **Atlas Search** | Create and manage Atlas Search indexes for full-text and vector search capabilities |\n| 🔗 **VPC Endpoints** | Configure VPC endpoints and Private Link connections for secure Atlas connectivity |\n| 🗄️ **Databases** | List/create/delete databases, collections, and indexes — either via connection string or Atlas cluster reference |\n| 👥 **Database Users** | Create/list/update/delete database-specific users with custom roles — via connection string or Atlas cluster reference |\n| 📋 **Infra** | Discover current state, plan/diff/apply/destroy via declarative YAML |\n\n## 📦 Installation\n\n### ⚡ Quick Install (Recommended)\n\n**macOS \u0026 Linux:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/teabranch/matlas-cli/main/install.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\nInvoke-WebRequest -Uri \"https://raw.githubusercontent.com/teabranch/matlas-cli/main/install.ps1\" -OutFile \"install.ps1\"; .\\install.ps1\n```\n\n### 📋 Platform-Specific Installation\n\n#### macOS \u0026 Linux\n\n**Using the installation script:**\n```bash\n# Download and run installer\ncurl -fsSL https://raw.githubusercontent.com/teabranch/matlas-cli/main/install.sh -o install.sh\nchmod +x install.sh\n./install.sh\n\n# Install specific version\n./install.sh --version v1.2.3\n\n# Install to custom directory (no sudo required)\n./install.sh --dir ~/.local/bin\n\n# Install to user directory via environment variable\nMATLAS_INSTALL_DIR=~/.local/bin ./install.sh\n```\n\n**Manual installation:**\n1. Download the latest release from [GitHub Releases](https://github.com/teabranch/matlas-cli/releases)\n2. Extract the archive: `tar -xzf matlas-*.tar.gz`\n3. Move binary to PATH: `sudo mv matlas /usr/local/bin/`\n4. Make executable: `sudo chmod +x /usr/local/bin/matlas`\n\n#### Windows\n\n**Using PowerShell (Recommended):**\n```powershell\n# Download installer\nInvoke-WebRequest -Uri \"https://raw.githubusercontent.com/teabranch/matlas-cli/main/install.ps1\" -OutFile \"install.ps1\"\n\n# Run installer (may require Administrator privileges)\n.\\install.ps1\n\n# Install specific version\n.\\install.ps1 -Version v1.2.3\n\n# Install to user directory (no admin required)\n.\\install.ps1 -InstallDir \"$env:USERPROFILE\\matlas\"\n\n# Skip automatic PATH setup\n.\\install.ps1 -NoPathSetup\n```\n\n**Manual installation:**\n1. Download the Windows release from [GitHub Releases](https://github.com/teabranch/matlas-cli/releases)\n2. Extract the ZIP file\n3. Move `matlas.exe` to a directory in your PATH (e.g., `C:\\Program Files\\matlas\\`)\n4. Add the directory to your system PATH if needed\n\n### 🛠️ Build from Source\n\n**Prerequisites:**\n- 🐹 **Go 1.24+** required\n\n```bash\n# Clone the repository\ngit clone https://github.com/teabranch/matlas-cli.git\ncd matlas-cli\n\n# Quick build\nmake build\n\n# Or manually\ngo build -o bin/matlas ./...\n\n# Cross-compile for all platforms\n./scripts/build/build.sh cross\n```\n\n### 🗑️ Uninstallation\n\n**macOS \u0026 Linux:**\n```bash\n# Download and run uninstaller\ncurl -fsSL https://raw.githubusercontent.com/teabranch/matlas-cli/main/uninstall.sh | bash\n\n# Or manually\nsudo rm /usr/local/bin/matlas\nrm -rf ~/.matlas  # Remove config directory\n```\n\n**Windows:**\n```powershell\n# Download and run uninstaller\nInvoke-WebRequest -Uri \"https://raw.githubusercontent.com/teabranch/matlas-cli/main/uninstall.ps1\" -OutFile \"uninstall.ps1\"; .\\uninstall.ps1\n\n# Or manually remove\nRemove-Item \"C:\\Program Files\\matlas\\matlas.exe\"  # Adjust path as needed\nRemove-Item -Recurse -Force \"$env:USERPROFILE\\.matlas\"  # Remove config\n```\n\n### ✅ Verify Installation\n\nAfter installation, verify that matlas is working:\n\n```bash\n# Check if matlas is in PATH\nmatlas --version\n\n# Show help\nmatlas --help\n\n# Check configuration\nmatlas config --help\n```\n\n### 🔄 Upgrading\n\n**Quick upgrade to latest version:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/teabranch/matlas-cli/main/upgrade.sh | bash\n```\n\n**Advanced upgrade options:**\n```bash\n# Download upgrade script\ncurl -fsSL https://raw.githubusercontent.com/teabranch/matlas-cli/main/upgrade.sh -o upgrade.sh\nchmod +x upgrade.sh\n\n# Upgrade to latest version\n./upgrade.sh\n\n# Upgrade to specific version\n./upgrade.sh --version v1.2.3\n\n# Force reinstall current version\n./upgrade.sh --force\n```\n\n### 🔧 Installation Options\n\n| Method | Pros | Cons | Requires Admin |\n|--------|------|------|----------------|\n| **Quick Install** | Easy, automatic PATH setup | Requires internet | System dirs: Yes |\n| **Installation Script** | Customizable, version selection | Requires download | System dirs: Yes |\n| **Manual Install** | Full control | Manual PATH setup | System dirs: Yes |\n| **Build from Source** | Latest features, customizable | Requires Go toolchain | No |\n\n### 📁 Installation Directories\n\n**Default locations:**\n- **macOS/Linux**: `/usr/local/bin` (system-wide) or `~/.local/bin` (user)\n- **Windows**: `C:\\Program Files\\matlas` (system-wide) or `%USERPROFILE%\\matlas` (user)\n\n**Custom installation:**\n- Set `MATLAS_INSTALL_DIR` environment variable\n- Use `--dir` (Unix) or `-InstallDir` (Windows) flag\n\n### 🐚 Shell Integration\n\nThe installer automatically adds matlas to your PATH and detects your shell:\n\n- **Bash**: Updates `~/.bashrc` or `~/.bash_profile`\n- **Zsh**: Updates `~/.zshrc`\n- **Fish**: Updates `~/.config/fish/config.fish`\n- **PowerShell**: Updates user PATH environment variable\n\nTo manually add to PATH:\n```bash\n# Bash/Zsh\necho 'export PATH=\"/usr/local/bin:$PATH\"' \u003e\u003e ~/.bashrc\n\n# Fish\necho 'set -gx PATH /usr/local/bin $PATH' \u003e\u003e ~/.config/fish/config.fish\n\n# PowerShell\n$env:PATH += \";C:\\Program Files\\matlas\"\n```\n\n## 🔐 Authenticate\n\n### Environment Variables\n```bash\nexport ATLAS_PUB_KEY=\"your-public-key\"\nexport ATLAS_API_KEY=\"your-api-key\"\n# Optional\nexport ATLAS_PROJECT_ID=\"your-project-id\"\nexport ATLAS_ORG_ID=\"your-org-id\"\n```\n\n### YAML Configuration\nCreate `~/.matlas/config.yaml`:\n```yaml\napiKey: your-api-key\npublicKey: your-public-key\nprojectId: your-project-id  # optional\norgId: your-org-id          # optional\noutput: json                # optional\ntimeout: 30s                # optional\n```\n\n### Command Line Flags\n```bash\nmatlas --api-key \u003ckey\u003e --pub-key \u003ckey\u003e --project-id \u003cid\u003e --org-id \u003cid\u003e [command]\n```\n\n## 🚀 Quick start\n\n### Atlas Management\n```bash\n# List projects\nmatlas atlas projects list --org-id \u003cid\u003e\n\n# Get a specific project  \nmatlas atlas projects get --project-id \u003cid\u003e\n\n# List database users\nmatlas atlas users list --project-id \u003cid\u003e\n\n# Create Atlas user with password display (optional)\nmatlas atlas users create --project-id \u003cid\u003e --username testuser --show-password \\\n  --roles \"readWriteAnyDatabase\" --scopes \"cluster1,cluster2\"\n\n# List network access rules\nmatlas atlas network list --project-id \u003cid\u003e\n\n# List Atlas Search indexes\nmatlas atlas search list --project-id \u003cid\u003e --cluster \u003cname\u003e\n\n# Create a basic search index\nmatlas atlas search create --project-id \u003cid\u003e --cluster \u003cname\u003e \\\n  --database \u003cdb\u003e --collection \u003ccoll\u003e --name \u003cindex-name\u003e --type search\n\n# Create VPC endpoint\nmatlas atlas vpc-endpoints create --project-id \u003cid\u003e --provider AWS \\\n  --region us-east-1 --service-name com.amazonaws.vpce.us-east-1.vpce-svc-123\n```\n\n### 🗄️ Database Operations\n```bash\n# List databases (via connection string)\nmatlas database list --connection-string \"mongodb+srv://...\"\n\n# List databases (via Atlas cluster)\nmatlas database list --cluster \u003cname\u003e --project-id \u003cid\u003e --use-temp-user\n\n# List collections in a database\nmatlas database collections list --connection-string ... --database mydb\n\n# List indexes in a collection\nmatlas database collections indexes list \\\n  --connection-string ... \\\n  --database mydb \\\n  --collection mycoll\n\n# Database user management\nmatlas database users list --connection-string ... --database mydb\nmatlas database users create --cluster \u003cname\u003e --project-id \u003cid\u003e --use-temp-user \\\n  --database mydb --username testuser --password \"securepass\" --roles \"readWrite\"\n\n# Database custom roles management  \nmatlas database roles list --cluster \u003cname\u003e --project-id \u003cid\u003e --use-temp-user --database mydb\nmatlas database roles create --cluster \u003cname\u003e --project-id \u003cid\u003e --use-temp-user \\\n  --database mydb --role-name \"customRole\" --privileges '...'\n```\n\n### 📋 Declarative Infrastructure Workflows\n```bash\n# 🔍 Discover current state\nmatlas discover --project-id \u003cid\u003e -o atlas.yaml --include-databases --convert-to-apply\n\n# 📊 Plan and preview changes\nmatlas infra plan -f config.yaml\nmatlas infra diff -f config.yaml\n\n# 🚀 Apply changes (with safety checks)\nmatlas infra -f config.yaml --dry-run              # Preview first\nmatlas infra -f config.yaml --auto-approve         # Apply changes\n\n# 📸 Show current state\nmatlas infra show --project-id \u003cid\u003e\n\n# 🗑️ Destroy resources\nmatlas infra destroy -f config.yaml                # From config\nmatlas infra destroy --discovery-only --project-id \u003cid\u003e  # Discovery only\n```\n\n## ⚙️ Configuration\n\n### Configuration Priority (highest to lowest)\n1. 🏗️ **Built-in defaults**\n2. 📄 **YAML file**: `~/.matlas/config.yaml` or `--config` / `ATLAS_CONFIG_FILE`\n3. 🌍 **Environment variables**: `ATLAS_*` prefix (e.g., `ATLAS_OUTPUT`, `ATLAS_TIMEOUT`)\n4. 🚩 **Command flags**: `--api-key`, `--project-id`, etc.\n\n### 🔑 Credentials Resolution\nMatlas looks for credentials in this order:\n1. Command flags/YAML config\n2. Environment variables (`ATLAS_API_KEY`, `ATLAS_PUB_KEY`)\n3. Platform-specific secure storage:\n   - **macOS**: Keychain (`security` command)\n   - **Windows**: Credential Manager (PowerShell)\n   - **Linux**: secret-service (`secret-tool` or GNOME Keyring)\n\n## 🐚 Shell Completion\nEnable auto-completion for your shell:\n```bash\n# Choose your shell\nmatlas completion bash | sudo tee /etc/bash_completion.d/matlas\nmatlas completion zsh \u003e ~/.zsh/completions/_matlas\nmatlas completion fish \u003e ~/.config/fish/completions/matlas.fish\nmatlas completion powershell \u003e matlas.ps1\n```\n\n## 📚 Learn More\n\n| Topic | Documentation |\n|-------|---------------|\n| 🌐 **Atlas Commands** | [`docs/atlas.md`](docs/atlas.md) |\n| 🗄️ **Database Commands** | [`docs/database.md`](docs/database.md) |\n| 📋 **Infrastructure Workflows** | [`docs/infra.md`](docs/infra.md) |\n| 🔐 **Authentication \u0026 Config** | [`docs/auth.md`](docs/auth.md) |\n| 📖 **YAML Configuration** | [`docs/yaml-kinds.md`](docs/yaml-kinds.md) |\n| 🔍 **Discovery Workflows** | [`docs/discovery.md`](docs/discovery.md) |\n\n## 🛠️ Development\n\n### Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](.github/CONTRIBUTING.md) for:\n- Development setup\n- Pull request process\n- Commit message guidelines (Conventional Commits)\n- Code style standards\n- Testing requirements\n- Feature development workflow\n\n**Important:** This repository uses **squash merge only**. All PRs are squashed into a single commit following [Conventional Commits](https://www.conventionalcommits.org/) format for automated versioning and releases.\n\n### Commands\n```bash\n# Run tests\nmake test                    # See scripts/test/*.sh for details\n\n# Code quality  \nmake lint                    # Lint code\nmake fmt                     # Format code\n\n# Generate mocks\nmake generate-mocks         # Update test mocks\n\n# Installation (for development)\nmake install                # Install to /usr/local/bin (requires sudo)\nmake install-user          # Install to ~/.local/bin (no sudo)\nmake uninstall             # Remove installation\n```\n\n### Feature tracking\nCreate a brief, per-feature summary in `features/` using the provided template. This helps reviewers and users understand what was achieved and where it was wired end-to-end (CLI + YAML ApplyDocument).\n\n```bash\ncp features/TEMPLATE.md features/$(date +%F)-\u003cshort-slug\u003e.md\n```\n\n## ⚠️ Current Limitations\n- 🔧 **Advanced Configuration**: Some complex cluster configurations (ReplicationSpecs, AutoScaling) require manual Atlas console setup\n\n## 📄 License\n**MIT License** - see [`LICENSE`](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ for the MongoDB community**\n\n[⭐ Star this repo](https://github.com/teabranch/matlas-cli) • [🐛 Report issues](https://github.com/teabranch/matlas-cli/issues) • [💡 Request features](https://github.com/teabranch/matlas-cli/issues/new)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteabranch%2Fmatlas-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fteabranch%2Fmatlas-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fteabranch%2Fmatlas-cli/lists"}