HUCKLE(1)

NAME
huckle - A generic hypertext command line interface (HCLI) client

SYNOPSIS
huckle [ option | <command> <parameter> ]

DESCRIPTION
huckle is a generic HCLI client, CLI, and python library, that can be used with any API that presents hypertext command line interface (HCLI) semantics.

By default huckle installs itself in a user's home directory (i.e. ~), however this can be overridden via the HUCKLE_HOME environment variable (e.g. export HUCKLE_HOME=/tmp)

CLI aliases are directly invoked by name if the HCLI entry scripts are locatable in your shell PATH. See 'huckle env' for details to make your environment configuration more permanent.

COMMANDS

env This outputs the HCLI entry scripts path to export to enable direct HCLI execution by name (i.e. <cliname>. Equivalent to huckle cli run <cliname>).

    "eval $(huckle env)" can be setup in ~/.bashrc, ~/.bash_profile or ~/.profile to ensure the path is always loaded on shell start.

cli install <url>
    This attempts to install/auto configure a CLI if provided with the root URL of an HCLI API. If successful, the CLI can be invoked by name.

    - Its entry script is located under $HUCKLE_HOME/.huckle/bin/<cliname> (huckle created).
    - Its configuration is located under $HUCKLE_HOME/.huckle/etc/<cliname>/config (huckle created). See EXAMPLE CONFIGURATION FILE.

    Note that an existing configuration file is left alone if the command is run multiple times for the same CLI.

cli rm <cliname>
    Removes an installed CLI.

cli flush <cliname>
    Flushes pinned urls (url cache of final/non-HCLI/API surface urls). The cache is used to increase speed to API surface by reducing the quantity of network calls normally executed to navigate the HCLI semantics.

    Note that unexpected failures can occur if the cache is invalidated for a reason or another.

cli run <cliname>
    Used to invoke a CLI by name, the details of which are otherwise left to API implementers. This is equivalent to invoking <cliname> directly after CLI installation and after exporting the huckle env path (see "huckle env").

    Note that in certain exceptional cases where a parameter might be passed on the command line, if the parameter value matches exactly an available command, huckle will not be able to distinguish between an intent to pass a command or a parameter and will require additional information; notably escapement via backslash double quote or single quote.

    Huckle accept lazy parameters (without quotes), and this works most of the time, however if ambiguity arises, additional information must be provided.

    For example, assuming an "hc" HCLI, an hc "connect" command and otherwise valid "-j" option; the following will fail:

    echo '$$' | hc -j "connect"

    echo '$$' | hc -j 'connect'

    The following however would succeed:

    echo '$$'| hc -j \'connect\'

    echo '$$'| hc -j \"connect\"

    This would also succeed if multiple words must be passed as a parameter:

    echo '$$'| hc -j 'connect me'

    echo '$$'| hc -j "connect me"

cli ls
    Lists all the installed CLIs.

cli config <cliname>
    Lists the configuration options of an installed CLI.

cli config <cliname> <property>
    Returns the value of a set configured property.

cli config <cliname> <property> <value>
    Sets the value of a property to a specific value.

cli credential <cliname> <username | keyid>
    Sets the value of a username password or keyid apikey, as submitted via stdin to the configured credential helper.

<cliname> ...
    The <cliname> alias created for brevity, via huckle cli install.

<cliname> ... help
    The "help" command can be used anywhere in a command line invocation to generate help pages from an HCLI document. This is useful to explore what a CLI can do.

help
    This help file.

OPTIONS

--version
    huckle version and the version of its dependencies.

CACHING
Huckle is able to cache the final execution URL of given command to help avoid traversal of HCLI semantics. This allows for a tradeoff between performance and relevance (e.g. potential staleness per the expected HCLI semantics); see url.pinning under EXAMPLE CONFIGURATION FILE.

LOGGING
Huckle supports logging of errors to $HUCKLE_HOME/.huckle/var/log/huckle.log if configured in the common configuration file per $HUCKLE_HOME/.huckle/etc/config; see log and log.level under EXAMPLE COMMON CONFIGURATION FILE.

  EXAMPLE COMMON CONFIGURATION FILE
[default]
log = <skip | log>
log.level = <info | debug | warning | error | critical>

AUTHENTICATION
Huckle supports three authentication modes:

- No Authentication - See auth.mode under EXAMPLE CONFIGURATION FILE.
- HTTP Basic Authentication - See auth.mode and auth.user.profile under EXAMPLE CONFIGURATION FILE.
- HCOAK (HCLI Core API Key Authentication) - See auth.mode and auth.apikey.profile under EXAMPLE CONFIGURATION FILE.

A user created credentials file is expected under $HUCKLE_HOME/.huckle/etc/<cliname>/credentials for its respective HCLI, and will only be used by huckle in that context.

  HUCKLE VS KEYRING
Huckle makes available two credential helpers: huckle, and keyring; see credential.helper under EXAMPLE CONFIGURATION FILE.

The huckle credential helper simply works with a $HUCKLE_HOME/.huckle/etc/<cliname>/credentials plaintext file. It is not particularly secure, but is otherwise convenient and can be made sufficiently secure if the user's environment is made sufficiently secure.

The keyring credential helper makes use of the keyring library which defaults to a recommended backend. The following are supported by default:

- macOS Keychain
- Freedesktop Secret Service supports many DE including GNOME (requires secretstorage)
- KDE4 & KDE5 KWallet (requires dbus)
- Windows Credential Locker

See https://pypi.org/project/keyring/ for the full range or supported features and to understand how to setup 3rd party or custom storage backends.

Both HTTP Basic Authentication and HCOAK Authentication are supported via the use of [profile] in a credentials file, as referenced by auth.user.profile or auth.apikey.profile; see EXAMPLE CREDENTIALS FILE and EXAMPLE CONFIGURATION FILE.

  EXAMPLE CREDENTIALS FILE
[default]
username = <username>
password = <password>

[anotherprofile]
username = <anotherusername>
password = <anotherpassword>

[user_apikeyprofile]
keyid = <apikeyid>
apikey = <apikey>

EXAMPLE CONFIGURATION FILE
[default]
url = <url>
ssl.verify = <skip | verify>
url.pinning = <dynamic | pin>
credential.helper = <huckle | keyring>
auth.mode = <skip | basic | hcoak>
auth.user.profile = <credentials profile (section name)>
auth.apikey.profile = <credentials profile (section name)>

EXAMPLE
huckle cli install https://hcli.io/hcli/cli/jsonf?command=jsonf

eval $(huckle env)

jsonf

huckle cli install localhost:8000

huckle cli install localhost:8000 | xargs bash -c '$0 help'

huckle cli run jsonf (equivalent to simply invoking "jsonf" in the shell after a successful cli installation and setup via 'eval $(huckle env)')

huckle cli ls

huckle cli config jsonf

huckle cli flush jsonf

huckle cli rm jsonf

huckle cli config jsonf url.pinning pin

huckle cli config hco credential.helper keyring

tr -d '\n' < passwordfile | huckle cli credential hco admin

tr -d '\n' < passwordfile | tee >(hco passwd admin) | huckle cli credential hco admin

huckle --version