<!-- FS_84_11_73_28: supported python versions: -->

Supported:

• Linux
• Bash >= 4.0
• Python >= 3.9

<a name="argrelay-secreencast"></a>

<!-- [](https://asciinema.org/a/LTHj0DHN2kfXJCHCGuJugNG4P) -->

<!-- See: docs/dev_notes/screencast_notes.md -->

<a id="argrelay-about"></a>

What is argrelay?

A human interface into "automation arsenal" with built-in search for scripts & their input data.

A longer answer:

A wrapper for command line interface (CLI) tools to simplify input selection.<br/> It integrates shell + client + server to search loaded custom data<br/> navigating custom schema via CLI args directly in the standard shell.

• Although its initial purpose was command auto-completion, that become a trivial byproduct of...
• Its primary feature: (tag|label|keyword|attribute)-based structured data search.

Probably the best answer:

:star: :star: :star: :star: :star:

You may find it easier to get the idea through examples in [the_problem_argrelay_solves.md][the_problem_argrelay_solves.md]<br/> and ignore the rest of this readme.md (to avoid reading distilled claims).

When is it needed?

It solves the single most annoying problem to know what to type next in the middle of typing.

• When command args relate to sizeable data incomprehensible or difficult to<br/> review, select, browse, discover on the spot.

• When knowledge about ( non-standard | undocumented ) "enterprise automation" scripts is<br/> constantly invalidated by frequent updates of code & data.

argrelay-registered functions are queryable - they use schemas with<br/> loaded data to contextually limit possible options to locate or auto-complete them.

<a id="argrelay-general-dilemma"></a> <a id="argrelay-purpose"></a>

Why is it for shell?

[It is not necessarily only for shell][argrelay_org],<br/> but there is an oversupply of GUI-s (and they do not integrate with scripts).

Vacant niche:

CLI is indispensable for rapidly evolving custom tools:

• [A] ubiquitous automation (any command is effectively replay-able code)
• [B] quick implementation (get it done "in the afternoon" without drilling fullstack API whole month)
• [C] ultimate manual intervention (when everything else is already failed and unavailable)

Accepting the problem:

Achieving all three [A, B, C] is nearly impossible without CLI.

Devising a solution:

Make CLI more human-efficient by reducing manual and guess work:

• enable inline search directly in shell (without copying-and-pasting args from other apps)
• reduce cognitive load via feedback eliminating syntax and options memorization
• unify interaction for all registered commands via data-driven framework

See also ["general dilemma"][general_dilemma].

<a id="argrelay-execution"></a>

How does it work?

It employs the same shell API as auto-completion for any other (e.g. ls or git) command,<br/> except that requests go to the server with its plugin-s to run search logic against indexed data<br/> (instead of processing requests locally by querying the file system).

<a id="argrelay-name"></a>

It is in the name:

Essentially, sitting between the user shell and the user program,<br/> argrelay "relays" command line args (hence, the name) to the server on each request,<br/> then it uses response data to complete/explain/invoke the command for the user:

sequenceDiagram
    autonumber
    actor U as <br/>User with shell
    box transparent <br/>argrelay
    participant C as Client
    participant S as Server
    end
    participant P as Any program:<br/>user-specific<br/>client-side-local
    U ->> C: use shell hotkeys
    activate C
    C ->> S: "relay" all args
    activate S
    S ->> C: provide data to<br/>complete<br/>explain<br/>invoke<br/>the command
    deactivate S
    C ->> U: if<br/>complete<br/>or<br/>explain
    C ->> P: if invoke
    deactivate C
    activate P
    P ->> U: produce invocation results
    deactivate P

See ["full picture"][full_picture] below.

<a id="argrelay-scenario"></a>

Typical scenario:

• Human types in some remembered args (via Tab-auto-completion) in relaxed syntax and order.

• Machine provides feedback (via Alt+Shift+Q-query) on the progress of the input interrogation.

  It tells:

  • What args machine already matched with the data according to command schema.

  • What else machine needs from human to disambiguate and select the remaining command args.

Try ["interactive demo"][interactive_demo] below.

<a id="argrelay-request-hotkeys"></a>

Request hotkeys:

| Local Bash: | Remote Server: | Local Client: | |-------------------|:------------------------------------|:--------------------------------------------| | Alt+Shift+Q | reports existing and missing input | displays command input interrogation status | | Tab | suggests options for missing input | lists options to Bash for auto-completion | | Enter | provides data to invoke the command | executes the command |

Apart from the trivial Enter to execute command,</br> Tab and Alt+Shift+Q hotkeys are configured via [Readline][readline_config] library Bash relies on.

How to use it?

The simplest way is to fork|branch the repo and wrap the intended logic following an example:

• Implement loader plugin to load objects and index their properties for selection via CLI.

  For example, ssh wrapper may use generic loader for static file with data -<br/> see few destinations with multiple properties in [ConfigOnlyLoader.ssh_dst_group.data.yaml][ssh_loder_data].

• Implement delegator plugin to wrap the logic requiring arguments selection.

  For example, ssh wrapper may use selected destinations,<br/> see invoke_action func in [DelegatorSshDst.py][ssh_delegator_code].

Try ["interactive demo"][interactive_demo] while changing code and data from that example to<br/> see how CLI arguments are matched against properties of the ssh destinations loaded by the loader.

Ultimately, argrelay can be used as dependency for a [separate project][bootstrap_procedure.1.project_creation.md] (in its own another repo).

<a id="argrelay-demo"></a>

Interactive demo: starting and stopping

There are two ways to start demo:

• Using docker image:

  docker run -it argrelay/demo
  

• Using git sources:

  This is a non-intrusive demo (e.g. without permanent changes to ~/.bashrc).

  Clone this repo somewhere (@/ is [the project root][FS_29_54_67_86.dir_structure.md]).

  Start @/exe/relay_demo.bash sub-shell (it may take a couple of minutes to start for the first time):

  ./exe/relay_demo.bash
  

  This sub-shell configures request hotkeys to bind lay command with @/exe/run_argrelay_client.

Optionally, review env state (any time):

./exe/check_env.bash

To stop & clean up at any point, simply exit the sub-shell:

exit

<!-- TODO: Add more relevant link about bootstrap_env and dev_shell. -->

See [project_walkthrough.md][project_walkthrough.md] for more details.

Interactive demo: elaborated test data

While still in the started ["interactive demo"][interactive_demo] sub-shell:

• Try [request hotkeys][request_hotkeys] with lay command (which uses [demo test data][TD_63_37_05_36.demo_services_data.md]):

  lay goto                 # press `Alt+Shift+Q` to describe available options
  

  lay goto host            # press `Tab` one or multiple times
  

  lay goto host dev        # press `Alt+Shift+Q` to observe changes in the output
  

  If executed (press Enter), it runs stub implementations (in real app it would do remote ssh-login for example).

• Command lay goto binds to only one of the function.

  To see all bindings for lay command, run help function accessible via this command:

  lay help
  

  A lot of the functions are stubs and tests for demo purposes only.

<a id="argrelay-changes-to-code-and-data"></a>

Interactive demo: changes to code & data

The following ssh-related command is intentionally added to demo simple changes to code & data.

While still in the started ["interactive demo"][interactive_demo] sub-shell:

• For ssh wrapper example, try lay ssh or ar_ssh commands:

  Note that this is an example when the same function is bound to more than one command.

  lay ssh                  # press `Alt+Shift+Q` to describe available options
  ar_ssh                   # press `Alt+Shift+Q` to describe available options
  

• Modify code or data (or both) in the files below.

  This ssh-wrapper function uses:

  • Data from [ConfigOnlyLoader.ssh_dst_group.data.yaml][ssh_loder_data].
  • Code from [DelegatorSshDst.py][ssh_delegator_code].

• Restart ["interactive demo"][interactive_demo] and try lay ssh or ar_ssh command again to see the changes.

You may apply many examples from [the_problem_argrelay_solves.md][the_problem_argrelay_solves.md] to this ssh-wrapper.

<a id="argrelay-data-access"></a>

Interactive demo: browse and replace server data

Data is accessed by snapshots.

Snapshot does not need to include entire i