Skip to main content

An HCLI Connector that can be used to expose a REST API that behaves as a CLI, via hypertext command line interface (HCLI) semantics.

Project description

pypi build status pyver huckle hc hg

HCLI Core

An HCLI Connector that can be used to expose a REST API that behaves as a CLI, via hypertext command line interface (HCLI) semantics.


HCLI Core implements an HCLI Connector, a type of Service Connector, as a WSGI application, and provides a way for developers to expose a service hosted CLI, as a REST API, via HCLI semantics. Such an API exposes a “built-in” CLI that can be interacted with dynamically with any HCLI client. Up to date, in-band, man page style API/CLI documentation is readily available for use to help understand how to interact with the API.

Most, if not all, programming languages have a way to issue shell commands. With the help of a generic HCLI client, such as Huckle [1], APIs that make use of HCLI semantics are readily consumable anywhere via the familiar command line (CLI) mode of operation, and this, without there being a need to write a custom and dedicated CLI to interact with a specific HCLI API.

You can find out more about HCLI on hcli.io [2]

The HCLI Internet-Draft [3] is a work in progress by the author and the current implementation leverages hal+json alongside a static form of ALPS (semantic profile) [4] to help enable widespread cross media-type support.

Help shape HCLI and it’s ecosystem by raising issues on github!

[1] https://github.com/cometaj2/huckle

[2] http://hcli.io

[3] https://github.com/cometaj2/I-D/tree/master/hcli

[4] http://alps.io

Installation

hcli_core requires a supported version of Python and pip.

You’ll need an WSGI compliant application server to run hcli_core. For example, you can use Green Unicorn (https://gunicorn.org/), and an HCLI client such as Huckle (https://github.com/cometaj2/huckle). The following runs the default jsonf HCLI bundled with HCLI Core.

pip install hcli-core
pip install gunicorn
pip install huckle
gunicorn --workers=1 --threads=2 -b 127.0.0.1:8000 "hcli_core:connector()"

Usage

Open a different shell window.

Setup the huckle env eval in your .bash_profile (or other bash configuration) to avoid having to execute eval everytime you want to invoke HCLIs by name (e.g. jsonf).

Note that no CLI is actually installed by Huckle. Huckle reads the HCLI semantics exposed by the API and ends up behaving like the CLI it targets.

huckle cli install http://127.0.0.1:8000
eval $(huckle env)
jsonf help

3rd Party HCLI Installation

If you want to load a sample HCLI other than the default sample application, you can try loading one of the other sample HCLIs developped independently of HCLI Core. For example, the hai HCLI (hypertext LLM command line chat application).

A folder path to any other 3rd party HCLI can be provided in the same way to the HCLI Connector, provided the 3rd party HCLI meets CLI interface (cli.py) and HCLI template (template.json) requirements:

pip install hcli-hai
pip install hcli-core
pip install gunicorn
pip install huckle
gunicorn --workers=1 --threads=2 "hcli_core:connector(\"`hcli_hai path`\")"

3rd Party HCLI Usage

Open a different shell window.

Setup the huckle env eval in your .bash_profile (or other bash configuration) to avoid having to execute eval everytime you want to invoke HCLIs by name (e.g. hai).

huckle cli install http://127.0.0.1:8000
eval $(huckle env)
hai help

Versioning

This project makes use of semantic versioning (http://semver.org) and may make use of the “devx”, “prealphax”, “alphax” “betax”, and “rcx” extensions where x is a number (e.g. 0.3.0-prealpha1) on github. Only full major.minor.patch releases will be pushed to pip from now on.

Supports

  • HTTP/HTTPS.

  • HCLI version 1.0 server semantics for hal+json.

  • Web Server Gateway Interface (WSGI) through PEP 3333 and Falcon.

  • Bundled Sample HCLIs:
    • jsonf - a simple formatter for JSON.

    • hfm - a file upload and download manager that works with *nix terminal shell input and output streams.

    • hptt - a rudimentary HCLI Push To Talk (PTT) channel management service.

    • hub - a rudimentary HCLI service discovery hub.

    • nw - a flexible IP Address Management (IPAM) service.

  • Support for use of any 3rd party HCLI code that meets CLI interface requirements and HCLI template requirements (i.e. see sample HCLIs).

  • Support large input and output streams as application/octet-stream.

  • HTTP Basic Authentication. See hcli_core help for details.

  • HCLI Core API Key (HCOAK) Authencitation. See hcli_core help for details.

  • Support HTTP API Problem Details [RFC9457] per spec to help with client-side STDERR output.

  • Credentials Management via the hco HCLI.

  • Centralized remote authentication support via hco for HCLI Core services configured for remote credential management.

  • Serverless deployment (i.e. AWS Lambda).

Authentication

HCLI Core makes available the deployment of an HCLI Management app (hco) to manage authentication credentials for the deployed 3rd party HCLI service, and can be configured for authentication in two distinct ways:

  • local - HCLI Core manages the credentials locally for the 3rd party HCLI app.

  • remote - HCLI Core forwards credentials validation to a remotely hosted hco for 3rd party HCLI app access.

The remote configuration allows for centralized remote authentication support across many deployed HCLIs. This is trivially accomplished via HCLI Core making use of the huckle HCLI client, and via hco and HCLI semantics, to forward validation of provided credentials to a remotely hosted hcli_core service exposing hco. See ‘hcli_core help’ for details.

Artificial Intelligence

HCLI naturally presents, via in-band documentation availability, as a highly discoverable semantic landscape that can be used to trivially extend the capabilities of conversational LLMs by providing a mature conceptual and practical alternative to Model Context Protocol (MCP) or function calls.

This is explored via hcli_hai https://github.com/cometaj2/hcli_hai and haillo https://github.com/cometaj2/haillo

Security

HCLI Core implements a trusted integration model. In other words, 3rd party HCLIs running via HCLI Core MUST be trusted not to interfere with HCLI Core. 3rd party HCLIs are inherently able to do anything that Python can do, and as such, a 3rd party HCLI cannot coherently be isolated from HCLI Core as a security boundary. If a trust boundary needs to be established on authentication grounds, then authentication SHOULD be managed elsewhere (i.e. by another layer on the network or via a remotely hosted hco; see Authentication).

To Do

  • Automated tests for all bundled HCLI samples.

  • Separate out HCLI applications from HCLI Core to help avoid application dependencies bleeding onto HCLI Core.

  • Rate limiting.

  • Lockout on multiple failed authentications.

  • Better role handling for admin vs users for remote validation.

  • Better logging configuration support.

  • Role assignment for hco remote validation authorization.

Bugs

  • No good handling of control over request and response in cli code which can lead to exceptions and empty response client side.

  • The hfm sample HCLI fails disgracefully when copying a remote file name that doesn’t exist (server error).

  • Routing can ambiguous and fail if the 3rd party HCLI app’s name start with hco in core.root aggregate configuration (template.py owns)

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hcli_core-3.7.0.tar.gz (50.0 kB view details)

Uploaded Source

Built Distribution

hcli_core-3.7.0-py3-none-any.whl (60.3 kB view details)

Uploaded Python 3

File details

Details for the file hcli_core-3.7.0.tar.gz.

File metadata

  • Download URL: hcli_core-3.7.0.tar.gz
  • Upload date:
  • Size: 50.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.11.12

File hashes

Hashes for hcli_core-3.7.0.tar.gz
Algorithm Hash digest
SHA256 7c6a9db57d239450a3170046cc1fd0194c45a34508cde2919bbc8b921e280a4f
MD5 9481002eb72ccaffac0bdb21572d314b
BLAKE2b-256 046ac5597ff64820de045517a927029a2e10ef6f55fb979ca08d4893f52f7a51

See more details on using hashes here.

File details

Details for the file hcli_core-3.7.0-py3-none-any.whl.

File metadata

  • Download URL: hcli_core-3.7.0-py3-none-any.whl
  • Upload date:
  • Size: 60.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.11.12

File hashes

Hashes for hcli_core-3.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 c90e08548c191dded246754952a8cec19939e516fd569596cdaead0bb6dca684
MD5 64be4c863bd50f413d4ed32ada26e7b5
BLAKE2b-256 09056d0d776b5ec814c5ba5cdaae848a13e9a73627b50d36c2cf15dcff00d17e

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page