{"id":22972707,"url":"https://github.com/datum-cloud/datumctl","last_synced_at":"2026-04-10T00:04:08.324Z","repository":{"id":267848500,"uuid":"902543182","full_name":"datum-cloud/datumctl","owner":"datum-cloud","description":"A CLI for interacting with Datum Cloud","archived":false,"fork":false,"pushed_at":"2025-03-13T01:33:08.000Z","size":84,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-11T20:47:19.073Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datum-cloud.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2024-12-12T19:17:52.000Z","updated_at":"2025-04-11T19:01:59.000Z","dependencies_parsed_at":"2024-12-12T20:35:54.859Z","dependency_job_id":"4672e8a2-68c8-495c-9579-a30c8b2c534f","html_url":"https://github.com/datum-cloud/datumctl","commit_stats":null,"previous_names":["datum-cloud/datumctl"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdatumctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdatumctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdatumctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datum-cloud%2Fdatumctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datum-cloud","download_url":"https://codeload.github.com/datum-cloud/datumctl/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249752018,"owners_count":21320413,"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":[],"created_at":"2024-12-14T23:18:46.194Z","updated_at":"2026-04-10T00:04:08.312Z","avatar_url":"https://github.com/datum-cloud.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# datumctl: The Datum Cloud CLI\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n\n`datumctl` is the official command-line interface for interacting with [Datum Cloud](https://www.datum.net), the connectivity infrastructure platform designed to unlock networking superpowers for developers and forward-thinking companies.\n\nUse `datumctl` to manage your Datum Cloud resources, authenticate securely, and integrate with tools like `kubectl`.\n\n## Features\n\n*   **Secure Authentication:** Uses modern OAuth 2.0 and OIDC PKCE flow for secure, browser-based login. No static API keys required.\n*   **Multi-User Support:** Manage credentials for multiple Datum Cloud user accounts.\n*   **Resource Management:** Interact with Datum Cloud resources (e.g., list organizations).\n*   **Kubernetes Integration:** Seamlessly configure `kubectl` to use your Datum Cloud credentials for accessing Kubernetes clusters.\n*   **MCP Server (optional):** Start an MCP server (`datumctl mcp`) for Datum Cloud so AI agents (e.g., Claude) can discover resources, inspect schemas, validate manifests, and perform CRUD operations via server-side dry-run.\n*   **Cross-Platform:** Pre-built binaries available for Linux, macOS, and Windows.\n\n## Getting Started\n\n### Installation\n\nSee the [Installation Guide](https://www.datum.net/docs/quickstart/datumctl/) for detailed instructions, including Homebrew for macOS, nix for Linux and macOS, and pre-built binaries for all platforms.\n\n### Basic Usage\n\n1.  **Log in to Datum Cloud:**\n    ```bash\n    datumctl auth login\n    ```\n    (This will open your web browser to complete authentication.)\n\n2.  **List your organizations:**\n    ```bash\n    datumctl get organizations\n    ```\n\n3.  **Configure `kubectl` access (optional):**\n    Use the organization ID (or a specific project ID) from the previous step\n    to configure `kubectl`.\n    ```bash\n    # Example using an organization ID\n    datumctl auth update-kubeconfig --organization \u003corg-id\u003e\n\n    # Example using a project ID\n    datumctl auth update-kubeconfig --project \u003cproject-id\u003e\n    ```\n    Now you can use `kubectl` to interact with your Datum Cloud control plane.\n\n### MCP Setup\n\nMCP can target either an **organization** or **project** control plane. For maximum flexibility, we recommend starting with an organization context.\n\n**A) If you already have a project:**\n```bash\n# Ensure your kube context points at an organization control plane\ndatumctl auth update-kubeconfig --organization \u003corg-id\u003e\n\n# List projects; copy the NAME column (that is the Project ID)\nkubectl get projects\n# Or JSON-friendly:\nkubectl get projects -o jsonpath='{range .items[*]}{.metadata.name}{\"\\n\"}{end}'\n```\n\n**B) If you need to create a project:**\n```bash\n# Make sure your kube context targets an organization control plane\ndatumctl auth update-kubeconfig --organization \u003corg-id\u003e\n\ncat \u003e intro-project.yaml \u003c\u003c'YAML'\napiVersion: resourcemanager.miloapis.com/v1alpha1\nkind: Project\nmetadata:\n  generateName: intro-project-\nspec: {}\nYAML\n\nkubectl create -f intro-project.yaml\n\n# Wait until Ready\nPRJ_ID=\"$(kubectl get projects -o jsonpath='{.items[-1:].metadata.name}')\"\nkubectl wait --for=condition=Ready --timeout=15m project/$PRJ_ID\necho \"Project ready: $PRJ_ID\"\n```\n\n#### MCP subcommand (optional)\n\nStart the Model Context Protocol (MCP) server targeting a specific Datum Cloud context:\n```bash\n# Exactly one of --organization or --project is required.\ndatumctl mcp --organization \u003corg-id\u003e --namespace \u003cns\u003e [--port 8080]\n# or\ndatumctl mcp --project \u003cproject-id\u003e --namespace \u003cns\u003e [--port 8080]\n```\n\n##### Available Tools\n\n- **Discovery:** `list_crds`, `get_crd` - Discover and inspect Custom Resource Definitions\n- **Validation:** `validate_yaml` - Validate manifests via server-side dry-run\n- **Context:** `change_context` - Switch between organization and project contexts\n- **CRUD Operations:** `create_resource`, `get_resource`, `update_resource`, `delete_resource`, `list_resources`\n- **Safety:** All write operations default to dry-run mode; use `dryRun: false` to apply changes\n\n##### Startup \u0026 safety\n\n- **Preflight:** On startup, `datumctl mcp` verifies connectivity and auth by calling Kubernetes discovery (e.g., `GET /version`). If this check fails, the server exits.\n- **Dry-run by default:** All write operations use server-side dry-run (`dryRun=true`) by default for safety.\n\n\u003e [!NOTE]\n\u003e The MCP server builds its own Kubernetes connection for the selected Datum context; it does **not** depend on your local kubeconfig or `--kube-context`. Provide either `--organization` or `--project`.\n\n##### Scope: organization vs. project\n\n\u003e [!IMPORTANT]\n\u003e **Organization scope** provides access to all projects within the organization and allows switching between them using `change_context`.  \n\u003e **Project scope** provides direct access to project-specific resources but limits visibility to that single project.\n\n**Recommended (organization scope)**\n```bash\ndatumctl mcp --organization \u003corg-id\u003e --namespace \u003cns\u003e [--port 8080]\n```\n\n##### Claude config (macOS)\n```json\n{\n  \"mcpServers\": {\n    \"datum_mcp\": {\n      \"command\": \"/absolute/path/to/datumctl\",\n      \"args\": [\"mcp\", \"--organization\", \"your-org-id\", \"--namespace\", \"default\"]\n    }\n  }\n}\n```\n\n**Project scope (alternative)**\n```bash\ndatumctl mcp --project \u003cproject-id\u003e --namespace \u003cns\u003e [--port 8080]\n```\n\n**HTTP debug (if `--port` is set):**\n```bash\n# List CRDs\ncurl -s localhost:8080/datum/list_crds | jq\n\n# List resources\ncurl -s localhost:8080/datum/list_resources -H 'Content-Type: application/json' -d '{\"kind\":\"Project\"}' | jq\n\n# Validate a YAML file (wrap safely into JSON)\nprintf '{\"yaml\":%s}\\n' \"$(jq -Rs . \u003c/path/to/file.yaml)\" | curl -s -X POST localhost:8080/datum/validate_yaml -H 'Content-Type: application/json' -d @- | jq\n```\n\nFor more detailed tool setup instructions, refer to the official\n[Set Up Tools](https://docs.datum.net/docs/tasks/tools/) guide on docs.datum.net.\n\n## Documentation\n\nFor comprehensive user and developer guides, including detailed command references and authentication flow explanations, please see the [**Documentation**](./docs/README.md).\n\n## Contributing\n\nContributions are welcome! Please refer to the contribution guidelines (link to be added) for more information.\n\n## License\n\n`datumctl` is licensed under the Apache License, Version 2.0. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatum-cloud%2Fdatumctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatum-cloud%2Fdatumctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatum-cloud%2Fdatumctl/lists"}