
<center>
  <img style="width: 100%; max-width: 375px;" src="https://codemelted.com/assets/images/logo-codemelted-rs.png" />
</center>
<h1><img style="height: 35px;" src="https://codemelted.com/assets/images/icon-pwsh.png" /> Invoke-CodeMeltedCLI Module</h1>

*BY: Mark Shaffer / LAST UPDATED: 2025-Oct-12*

The `Invoke-CodeMeltedCLI` PowerShell module will provide a Command Line Interface (CLI) to facilitate common developer tasks on Mac, Linux, or Windows systems. When installed, the CLI will provide the `codemelted-cli` command that can be accessed in a pwsh terminal or in ps1 scripts.

The `codemelted-cli` provides a binding to the `codemelted` rust compiled native command. This binding facilitates lower level calls not easily accomplished within PowerShell. However, with this binding and the power of the .NET core, a developer gets the most powerful terminal experience around.

<center>
  <br />
  <a href="https://www.buymeacoffee.com/codemelted" target="_blank">
    <img height="50px" src="https://codemelted.com/assets/images/icon-bmc-button.png" />
  </a>
  <br /><br />
  <p>Hope you enjoy the content. Any support is greatly appreciated. Thank you! 🙇</p>
</center>

**Table of Contents**

- [1.0 GETTING STARTED](#10-getting-started)
  - [1.1 Install pwsh Core](#11-install-pwsh-core)
    - [1.1.1 Mac OS](#111-mac-os)
    - [1.1.2 Linux OS](#112-linux-os)
    - [1.1.3 Windows](#113-windows)
    - [1.1.4 Raspberry Pi](#114-raspberry-pi)
  - [1.2 Install Module](#12-install-module)
- [2.0 FEATURES](#20-features)
  - [2.1 codemelted-cli --version](#21-codemelted-cli---version)
  - [2.2 codemelted-cli --help](#22-codemelted-cli---help)
- [3.0 USAGE](#30-usage)
  - [3.1 --async-\* Actions](#31---async--actions)
  - [3.2 --json-\* Actions](#32---json--actions)
  - [3.3 --logger-\* Actions](#33---logger--actions)
  - [3.4 --network-fetch Actions](#34---network-fetch-actions)
  - [3.5 --process-\* Actions](#35---process--actions)
- [4.0 MODULE INFORMATION](#40-module-information)
  - [4.1 License](#41-license)
  - [4.2 Revision History](#42-revision-history)

# 1.0 GETTING STARTED

This will guide you through the setup of the `codemelted-cli` command.

## 1.1 Install pwsh Core

The following section walk you through the installation of the pwsh terminal. Once installed you can access the terminal via the `pwsh` command.

### 1.1.1 Mac OS

From a Mac OS terminal execute the command:

```
brew install --cask powershell
```

### 1.1.2 Linux OS

Follow the <a target="_blank" href="https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-linux">Install Powershell on Linux</a> to properly setup the pwsh terminal for your Linux flavor.

### 1.1.3 Windows

From a windows cmd terminal execute the command

```
winget install --id Microsoft.PowerShell --source winget
```

### 1.1.4 Raspberry Pi

The following series of commands will setup a pwsh terminal on a Raspberry Pi picking up the necessary repo and setting up the environment. Notice the `VERSION` as the currently identified version. Change this to install the latest version.

```sh
VERSION=7.5.0
sudo dpkg --add-architecture arm64
sudo apt-get update
sudo apt-get install -y libc6:arm64 libstdc++6:arm64
sudo mkdir -p /opt/microsoft/powershell/7
sudo wget -O /tmp/powershell.tar.gz https://github.com/PowerShell/PowerShell/releases/download/v${VERSION}/powershell-$VERSION}-linux-arm64.tar.gz
sudo tar zxf /tmp/powershell.tar.gz -C /opt/microsoft/powershell/7
sudo chmod +x /opt/microsoft/powershell/7/pwsh
sudo ln -s /opt/microsoft/powershell/7/pwsh /usr/bin/pwsh
sudo rm /tmp/powershell.tar.gz
pwsh --version
```

## 1.2 Install Module

The `Invoke-CodeMeltedCLI` module is hosted at [PowerShell Gallery](https://www.powershellgallery.com/packages/invoke-codemeltedcli). The commands below will facilitate installation, maintenance, and removal of the module.

- `Find-Module -Name Invoke-CodeMeltedCLI`: To find the current version of the published module in the PSGallery.
- `Install-Module -Name Invoke-CodeMeltedCLI`: To install the module from the PSGallery.
- `Update-Module -Name Invoke-CodeMeltedCLI`: To update to the latest module version from the PSGallery.
- `Remove-Module -Name Invoke-CodeMeltedCLI`: To completely uninstall the module from the host operating system.

# 2.0 FEATURES

<center><img style="width: 100%"src="https://codemelted.com/developer/mdbook/models/use-case-model.drawio.png"></center>

## 2.1 codemelted-cli --version

<mark>TBD</mark>

## 2.2 codemelted-cli --help

```
NAME
    Invoke-CodeMeltedCLI

SYNOPSIS
    Provides the PowerShell module Invoke-CodeMeltedCLI. This cmdlet
    accessible via the codemelted-cli alias provides the advanced wrapper
    for the native codemelted command. The native codemelted command provides
    the lower level bindings to work in any shell. This cmdlet provides
    additional functionality only available in a pwsh terminal.

    SYNTAX:
      codemelted-cli [Action] [Params]

    PARAMETERS:
      [Action]
        --help: Execute `codemelted-cli --help to learn about produce this
            help file. Execute
            'codemelted-cli --help @{ action = "--action-item" }' to learn
            about additional actions listed under the ACTION: section.

        --version: Get the current version of the Invoke-CodeMeltedCLI
            module.


      [Params]
        The optional set of named arguments to pass to action via a
        hashtable.

    ACTIONS:
      --async-sleep
      --async-task
      --async-timer
      --json-check-type
      --json-create-array
      --json-create-object
      --json-has-key
      --json-parse
      --json-stringify
      --json-valid-url
      --logger-level
      --logger-handler
      --logger-log
      --network-fetch
      --process-exists
      --process-run
      --process-spawn

    RETURNS:
      Will vary depending on the called [Action] function call. It will be
      documented with each function and available online.

RELATED LINKS
    SDK Docs:
    https://codemelted.com/developer/pwsh

    GitHub Source:
    https://github.com/CodeMelted/codemelted.rs
```

# 3.0 USAGE

## 3.1 --async-* Actions

Execute `codemelted-cli --help @{ action = "--async" }` to retrieve help information.

```
NAME
    codemelted_async

SYNOPSIS
    Provides a series of actions for performing asynchronous operations within
    a pwsh session / script. These actions include sleeping processing for
    a given number of milliseconds, running a background task and retrieving
    the data later, and kicking off a repeating timer in the background until
    stopped.

    SYNTAX:
      # Delay a given script task for the specified time in milliseconds.
      codemelted-cli --async-sleep @{
        delay = [int]; # required
      }

      # Starts a background processing task that will run to completion and
      # provide the answer via the return call of the task.
      $scheduledTask = codemelted-cli --async-task @{
        task = {
          param($data)
          return $data + 5
        };                  # [scriptblock] required
        data = [object];    # optional
        delay = [int];      # optional
      }

      # Some processing later...
      if ($scheduleTask.has_completed()) {
        # This blocks if it has not completed.
        $value = $scheduledTask.value()
      }

      # Kicks off a repeating background timer on a given interval in
      # milliseconds.
      $timer = codemelted-cli --async-timer @{
        task = [scriptblock]; # required
        delay = [int];     # required
      }

      # Some processing later...
      if ($timer.is_running()) {
        $timer.stop()
      }

    RETURNS:
      --async-sleep: [void]

      --async-task: [CTaskResult] object that will hold the task running in
          the background until completed. You can check if it has completed
          via the has_completed() function call and access the final
          calculated value via the value() function.

      --async-timer: [CTimerResult] object with the methods of is_running()
          and stop() to determine if the timer is running and stopping it
          altogether.
```

## 3.2 --json-* Actions

Execute `codemelted-cli --help @{ action = "--json" }` to retrieve the latest information.

```
NAME
    codemelted_json

SYNOPSIS
    Provides a series of actions that allow for fully working with JSON data
    within a pwsh terminal / shell script.

    SYNTAX:

      # Validates the specified "data" is the given .NET "type".
      # NOTE: the type represents the .NET type name but a Contains compare
      #       is done to try to establish partial name finds but that is not
      #       a guarantee.
      $isType = codemelted-cli --json-check-type @{
        type = "string";       # required
        data = $var1;          # required
        should_throw = [bool]; # optional
      }

      # Creates a JSON compliant [ArrayList] copying "data" if specified.
      $data = codemelted-cli --json-create-array @{
        "data" = [array] or [System.Collection.ArrayList] # optional
      }

      # Creates a JSON compliant [hashtable] copying "data" if specified.
      $data = codemelted-cli --json-create-object @{
        data = [hashtable]  # optional
      }

      # Determines if the given [hashtable] has the specified key.
      $hasKey = codemelted-cli --json-has-key @{
        data = [hashtable];    # required
        key = "key_name";      # required
        should_throw = [bool]; # optional
      }

      # Converts the string data to its appropriate JSON compliant data type.
      $data = codemelted-cli --json-parse @{
        data = [string]; # required
      }

      # Converts a JSON compliant type to a string.
      $data = codemelted-cli --json-stringify @{
        data = [object]; # required, JSON compliant type.
      }

      # Determines if the data is a valid url or not.
      $isType = codemelted-cli --json-valid-url @{
        data = [string];       # required
        should_throw = [bool]; # optional
      }

    RETURNS:
      --json-check-type: [bool] indication if the type is as expected.
      --json-create-array: [System.Collections.ArrayList] JSON compliant
          object.
      --json-create-object: [hashtable] JSON compliant object.
      --json-has-key: [bool] if key found or not.
      --json-parse: [array], [double], [int], [bool], [hashtable] JSON
          compliant types.
      --json-stringify: [string] representation of the JSON compliant type.
      --json-valid-url: [bool] URL validity.

    THROWS:
      Any option taking a 'should_throw = true' will throw on unexpected
      data.

      Any conversion failures with the --json-stringify / --json-parse
      actions.
```

## 3.3 --logger-* Actions

Execute `codemelted-cli --help @{ action = "--logger" }` to retrieve the latest information.

```
NAME
    codemelted_logger

SYNOPSIS
    Provides a logging facility to STDOUT color coding the different log
    messages based on the log level. Also provides further processing via
    a log handler to allow for logging to backend database or local file.

    SYNTAX:
      # Set / get the current pwsh script logging level. The valid levels
      # when setting are 'debug' / 'info' / 'warning' / 'error' / 'off'.
      codemelted-cli --logger-level @{
        level = [string]; # required for setting
      }

      # Set / unset a scriptblock log handler for further processing
      # of a log event.
      codemelted-cli --logger-handler @{
        handler = [scriptblock] / $null  # required
      }

      # Will log a 'info' / 'warning' / 'error' / 'debug' [level] message
      # to STDOUT and to be further processed via a log handler.
      codemelted-cli --logger-log @{
        level = [string]; # required
        data = [string];  # required
      }

    RETURNS:
      --logger-level: [string] if not setting the log level.
      --logger-handler: [void]
      --logger-log: [void]
```

## 3.4 --network-fetch Actions

Execute `codemelted-cli --help @{ action = "--network-fetch" }` to retrieve the latest information.

```
NAME
    codemelted_network_fetch

SYNOPSIS
    Provides a mechanism for fetching data from a server REST API. The result
    is a [CFetchResponse] object with the status_code along with the data
    received as_bytes(), as_object(), or as_string(). If it is not any of those
    types, a $null is returned.

    SYNTAX:
      # Perform a network fetch to a REST API. The "data" is a [hashtable]
      # reflecting the named parameters of the Invoke-WebRequest. So the two
      # most common items will be "method" / "body" / "headers" but others
      # are reflected via the link.
      $resp = codemelted --network-fetch @{
        "url" = [string / ip]; # required
        "data" = [hashtable]   # required
      }

    RETURNS:
      [CFetchResponse] that has the statusCode and data as properties.
        Methods of as_bytes(), as_object(), as_string() exists to get the data
        of the expected type or $null if not of that type. A method of is_ok()
        signals whether the statusCode was a 2XX HTTP Status Code.

RELATED LINKS
    Invoke-WebRequest Details:
    https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.utility/invoke-webrequest
```

## 3.5 --process-* Actions

Execute `codemelted-cli --help @{ action = "--process" }` to retrieve the latest information.

```
NAME
    codemelted_process

SYNOPSIS
    Provides the actions necessary to interact with the host operating
    system's available executable programs.

    SYNTAX:
      # Determines if a given executable is known by the host operating
      # system. NOTE: regular terminal command (i.e. ls, dir) will not
      # register.
      $exists = codemelted-cli --process-exists @{
        command = [string]; # required
      }

      # Runs a one-off operating system process and captures its STDOUT
      # output.
      $output = codemelted-cli --process-run @{
        command = "ls"; [string] # required
        args = "-latr"; [string] # optional
      }

      # Creates a [CProcess] object allowing bi-directional communication via
      # STDIN / STDOUT with the command until killed.
      $process = codemelted-cli --process-spawn @{
        command = [string] # required executable name
        args = [string]    # optional arguments to pass.
      }

    RETURNS:
      --process-exists: [bool] identifying if the process exists.
      --process-run: [string] of the captured STDOUT.
      --process-spawn: [CProcess] object with the methods of id(), read(),
          and write() to allow bi-directional communication with the process
          until terminated via kill().
```

# 4.0 MODULE INFORMATION

## 4.1 License

MIT License

© 2025 Mark Shaffer

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.

## 4.2 Revision History

- **<u>2025-mmm-dd (M. Shaffer)</u>:** TBD
