mtncloud-cli 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 639203a2d4abce5fa9f74f710a71dd159f38c775dcd009549aba64fe5de773c9
+  data.tar.gz: d598611f41e31e3546003dd12db8e84be2c4cc5e1a440bb8fb51b78d5f21dc23
+SHA512:
+  metadata.gz: e2b6e6aea6578305035081434b24ce671a43df0ccd0760bf2813a7dbea54c932382d37f002f1ad32ede689bd9f34c956f04d6126b9cb78625b48cfca468a2971
+  data.tar.gz: 0aec3580475e9814d229695f76d89f3f254a7111831367b4f26fb049c695b441e708049a951da5d2938e193359ba30912c9cf9c208e5cd84a6e09fe3a280f9f0

data/.dockerignore

@@ -0,0 +1,20 @@
+# Keep local and generated files out of the Docker build context.
+# Do NOT add .git here: the gem build uses `git ls-files` to list its files.
+# Only exclude files that are not tracked by git, or the gem build will fail.
+
+# test credentials for the live appliance tests
+test_config.yaml
+
+# built gems and bundler state
+*.gem
+pkg
+.bundle
+Gemfile.lock
+
+# temporary and editor files
+tmp
+coverage
+*.log
+.idea
+.vscode
+.DS_Store

data/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## What this changes
+
+<!-- What does this pull request change, and why? -->
+
+## How it was tested
+
+<!-- For example: bundle exec rake test:offline, or commands you ran against an appliance -->
+
+## Checklist
+
+- [ ] `bundle exec rake test:offline` passes
+- [ ] Tests added or updated for the changed behaviour
+- [ ] README updated if installation, configuration or usage changed
+- [ ] Customer-facing text says MTN Cloud, not Morpheus

data/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+# Runs on every pull request and every push to main.
+# main is protected: a pull request can only be merged when every job here passes.
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Offline tests (Ruby ${{ matrix.ruby }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.3", "3.4", "4.0"]
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run offline tests
+        run: bundle exec rake test:offline
+
+  build:
+    name: Build gem
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+
+      - name: Build the gem
+        run: gem build mtncloud-cli.gemspec
+
+  # One check for branch protection to require, so the protection rule does not
+  # need to change when the Ruby versions above change.
+  ci-passed:
+    name: CI passed
+    if: always()
+    needs: [test, build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail unless every job passed
+        run: |
+          echo "test: ${{ needs.test.result }}, build: ${{ needs.build.result }}"
+          [ "${{ needs.test.result }}" = "success" ] && [ "${{ needs.build.result }}" = "success" ]

data/.github/workflows/release.yml

@@ -0,0 +1,46 @@
+# Publishes the mtncloud-cli gem to RubyGems.org when a version tag is pushed.
+#
+# Release a new version:
+#   1. Bump VERSION in lib/mtncloud/cli/version.rb and push to main.
+#   2. git tag v<version> && git push origin v<version>
+#
+# Uses RubyGems trusted publishing, so no API key is stored in this repository.
+# RubyGems.org must list this repository, this workflow file (release.yml)
+# and the "release" environment as a trusted publisher. See README > Releasing.
+name: Publish gem
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  push:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    environment: release
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+          ruby-version: "3.3"
+
+      - name: Check the tag matches the gem version
+        run: |
+          gem_version=$(ruby -Ilib -e 'require "mtncloud/cli/version"; print MtnCloud::Cli::VERSION')
+          if [ "${GITHUB_REF_NAME}" != "v${gem_version}" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match the gem version ${gem_version} in lib/mtncloud/cli/version.rb"
+            exit 1
+          fi
+
+      - uses: rubygems/release-gem@v1

data/.gitignore

@@ -0,0 +1,25 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.DS_Store
+.idea
+test_config.yaml

data/CLAUDE.md

@@ -0,0 +1,24 @@
+# MTN Cloud CLI
+
+Ruby gem `mtncloud-cli`. It installs the `mtncloud` command and its alias `mcs`. Code is under `lib/mtncloud/` in the `MtnCloud::` namespace. See CONTRIBUTING.md and the README.
+
+## Git workflow (required)
+
+- Never commit or push to `main`. It is protected, and direct pushes are rejected.
+- For every code or docs change: create a branch from an up-to-date `main` (`feature/`, `fix/`, `docs/` or `chore/` prefix), commit there, push the branch, and open a pull request against `main` with `gh pr create --base main`.
+- Merge only after the **CI passed** check succeeds (`gh pr checks <number> --watch`). Never bypass a failing or pending check.
+- Never force-push to `main` and never delete it.
+
+## Testing
+
+- Run `bundle exec rake test:offline` before opening a pull request. CI runs the same task on Ruby 3.3, 3.4 and 4.0.
+- Tests that `require 'mtncloud_test'` need a live appliance and are not run by CI.
+
+## Naming
+
+- Customer-facing text says MTN Cloud, and commands are shown as `mtncloud`.
+- Keep values the appliance or its API defines unchanged, even though they contain "Morpheus": the `X-Morpheus-Lease` and `X-Morpheus-Token` headers, `MORPHEUS_LEASE_TOKEN`, the `morpheus.yml` fallback, job type codes such as `morpheus.task`, the `morpheus` blueprint and backup provider codes, and Morpheus Hub. `test/branding_test.rb` lists the approved ones.
+
+## Releases
+
+Pushing a `v<version>` tag runs `.github/workflows/release.yml`, which publishes to RubyGems. The tag must match `VERSION` in `lib/mtncloud/cli/version.rb`. Push a release tag only when the user asks for one.

data/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to the MTN Cloud CLI
+
+Thank you for helping improve the MTN Cloud CLI. This guide explains how changes get into the project.
+
+## How changes reach main
+
+`main` is protected. Nobody pushes to it directly, including maintainers. Every change goes through a pull request:
+
+1. Update your local `main`:
+
+   ```shell
+   git checkout main
+   git pull
+   ```
+
+2. Create a branch for your change:
+
+   ```shell
+   git checkout -b fix/clusters-get-help
+   ```
+
+   Name the branch after the change, with a prefix: `feature/`, `fix/`, `docs/` or `chore/`.
+
+3. Make your change, run the offline tests (see [Testing](#testing)), and commit.
+4. Push the branch and open a pull request against `main`:
+
+   ```shell
+   git push -u origin fix/clusters-get-help
+   gh pr create --base main
+   ```
+
+5. Wait for the **CI passed** check. It runs the offline tests on Ruby 3.3, 3.4 and 4.0 and builds the gem.
+6. When CI passes, merge the pull request. A pull request cannot be merged while CI is failing or still running.
+
+If CI fails, push more commits to the same branch. CI runs again on every push.
+
+## Setting up
+
+Requirements:
+
+- Ruby 3.3 or newer
+- Bundler 2
+- Git
+
+```shell
+git clone https://github.com/Jose-henry/mtncloud-cli
+cd mtncloud-cli
+bundle install
+```
+
+Run the CLI from your working copy:
+
+```shell
+bundle exec ruby bin/mtncloud --help
+```
+
+See [Development](README.md#development) in the README for the code layout.
+
+## Testing
+
+Run the offline tests before you open a pull request. They don't need an MTN Cloud appliance, and they are the same tests CI runs:
+
+```shell
+bundle exec rake test:offline
+```
+
+Add or update tests for the behaviour you change. A test that doesn't need an appliance must not `require 'mtncloud_test'`, so that `test:offline` and CI run it.
+
+`test/branding_test.rb` fails if any command's help mentions Morpheus, except for values that belong to the appliance, such as the `X-Morpheus-Lease` header. Keep it passing.
+
+The tests that need a live appliance are described in [Testing](README.md#testing) in the README. Run them when you change how the CLI talks to the API.
+
+## Writing changes
+
+- Keep each pull request to one change. Separate refactoring from behaviour changes.
+- Follow the style of the code around your change.
+- Customer-facing text says **MTN Cloud**, and commands are shown as `mtncloud`. Values that the appliance or its API defines keep their names, for example `X-Morpheus-Lease` and `MORPHEUS_LEASE_TOKEN`.
+- Update the README when you change how the CLI is installed, configured or used.
+
+## Commit messages
+
+- Write a short summary line in the imperative mood, for example "Fix clusters get usage on Ruby 3.4".
+- If the reason for the change isn't obvious, explain it in the body.
+
+## Releases
+
+Maintainers publish releases. See [Releasing](README.md#releasing) in the README. The version bump goes through a pull request like any other change, and the version tag is pushed after that pull request is merged.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the project's [MIT license](LICENSE.txt).

data/Dockerfile

@@ -0,0 +1,19 @@
+# Stage 1: build the mtncloud-cli gem from this repository.
+# The gemspec lists its files with `git ls-files`, so this stage needs the .git
+# directory in the build context. Only files tracked by git go into the gem.
+FROM ruby:3.3 AS build
+WORKDIR /src
+COPY . .
+RUN gem build mtncloud-cli.gemspec -o /mtncloud-cli.gem
+
+# Stage 2: install the gem into a clean image.
+# Only the built .gem is copied from stage 1, so nothing else from the build
+# context (local files such as test_config.yaml, or the .git directory)
+# ends up in the final image.
+FROM ruby:3.3
+COPY --from=build /mtncloud-cli.gem /tmp/mtncloud-cli.gem
+RUN gem install /tmp/mtncloud-cli.gem --no-document \
+ && rm /tmp/mtncloud-cli.gem
+
+WORKDIR /root
+ENTRYPOINT ["mtncloud"]

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mtncloud-cli.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,23 @@
+Copyright (c) 2026 MTN Cloud
+Copyright (c) 2015 David Estes
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,187 @@
+# MTN Cloud CLI
+
+The MTN Cloud CLI is a command line interface for managing MTN Cloud. You can use it to provision and manage instances, hosts and clusters, deploy applications, run tasks and workflows, and automate most of what you can do in the MTN Cloud UI.
+
+It installs two commands that run the same CLI:
+
+- `mtncloud`
+- `mcs`, a short alias for `mtncloud`
+
+## Installation
+
+Requirements:
+
+- Ruby. The CLI is tested on Ruby 3.3. On Windows, install Ruby+Devkit from [rubyinstaller.org](https://rubyinstaller.org/downloads/) and select the option to add Ruby to your PATH.
+
+Install the CLI from RubyGems:
+
+```shell
+gem install mtncloud-cli --no-document
+```
+
+Check the installation:
+
+```shell
+mtncloud version
+mcs version
+```
+
+On Windows, a first install from a clean environment took about 17 minutes in our testing, mostly spent compiling native extensions for dependencies such as `ffi`, `llhttp-ffi` and `bigdecimal`. Your install time may differ.
+
+### Updating
+
+```shell
+gem update mtncloud-cli
+```
+
+### Installing from source
+
+To install an unreleased version, build the gem from a clone of this repository. The build needs Git, which it uses to list the files to package.
+
+```shell
+git clone https://github.com/Jose-henry/mtncloud-cli
+cd mtncloud-cli
+gem build mtncloud-cli.gemspec -o mtncloud-cli.gem
+gem install ./mtncloud-cli.gem
+```
+
+### Docker
+
+The Dockerfile builds the CLI from this repository. Build it from the root of a git clone, because the gem build needs the `.git` directory.
+
+```shell
+docker build -t mtncloud-cli .
+docker run --rm -it -v ~/.mtncloud:/root/.mtncloud mtncloud-cli remote list
+```
+
+The volume keeps your remotes and credentials between runs.
+
+## Usage
+
+Add your MTN Cloud remote, then log in:
+
+```shell
+mtncloud remote add mtncloud https://console.cloud.mtn.ng
+mtncloud login
+```
+
+Then run commands, for example:
+
+```shell
+mtncloud instances list
+mcs instances list
+```
+
+Help is available for every command and subcommand with `-h`:
+
+```shell
+mtncloud --help
+mcs instances list --help
+```
+
+`mtncloud shell` starts an interactive shell. `mtncloud man` opens the full manual, which includes the help for every command.
+
+## Configuration
+
+The CLI keeps its configuration in `~/.mtncloud`. Set `MTNCLOUD_CLI_HOME` to use a different directory, for example to keep separate configurations:
+
+```shell
+MTNCLOUD_CLI_HOME=~/.mtncloud_test mtncloud remote list
+```
+
+Files in the home directory include:
+
+| File | Contents |
+|---|---|
+| `appliances` | Your remotes, keyed by name |
+| `credentials` | Access tokens for each remote |
+| `groups` | The active group for each remote |
+| `.mtncloud_profile` | Commands run every time the CLI starts |
+| `.mtncloudrc` | Commands run when `mtncloud shell` starts |
+| `shell_history` | History for `mtncloud shell` |
+
+The `appliances` and `credentials` files are saved with file permissions `0600`. Only one system user should use a home directory.
+
+Other environment variables:
+
+| Variable | Purpose |
+|---|---|
+| `MTNCLOUD_PS1` | The prompt for `mtncloud shell`. See `mtncloud set-prompt --help`. |
+| `MTNCLOUD_CLI_TMPDIR` | Where temporary shells (`mtncloud shell -Z`) are created. The default is the `tmp` directory inside the home directory. |
+
+## Development
+
+Install the dependencies with Bundler 2.2 or newer:
+
+```shell
+bundle install
+```
+
+Run the CLI from your working copy:
+
+```shell
+bundle exec ruby bin/mtncloud --help
+bundle exec ruby bin/mcs --help
+```
+
+To reload your code changes without restarting, start a shell and use `reload`:
+
+```shell
+bundle exec ruby bin/mtncloud shell --debug
+```
+
+Code layout:
+
+- API interfaces are in `lib/mtncloud/api/`.
+- CLI commands are in `lib/mtncloud/cli/commands/`.
+
+### Testing
+
+Offline tests don't need an appliance. CI runs them on every pull request:
+
+```shell
+bundle exec rake test:offline
+```
+
+They include:
+
+- `test/branding_test.rb`, which checks every command's help for leftover non-MTN Cloud branding
+- the test files under `test/cli/` and `test/api/` that do not `require 'mtncloud_test'`
+
+The other tests run against a live appliance. Create a `test_config.yaml` in the repository root:
+
+```yaml
+url: 'https://console.cloud.mtn.ng'
+username: (accountID/Subdomain)\testrunner
+password: 'SecretPassword123$'
+```
+
+Then run all the tests:
+
+```shell
+bundle exec rake test
+```
+
+## Contributing
+
+Changes reach `main` only through pull requests that pass CI. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Releasing
+
+New versions are published to RubyGems by the [Publish gem](.github/workflows/release.yml) workflow when a version tag is pushed:
+
+1. Update `VERSION` in `lib/mtncloud/cli/version.rb` in a pull request, and merge it once CI passes.
+2. Tag the merged commit on `main` and push the tag:
+
+   ```shell
+   git tag v1.0.1
+   git push origin v1.0.1
+   ```
+
+The workflow fails if the tag does not match `VERSION`. RubyGems does not accept the same version twice.
+
+The workflow uses RubyGems trusted publishing, so no API key is stored in this repository. On RubyGems.org, the trusted publisher for `mtncloud-cli` names this repository, the `release.yml` workflow and the `release` environment. If the repository moves, update the repository owner and name in that trusted publisher.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,26 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+# Every test, including the ones that need a live appliance (see README > Testing).
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+# Tests that need a live appliance load the mtncloud_test helper.
+OFFLINE_TESTS = FileList['test/**/*_test.rb'].exclude('test/mtncloud_test.rb').reject do |f|
+  File.read(f).include?("require 'mtncloud_test'")
+end
+
+desc "Run the tests that do not need a live appliance, one file at a time"
+task "test:offline" do
+  failed = OFFLINE_TESTS.reject do |f|
+    puts "== #{f}"
+    ruby("-Ilib", "-Itest", f) { |ok, _status| ok }
+  end
+  abort "Failed: #{failed.join(', ')}" unless failed.empty?
+  puts "All #{OFFLINE_TESTS.size} offline test files passed."
+end
+
+#task :default => :test

data/bin/mcs

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+# mcs is the short alias for the mtncloud command, it runs the same CLI.
+load File.expand_path('mtncloud', __dir__)

data/bin/mtncloud

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+require 'mtncloud'
+
+# arguments
+args = ARGV.dup
+
+# input pipe: only read stdin as arguments when --stdin is explicitly passed.
+# Previously stdin was always consumed when not a TTY, which caused the CLI
+# invoked inside a piped bash script (e.g. base64 -d <<< <script> | bash -l)
+# to consume the remaining script lines as CLI arguments (MORPH-6237).
+# Usage: echo 42 | mtncloud instances get --stdin
+if args.delete('--stdin') && !$stdin.tty?
+  pipe_data = $stdin.read
+  if pipe_data
+    args += pipe_data.split
+  end
+end
+
+# output pipe
+# if !$stdout.tty?
+
+# end
+
+terminal = MtnCloud::Terminal.new
+exit_code, err = terminal.execute(args)
+# raise err unless err.nil?
+exit exit_code

data/lib/mtncloud/api/account_groups_interface.rb

@@ -0,0 +1,48 @@
+require 'mtncloud/api/api_client'
+
+class MtnCloud::AccountGroupsInterface < MtnCloud::APIClient
+
+  def get(account_id, id, params={})
+    raise "#{self.class}.get() passed a blank id!" if id.to_s == ''
+    url = "#{@base_url}/api/accounts/#{account_id}/groups/#{id}"
+    headers = { params: params, authorization: "Bearer #{@access_token}" }
+    opts = {method: :get, url: url, headers: headers}
+    execute(opts)
+  end
+
+  def list(account_id, params={})
+    url = "#{@base_url}/api/accounts/#{account_id}/groups"
+    headers = { params: params, authorization: "Bearer #{@access_token}" }
+    opts = {method: :get, url: url, headers: headers}
+    execute(opts)
+  end
+
+  def create(account_id, payload)
+    url = "#{@base_url}/api/accounts/#{account_id}/groups"
+    headers = { :authorization => "Bearer #{@access_token}", 'Content-Type' => 'application/json' }
+    opts = {method: :post, url: url, headers: headers, payload: payload.to_json}
+    execute(opts)
+  end
+
+  def update(account_id, id, payload)
+    url = "#{@base_url}/api/accounts/#{account_id}/groups/#{id}"
+    headers = { :authorization => "Bearer #{@access_token}", 'Content-Type' => 'application/json' }
+    opts = {method: :put, url: url, headers: headers, payload: payload.to_json}
+    execute(opts)
+  end
+
+  def destroy(account_id, id, params={})
+    url = "#{@base_url}/api/accounts/#{account_id}/groups/#{id}"
+    headers = { :params => params, :authorization => "Bearer #{@access_token}", 'Content-Type' => 'application/json' }
+    opts = {method: :delete, url: url, headers: headers}
+    execute(opts)
+  end
+
+  def update_zones(account_id, id, payload)
+    url = "#{@base_url}/api/accounts/#{account_id}/groups/#{id}/update-zones"
+    headers = { :authorization => "Bearer #{@access_token}", 'Content-Type' => 'application/json' }
+    opts = {method: :put, url: url, headers: headers, payload: payload.to_json}
+    execute(opts)
+  end
+
+end