{"id":19002330,"url":"https://github.com/rainu/mqtt-shell","last_synced_at":"2025-04-22T18:03:50.497Z","repository":{"id":57708263,"uuid":"367618615","full_name":"rainu/mqtt-shell","owner":"rainu","description":"A interactive shell-like command line interface (CLI) for MQTT written in Go.","archived":false,"fork":false,"pushed_at":"2023-05-03T14:32:39.000Z","size":182,"stargazers_count":20,"open_issues_count":2,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-29T17:24:14.011Z","etag":null,"topics":["cli","go","golang","mqtt","mqtt-client","shell"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rainu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-15T11:52:04.000Z","updated_at":"2024-06-26T18:41:59.000Z","dependencies_parsed_at":"2024-06-19T04:12:35.656Z","dependency_job_id":"998d4c17-0deb-44ab-81cf-22da8eb33a97","html_url":"https://github.com/rainu/mqtt-shell","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rainu%2Fmqtt-shell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rainu%2Fmqtt-shell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rainu%2Fmqtt-shell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rainu%2Fmqtt-shell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rainu","download_url":"https://codeload.github.com/rainu/mqtt-shell/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249283008,"owners_count":21243658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","go","golang","mqtt","mqtt-client","shell"],"created_at":"2024-11-08T18:14:40.336Z","updated_at":"2025-04-16T22:31:34.326Z","avatar_url":"https://github.com/rainu.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Go](https://github.com/rainu/mqtt-shell/actions/workflows/build.yml/badge.svg)](https://github.com/rainu/mqtt-shell/actions/workflows/build.yml)\n[![codecov](https://codecov.io/gh/rainu/mqtt-shell/branch/main/graph/badge.svg)](https://codecov.io/gh/rainu/mqtt-shell)\n[![Go Report Card](https://goreportcard.com/badge/github.com/rainu/mqtt-shell)](https://goreportcard.com/report/github.com/rainu/mqtt-shell)\n[![Go Reference](https://pkg.go.dev/badge/github.com/rainu/mqtt-shell.svg)](https://pkg.go.dev/github.com/rainu/mqtt-shell)\n# mqtt-shell\n\nA shell like command line interface for MQTT written in go. With it, you can easily subscribe and publish MQTT topics. \nIt is also possible to pass through the incoming messages to external applications. Such like piping in shells!\n\n![](./doc/example.gif)\n\nFeatures:\n* Colored output\n* Subscribe (multiple) MQTT topics\n* Publish messages to MQTT topic\n* Pipe the incoming messages to external applications\n* Command history (such like other shells)\n* Configuration support via yaml-files\n    * so you can use handle multiple environments easily\n* Macro support\n\n# Get the Binary\nYou can build it on your own (you will need [golang](https://golang.org/) installed):\n```bash\ngo build -a -installsuffix cgo ./cmd/mqtt-shell/\n```\n\nOr you can download the release binaries: [here](https://github.com/rainu/mqtt-shell/releases/latest)\n\nOr for Arch-Linux you can install the AUR-Package [mqtt-shell](https://aur.archlinux.org/packages/mqtt-shell/)\n```bash\nyay -S mqtt-shell\n```\n\n# Usage \n\nTo see all command options, simple type\n```bash\n./mqtt-shell -h\n\nUsage of ./mqtt-shell:\n  -b string\n        The broker URI. ex: tcp://127.0.0.1:1883\n  -c string\n        The ClientID (default \"mqtt-shell\")\n  -ca string\n        MQTT ca file path (if tls is used)\n  -cb value\n        This color(s) will not be used\n  -cmd value\n        The command(s) which should be executed at the beginning\n  -cs\n        Indicating that no messages saved by the broker for this client should be delivered (default true)\n  -e string\n        The environment which should be used\n  -ed string\n        The environment directory (default \"~/.config/mqtt-shell\")\n  -hf string\n        The history file path (default \"~/.config/mqtt-shell/.history\")\n  -hh\n        Show detailed help text\n  -m value\n        The macro file(s) which should be loaded (default [~/.config/mqtt-shell/.macros.yml])\n  -ni\n        Should this shell be non interactive. Only useful in combination with 'cmd' option\n  -p string\n        The password\n  -pq int\n        The default Quality of Service for publishing 0,1,2 (default 1)\n  -sp string\n        The prompt of the shell (default \"\\\\033[36m»\\\\033[0m \")\n  -sq int\n        The default Quality of Service for subscription 0,1,2\n  -u string\n        The username\n  -v    Show the version\n```\n\n## Setting files\n\nAll options can be written in separate environment files (one per environment) or for global settings in the `.global.yml` file.\nThese files must be stores inside the shell-config directory (`~/.config/mqtt-shell`).\n\n## Environment configurations\n\nYou can create yaml files where you can configure predefined configuration. This can be helpful for different MQTT environments.\nThis files must be stored in the environment directory (by default ~/.config/mqtt-shell/).\n\nFor example:\n```yaml\n# example.yml\n\nbroker: tls://127.0.0.1:8883\nca: /tmp/my.ca\nsubscribe-qos: 1\npublish-qos: 2\nusername: user\npassword:  secret\nclient-id: my-mqtt-shell\nclean-session: true\ncommands: \n  - sub #\nnon-interactive: false\nhistory-file: ~/.config/mqtt-shell/history\nprompt: \"\\033[36mmsh\u003e\\033[0m \"\nmacros:\n  my-macro:\n    description: Awesome description of my macro\n    arguments:\n      - message\n    commands:\n      - pub test $1\ncolor-blacklist:\n  - \"38;5;237\"\n```\n\n```bash\n$ ./mqtt-shell -e example\n```\n\n# multiline publishing\n\nIf you want to publish a multiline message to topic:\n```bash\npub test/topic \u003c\u003cEOF\nThis is\na multiline\nmessage\nEOF\n```\n\nThis is also useful if you don't want to handle argument escaping:\n```bash\npub test/topic \u003c\u003cEOF\n{\"key\": \"value\"}EOF\n```\n\n# command chaining\n\nOne powerful feature of this shell is to chain incoming messages to external applications. It works like the other unix shells:\n\nThis will pass through all incoming messages in topic **test/topic** to `grep`\n```bash\nsub test/topic | grep \"Message\"\n```\n\n## stderr forwarding\n\nIf you want to push stdout **and** stderr to the stdin of the next application:\n```bash\nsub test/topic | myExternalApplication |\u0026 grep \"Message\"\n```\n\n## long term applications\n\nNormally the external applications will be started on **each incoming Message**. If you want to stream all incoming messages\nto a single started application:\n```bash\nsub test/topic | grep \"Message\" \u0026\n```\n\n## file redirection\n\nIf you want to write all incoming messages into files:\n```bash\nsub test/topic \u003e\u003e /tmp/test.msg\n```\n\n### only last incoming message\n\nIf you want to write only the latest incoming message to file:\n```bash\nsub test/topic \u003e /tmp/last.msg\n```\n\n# Macros\n\nMacros can be a list of commands which should be executed. Or it can be a more complex but more powerful script. \nMacros can have their own arguments. They can be defined in the environment file (`~/.config/mqtt-shell/my-env.yml`), \nthe global settings (`~/.config/mqtt-shell/.global.yml`) or the global macro file (`~/.config/mqtt-shell/.macros.yml`)\n\n## Macros - list of commands\n```yaml\n# ~/.config/mqtt-shell/.macros.yml\n\nmy-macro:\n  description: Awesome description of my macro\n  arguments:\n    - message\n  varargs: true\n  commands:\n    - pub test $1\n```\n\nThen you can use it in the mqtt-shell:\n```bash\n\u003e sub test\n\u003e my-macro \"Message#1\" \"Message#2\"\ntest | Message#1\ntest | Message#2\n```\n\n## Macros - a complex script\n\nThe [golang text templating](https://pkg.go.dev/text/template) is used for the scripts. The macro arguments can be read\nby **Arg** following by the **number of the argument**. So for the first argument: **Arg1** and for the second **Arg2** and\nso on. \n\nFurthermore there are two custom functions available:\n\n| name | argument | description | example |\n|---|---|---|---|\n| exec | \u0026lt;cmdLine\u0026gt; | Run the given command and return the result. You can also use pipes! | exec \"date \u0026#124; cut -d\\  -f1\" |\n| log | \u0026lt;format string\u0026gt; [\u0026lt;argument\u0026gt;, ...] | Write the given content to the shell stdout. | log \"Argument#1: %s\" .Arg1 |\n\n```yaml\n# ~/.config/mqtt-shell/.macros.yml\n\nmy-macro:\n  description: Awesome description of my macro\n  arguments:\n    - message\n  varargs: true\n  script: |-\n    {{ log \"Publish to topic\" }}\n    pub test {{ .Arg1 }} {{ exec \"date\" }}\n```\n\nThen you can use it in the mqtt-shell:\n```bash\n\u003e sub test\n\u003e my-macro \"Message#1\" \"Message#2\"\ntest | Message#1 So 15. Aug 16:15:00 CEST 2021\ntest | Message#2 So 15. Aug 16:15:00 CEST 2021\n```\n\n# Color output\n\nThis shell is able to write colored output. Each time a new subscription is made, the messages for that subscription will have\na colored prefix. Each subscription (not topic!) should have an own color schema. Internally the shell will have a pool with\ncolor codes. Each time a new subscription was made, the next color will get from that pool. After the pool is exhausted, \nthe color choosing will start again. The color pool can be shown with the `color` command in the shell.\n\nIf you want to disable some colors, you have to put them in your yaml config file(s). Or use the option `-cb` for the current\nsession.\n\n## Why chained applications will not show any color?\n\nBecause the mqtt-shell itself will start the chained application, the application can not detect if it operates on a tty. \nSo normally the applications will think that their stdin is no tty. Most of the application have an option to force print\nthe color codes. For example grep:\n\n```bash\nsub test/topic | grep --color=always Message\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frainu%2Fmqtt-shell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frainu%2Fmqtt-shell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frainu%2Fmqtt-shell/lists"}