| Name | shvcli JSON |
| Version |
0.8.0
JSON |
| download |
| home_page | None |
| Summary | Silicon Heaven CLI access application |
| upload_time | 2025-07-25 10:29:50 |
| maintainer | None |
| docs_url | None |
| author | Elektroline a.s. |
| requires_python | >=3.11 |
| license | MIT License
Copyright (c) 2023 Elektroline a.s.
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.
|
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
=====================================
Silicon Heaven CLI access application
=====================================
.. image:: https://gitlab.com/silicon-heaven/shvcli/-/raw/master/logo.svg
:align: right
:height: 128px
This provides an easy to use CLI interfase to access the SHV network.
* `📃 Sources <https://gitlab.com/silicon-heaven/shvcli>`__
* `⁉️ Issue tracker <https://gitlab.com/silicon-heaven/shvcli/-/issues>`__
* `📕 Silicon Heaven protocol documentation <https://silicon-heaven.github.io/shv-doc/>`__
Installation
------------
The installation can be done with package manager ``pip``.
.. code-block:: console
$ pip install shvcli
Usage
-----
You need to start application ``shvcli``. The first argument is URL specifying
where client should connect to.
After successful connection you will see prompt (``>``) and you can start typing.
Methods can be called with ``PATH:METHOD`` syntax or with just ``METHOD``. You can
use ``PATH:`` for change current path prefix. This prefix is displayed before
prompt and is prefixed to any paths you specify on command line. To return to
the root you need to use absolute path (``/``).
An example of usage:
.. code-block:: console
> ls
.app
> dir
dir ls lschng
> .app:
.app> dir
dir ls lschng shvVersionMajor shvVersionMinor name version ping
.app> name
"pyshvbroker"
.app> broker:ls
currentClient client clientInfo
.app> ls broker
currentClient client clientInfo
.app> broker/currentClient:info
{"clientId":0,"mountPoint":null,"subscriptions":[],"userName":"admin"}
.app> /:
>
.. TIP::
The validation that is performed by SHVCLI is best effort and sometimes you
might need to submit call that is considered invalid by SHVCLI. For that
reason you can use `Ctrl+o` shortcut instead of pressing enter key.
Configuration file
------------------
Tool reads configuration from files ``/etc/shvcli.toml`` and ``~/.shvcli.toml``.
They are in TOML file format and the following sections are supported:
**hosts**: That provides mapping from some name to RPC URL.
**hosts-shell**: That is same as **hosts** with exception that URL is passed
through your local Shell to expand any variables or command substitutions.
**option**: That allows you to set initial setting for runtime options. The
following options are available without any plugins:
* **vimode**: If Vi input mode should be used for command line input. The
default is ``false``.
* **autoget**: Automatically call getter methods and print received values when
listing nodes and methods (``ls`` and ``dir`` methods special handling).
* **autoprobe**: Completion process benefits from probing of the SHV nodes with
``ls`` and ``dir``, and to provide easier usage this can happen automatically
in background. This is what this option controls. It is ``true`` by default
but it might not be desirable in some cases, because this can generate a lot
of hidden traffic.
* **raw**: Controls if ``ls`` and ``dir`` methods are handled in a special way
as described later in this document. This special handling can be possibly
decremental if you are trying to debug something specific with these functions
and this provides a way to call them with any CPON to see what they provide.
Note that caching and discovery of the nodes will stop working once you are in
the raw mode and thus you will no longer get the advantage of that. The
default is ``false``.
* **debug**: Controls if internal debug messages are displayed. These messages
can give you idea of what shvcli is actually doing behind the wail but it can
be also overwhelming. The default is ``false``. It is beneficial to disable
the **autobrobe** once you enable debug because otherwise output on CLI will
be mangled on completion.
* **call_query_timeout**: Timeout in seconds for status request query. The
shorter time will result in faster request lost detection while very short
time will load SHV network too much.
* **call_retry_timeout**: Timeout in seconds when call request is sent again if
no response is received. This is not applied if query is and thus this mostly
is used only in case when method doesn't support delayed responses.
* **autoget_timeout**: Timeout in seconds for call that is part of autoget
functionality.
* **history_count**: Integer number used for number of records requested at time
for ``!history`` builtin.
Example configuration file:
.. code-block:: ini
[hosts]
localhost = tcp://test@localhost?password=test
[hosts-shell]
company = tcp://smith@company.example.org?password=$(pass company/shv)
[config]
vimode = true
Internal methods
----------------
CLI provides few additional methods that can be called on top of the ones
provided by SHV network. They are all prefixed with ``!`` to clearly distinguish
them. They provide a way to control CLI as well as to get insight into the
environment you are running in.
**subscribe|sub**: Add new subscribe. Shortcut to the call of
``.app/broker/currentClient:subscribe`` that accepts arguments in more convenient
way. The argument can be multiple RPC RIs (``PATH:METHOD:SIGNAL`` patterns).
**unsubscribe|usub**: Unsubscribe existing subscription. It is reverse operation
to the **subscribe** and same remarks apply here as well. It is a shortcut to
the call of ``.app/broker/currentClient:unsubscribe``
**subscriptions|subs**: List current subscriptions. This is shortcut to call
``.app/broker/currentClient:subscriptions``.
**cd**: Change current path prefix to given one even when there is no such node.
**tree|t**: This prints tree of known nodes from current path prefix. This is
not all nodes present in the SHV network. This is only what was discovered so
far (and cached thus it can be also old). You can use it to visualize the tree
of nodes you are working with as well as to get insight into the state of the
cache.
**scan[X]**: Perform recursive probing of the tree up to the depth given as `X`
(the default is 3). On big servers this can be pretty resource demanding and
thus use it sparely.
**set|s**: allows modification of configuration option in runtime. The names
are the same as in ``config`` section. The boolean options are set if no
argument is provided, or cleared if name is prefixed with ``no`` (and thus to
disable ``raw`` you use ``noraw``). You can also add ``=true`` or ``=false``.
The equal sign is also used with integer and floating point options. Without any
configuration option it simply prints the current configuration.
**upload**: provides a way to copy local file to the RPC File node. The
parameter must be path to the local file to be uploaded.
**download**: provides a way to copy RPC File node data to local file. The
parameter must be path to the local file where data will be stored.
**verify**: provides a way to verify RPC File node against local file. The
parameter must be path to the local file used for the verification.
**history**: is helper to list recorded history of signals by ``.history`` API.
The listing is incremental in ``history_count`` configured number of records and
in the order from the newest ones.
Special methods ``ls`` and ``dir``
----------------------------------
These methods are handled in a special way to allow easy discovery of the SHV
nodes. Their output is processed and displayed in easy to read format but not in
the fullest content.
Their parameter is also handled in a special way. It is considered to be
additional path suffix unless it is a valid CPON. This is allowed to match the
common shells.
You can see ``raw`` option to disable this behavior.
OAuth2 login
------------
SHVCLI supports non-standard login method OAuth2. This is not defined by SHV
standard. The non-standard URL query ``oauth2=y`` is accepted to perform the
OAuth2 login. The login is facilitated by web browser. SHVCLI will start server
on ``tcp://localhost:37719/`` to be able to receive token.
Plugins
-------
The support for external plugins is provided. These plugins are discovered using
Python package metadata using the entry point ``shvcli.plugins``.
Raw data
{
"_id": null,
"home_page": null,
"name": "shvcli",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": null,
"author": "Elektroline a.s.",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/58/8f/2e27533f00e5ee11ab6af2b326a8a651f6228f830dc79f42987a4364d5fe/shvcli-0.8.0.tar.gz",
"platform": null,
"description": "=====================================\nSilicon Heaven CLI access application\n=====================================\n.. image:: https://gitlab.com/silicon-heaven/shvcli/-/raw/master/logo.svg\n :align: right\n :height: 128px\n\nThis provides an easy to use CLI interfase to access the SHV network.\n\n* `\ud83d\udcc3 Sources <https://gitlab.com/silicon-heaven/shvcli>`__\n* `\u2049\ufe0f Issue tracker <https://gitlab.com/silicon-heaven/shvcli/-/issues>`__\n* `\ud83d\udcd5 Silicon Heaven protocol documentation <https://silicon-heaven.github.io/shv-doc/>`__\n\n\nInstallation\n------------\n\nThe installation can be done with package manager ``pip``.\n\n.. code-block:: console\n\n $ pip install shvcli\n\n\nUsage\n-----\n\nYou need to start application ``shvcli``. The first argument is URL specifying\nwhere client should connect to.\n\nAfter successful connection you will see prompt (``>``) and you can start typing.\nMethods can be called with ``PATH:METHOD`` syntax or with just ``METHOD``. You can\nuse ``PATH:`` for change current path prefix. This prefix is displayed before\nprompt and is prefixed to any paths you specify on command line. To return to\nthe root you need to use absolute path (``/``).\n\nAn example of usage:\n\n.. code-block:: console\n\n > ls\n .app\n > dir\n dir ls lschng\n > .app:\n .app> dir\n dir ls lschng shvVersionMajor shvVersionMinor name version ping\n .app> name\n \"pyshvbroker\"\n .app> broker:ls\n currentClient client clientInfo\n .app> ls broker\n currentClient client clientInfo\n .app> broker/currentClient:info\n {\"clientId\":0,\"mountPoint\":null,\"subscriptions\":[],\"userName\":\"admin\"}\n .app> /:\n >\n\n.. TIP::\n The validation that is performed by SHVCLI is best effort and sometimes you\n might need to submit call that is considered invalid by SHVCLI. For that\n reason you can use `Ctrl+o` shortcut instead of pressing enter key.\n\n\nConfiguration file\n------------------\n\nTool reads configuration from files ``/etc/shvcli.toml`` and ``~/.shvcli.toml``.\nThey are in TOML file format and the following sections are supported:\n\n**hosts**: That provides mapping from some name to RPC URL.\n\n**hosts-shell**: That is same as **hosts** with exception that URL is passed\nthrough your local Shell to expand any variables or command substitutions.\n\n**option**: That allows you to set initial setting for runtime options. The\nfollowing options are available without any plugins:\n\n* **vimode**: If Vi input mode should be used for command line input. The\n default is ``false``.\n* **autoget**: Automatically call getter methods and print received values when\n listing nodes and methods (``ls`` and ``dir`` methods special handling).\n* **autoprobe**: Completion process benefits from probing of the SHV nodes with\n ``ls`` and ``dir``, and to provide easier usage this can happen automatically\n in background. This is what this option controls. It is ``true`` by default\n but it might not be desirable in some cases, because this can generate a lot\n of hidden traffic.\n* **raw**: Controls if ``ls`` and ``dir`` methods are handled in a special way\n as described later in this document. This special handling can be possibly\n decremental if you are trying to debug something specific with these functions\n and this provides a way to call them with any CPON to see what they provide.\n Note that caching and discovery of the nodes will stop working once you are in\n the raw mode and thus you will no longer get the advantage of that. The\n default is ``false``.\n* **debug**: Controls if internal debug messages are displayed. These messages\n can give you idea of what shvcli is actually doing behind the wail but it can\n be also overwhelming. The default is ``false``. It is beneficial to disable\n the **autobrobe** once you enable debug because otherwise output on CLI will\n be mangled on completion.\n* **call_query_timeout**: Timeout in seconds for status request query. The\n shorter time will result in faster request lost detection while very short\n time will load SHV network too much.\n* **call_retry_timeout**: Timeout in seconds when call request is sent again if\n no response is received. This is not applied if query is and thus this mostly\n is used only in case when method doesn't support delayed responses.\n* **autoget_timeout**: Timeout in seconds for call that is part of autoget\n functionality.\n* **history_count**: Integer number used for number of records requested at time\n for ``!history`` builtin.\n\nExample configuration file:\n\n.. code-block:: ini\n\n [hosts]\n localhost = tcp://test@localhost?password=test\n\n [hosts-shell]\n company = tcp://smith@company.example.org?password=$(pass company/shv)\n\n [config]\n vimode = true\n\n\nInternal methods\n----------------\n\nCLI provides few additional methods that can be called on top of the ones\nprovided by SHV network. They are all prefixed with ``!`` to clearly distinguish\nthem. They provide a way to control CLI as well as to get insight into the\nenvironment you are running in.\n\n**subscribe|sub**: Add new subscribe. Shortcut to the call of\n``.app/broker/currentClient:subscribe`` that accepts arguments in more convenient\nway. The argument can be multiple RPC RIs (``PATH:METHOD:SIGNAL`` patterns).\n\n**unsubscribe|usub**: Unsubscribe existing subscription. It is reverse operation\nto the **subscribe** and same remarks apply here as well. It is a shortcut to\nthe call of ``.app/broker/currentClient:unsubscribe``\n\n**subscriptions|subs**: List current subscriptions. This is shortcut to call\n``.app/broker/currentClient:subscriptions``.\n\n**cd**: Change current path prefix to given one even when there is no such node.\n\n**tree|t**: This prints tree of known nodes from current path prefix. This is\nnot all nodes present in the SHV network. This is only what was discovered so\nfar (and cached thus it can be also old). You can use it to visualize the tree\nof nodes you are working with as well as to get insight into the state of the\ncache.\n\n**scan[X]**: Perform recursive probing of the tree up to the depth given as `X`\n(the default is 3). On big servers this can be pretty resource demanding and\nthus use it sparely.\n\n**set|s**: allows modification of configuration option in runtime. The names\nare the same as in ``config`` section. The boolean options are set if no\nargument is provided, or cleared if name is prefixed with ``no`` (and thus to\ndisable ``raw`` you use ``noraw``). You can also add ``=true`` or ``=false``.\nThe equal sign is also used with integer and floating point options. Without any\nconfiguration option it simply prints the current configuration.\n\n**upload**: provides a way to copy local file to the RPC File node. The\nparameter must be path to the local file to be uploaded.\n\n**download**: provides a way to copy RPC File node data to local file. The\nparameter must be path to the local file where data will be stored.\n\n**verify**: provides a way to verify RPC File node against local file. The\nparameter must be path to the local file used for the verification.\n\n**history**: is helper to list recorded history of signals by ``.history`` API.\nThe listing is incremental in ``history_count`` configured number of records and\nin the order from the newest ones.\n\n\nSpecial methods ``ls`` and ``dir``\n----------------------------------\n\nThese methods are handled in a special way to allow easy discovery of the SHV\nnodes. Their output is processed and displayed in easy to read format but not in\nthe fullest content.\n\nTheir parameter is also handled in a special way. It is considered to be\nadditional path suffix unless it is a valid CPON. This is allowed to match the\ncommon shells.\n\nYou can see ``raw`` option to disable this behavior.\n\n\nOAuth2 login\n------------\n\nSHVCLI supports non-standard login method OAuth2. This is not defined by SHV\nstandard. The non-standard URL query ``oauth2=y`` is accepted to perform the\nOAuth2 login. The login is facilitated by web browser. SHVCLI will start server\non ``tcp://localhost:37719/`` to be able to receive token.\n\n\nPlugins\n-------\n\nThe support for external plugins is provided. These plugins are discovered using\nPython package metadata using the entry point ``shvcli.plugins``.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2023 Elektroline a.s.\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "Silicon Heaven CLI access application",
"version": "0.8.0",
"project_urls": {
"repository": "https://gitlab.com/silicon-heaven/shvcli"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6114bdb1947a6225ed4059576b13a8534e5a7ca5a0f238a7902cc7ab93035562",
"md5": "de68eb27e3f4faa1329ca0a4cbcbb54d",
"sha256": "d3443141070541c49a34df41a26b4eb24c106179381c44ca06319b543d68ed62"
},
"downloads": -1,
"filename": "shvcli-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "de68eb27e3f4faa1329ca0a4cbcbb54d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 43734,
"upload_time": "2025-07-25T10:29:48",
"upload_time_iso_8601": "2025-07-25T10:29:48.739176Z",
"url": "https://files.pythonhosted.org/packages/61/14/bdb1947a6225ed4059576b13a8534e5a7ca5a0f238a7902cc7ab93035562/shvcli-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "588f2e27533f00e5ee11ab6af2b326a8a651f6228f830dc79f42987a4364d5fe",
"md5": "7f4f0e166e8026a3b8169720f9858b16",
"sha256": "fa69d018555dee764cbcc5ee230b63818424b1cbc2653d863615fd8a36502072"
},
"downloads": -1,
"filename": "shvcli-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "7f4f0e166e8026a3b8169720f9858b16",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 36662,
"upload_time": "2025-07-25T10:29:50",
"upload_time_iso_8601": "2025-07-25T10:29:50.656349Z",
"url": "https://files.pythonhosted.org/packages/58/8f/2e27533f00e5ee11ab6af2b326a8a651f6228f830dc79f42987a4364d5fe/shvcli-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 10:29:50",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "silicon-heaven",
"gitlab_project": "shvcli",
"lcname": "shvcli"
}
