{"id":13783422,"url":"https://github.com/saadjsct/matrixcli","last_synced_at":"2025-05-11T19:30:50.689Z","repository":{"id":46835075,"uuid":"177016892","full_name":"saadjsct/matrixcli","owner":"saadjsct","description":"Command line matrix client","archived":false,"fork":false,"pushed_at":"2024-04-21T10:37:14.000Z","size":485,"stargazers_count":132,"open_issues_count":17,"forks_count":14,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-05-18T22:23:29.270Z","etag":null,"topics":["bot","chat","client","command-line","matrix","matrix-python-sdk","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saadjsct.png","metadata":{"files":{"readme":"README.org","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":"2019-03-21T20:12:18.000Z","updated_at":"2024-06-25T03:56:26.187Z","dependencies_parsed_at":"2024-06-25T03:56:25.365Z","dependency_job_id":"8ba8ea86-e754-468c-982c-020977d4257b","html_url":"https://github.com/saadjsct/matrixcli","commit_stats":null,"previous_names":["saadjsct/matrixcli","saadsolimanxyz/matrixcli"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saadjsct%2Fmatrixcli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saadjsct%2Fmatrixcli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saadjsct%2Fmatrixcli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saadjsct%2Fmatrixcli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saadjsct","download_url":"https://codeload.github.com/saadjsct/matrixcli/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224713624,"owners_count":17357247,"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":["bot","chat","client","command-line","matrix","matrix-python-sdk","python"],"created_at":"2024-08-03T19:00:21.140Z","updated_at":"2024-11-17T20:30:28.227Z","avatar_url":"https://github.com/saadjsct.png","language":"Python","readme":"#+TITLE: matrixcli: a minimal command line matrix client\n#+AUTHOR: saadnpq\n#+date: 2019-03-30 \n#+HUGO_BASE_DIR: ~/blog/ \n#+hugo_auto_set_lastmod: t\n#+EXPORT_FILE_NAME: matrixcli\n#+hugo_tags: projects\n\nmatrixcli is a simple [[https://matrix.org/blog/home/][matrix]] client based on the [[https://github.com/matrix-org/matrix-python-sdk][matrix-python-sdk]].\nif you wonder how this is useful please see [[https://github.com/saadnpq/matrixcli#applications][applications]]\n\n* installation\nyou can install matrixcli using setup.py in root project directory. \nThis will also install all needed dependencies.\n#+BEGIN_SRC shell\ngit clone https://github.com/saadnpq/matrixcli.git\ncd ./matrixcli \nsudo ./install.sh\n#+END_SRC\nthis will put the matrixcli script in your path, install a \ntemplate config.py file in /etc/matrixcli and systemd unit file in /lib/systemd/user\n\nfor ubuntu users you have to install python3-setuptools first before running the above commands\n#+begin_src shell\nsudo apt install python3-setuptools\n#+end_src\n\nto enable the systemd service you can run the following.\n#+begin_src shell\nsystemctl --user enable --now matrixcli\n#+end_src\n\n* configuration file\nthe account configuration is done through the config.py\nfile in either one of the following locations sorted by precedence\n\n1) custom file specified using the -c option\n1) $HOME/.config/matrixcli  \n1) /etc/matrixcli  \n\nthis is a one account sample configuration.\n#+begin_src python \ndef password_eval():\n    return \"Y0UrPredIctabLePA$$w0ord\"\n\naccounts=[{ \"server\":\"https://matrix.org/\",\n              \"username\":\"putYourUserNameHere\",\n              \"passeval\":password_eval }] \n\n# the password_eval function can be named any thing as long as \n# it matches the function definition \n\nignore_rooms = [\"room_id\", \"another_room_id\"] \n# note: room_id not room_alias (run matrixcli rooms to get the room_id)\n\n#+end_src \n\nthe configuration file should have an =accounts= variable which holds \na list of dictionaries where every dictionary consists of the account \ninformation server, username and password eval \n\nthe rationale behind defining a function that returns the password value\nis that if you don't want to write your password in plain text you can \nwrite any python code you wish that generates or reads the password from \nan encrypted file or a key ring\n\nthe ignore_rooms list contains rooms that you want to be ignored when \ncalculating unread messages and in listen mode \n\nif you don't want to make a configuration file at all, you can pass the server, username\nand password through command line arguments. see [[*usage][usage]]\n\n** multi account configuration \n\nsuppose you have the following configuration file\n#+begin_src python \ndef account1_password_eval():\n    return \"account1secretpassword\"\n\ndef account2_matrixorg_password_eval():\n    return \"account2secretpassword\"\n\ndef account3_password_eval_any_name():\n    return \"yXkdsjhslkjhdlksjhffffffkkssskjsdhkljhssdc\"\n\naccounts=[\n\n        { \"server\":\"https://example.com\",\n          \"username\":\"account1\",\n          \"passeval\":account1_password_eval },\n\n        { \"server\":\"https://matrix.org\",\n          \"username\":\"account2\",\n          \"passeval\":account2_matrixorg_password_eval},\n\n        { \"server\":\"https://example.com\",\n          \"username\":\"account3\",\n          \"passeval\":account3_password_eval_any_name },]\n\nignore_rooms = [\"room_id\", \"another_room_id\"] \n#+end_src \n\nif you didn't specify any command line option, the program will use the first\naccount in the accounts list. to use any other account its enough to \npass the -u or --username option to the command with the username of that account.\n\nfor example \n#+begin_src shell\nmatrixcli -u account3 getrooms\n#+end_src\nthat command will login with the parameters of the third account.\n\nif you have two or more accounts with the same username but with different servers.\nyou can specify the --server option to norrow down the possible accounts to the\naccount you want.\n\n* applications \nbelow are the ways i personally use matrixcli, \n\n** desktop notifications\nthe first motive to make this program was that i didn't want to keep \nriot webpage open or to run an electron app just for notifications.\n\nyou can enable the systemd service, to get notifications for events as they come.\n#+begin_src shell \nsystemctl --user enable --now matrixcli\n#+end_src\n\n[[file:screenshots/notifications.png]]\n\n** status bars\nusing =matrixcli unread= you write a module for any status bar\nto display unread messages. here is a simple example for polybar\n\n#+begin_src yaml\n[module/matrix]\ntype = custom/script\nexec = matrixcli unread -f 2\u003e /dev/null\ntail = true\ninterval = 30\nformat = \u003clabel\u003e\nlabel = M[%output%]\nformat-underline = #268bd2\n#+end_src \n\n** sendmail for matrix \nfor example i have this cron job that sends every day a random song\nfrom my music directory to a specific room.\n\n#+begin_src shell\n0 0 * * * /usr/local/bin/matrixcli send -r '!OSPeUVrwMKbIrLQuBX:matrix.org' $(tree /home/pi/musiqa -fi | grep \".*.mp3\" | shuf | sed 1q)\n#+end_src\n\nand i use it in many scripts on remote servers to notify me about a script output or just when something goes wrong.\n\n* how to use\nfor a list of the subcommands and options run \n#+begin_src shell\nmatrixcli --help \n#+end_src\noutput:\n#+begin_example\n#usage: matrixcli [-h] [-s SERVER] [-u USERNAME] [-p PASSWORD] [-c CONFIG]\n                 {send,listen,rooms,unread,tail} ...\n\ncommand line matrix client\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -s SERVER, --server SERVER\n                        server to login to\n  -u USERNAME, --username USERNAME\n                        username to login with\n  -p PASSWORD, --password PASSWORD\n                        the password\n  -c CONFIG, --config CONFIG\n                        custom configuration file\n\nsubcommands:\n  {send,listen,rooms,unread,tail}\n    send                send something to a room\n    listen              listen forever for events\n    rooms               get all joined rooms\n    unread              get unread notifications\n    tail                print last messages\n#+end_example\n\nto list the options of a specific sub command, (e.g. send)\n\n#+begin_src shell\nmatrixcli send --help \n#+end_src\n\n** rooms \nevery sub-command that supposed to act on a specific room accepts the \n-r/--room-id optional argument which takes the room-id to act upon, \nor -a/--room_alias which takes a room alias.\n\nto get a room-id of a room run: \n#+begin_src \nmatrixcli rooms\n#+end_src\noutputs the following (for my account).\n#+begin_example \nlogging in ....\nlogged in ....\n0 : momenamr : !ocOmULdomkoJWYzXts:matrix.org\n1 : mahmoudhafez : !fCXcmULzIohNQomvXD:saadnpq.com\n2 : Emacs Matrix Client : !ZrZoyXEyFrzcBZKNis:matrix.org\n3 : elm3alem zaki : !OaBjEnLTTVqGpqrPES:matrix.org\n4 : matrix-python-sdk : !YHhmBTmGBHGQOlGpaZ:matrix.org\n5 : Emacs : !PWxnIIDhCBAbNItsSN:matrix.org\n6 : moatazomar : !LsBUkYVYJignwCpACn:saadnpq.com\n#+end_example\n\nif you didn't specify the room-id or room-alias through the command line, the program will prompt you \nwith your joined rooms when it needs to. \n\n** listen\n#+begin_src shell\nmatrixcli listen\n#+end_src\nlistens forever for events and outputs incoming messages to both stdout\nand os notifications, if you are running this command on a headless system\nor the program failed to send notifications for some reason,\nit will output events only to stdout without complaining.\n\nyou can press C-c to quit the listen mode.\n\nthere is also a systemd service installed with the program that uses =matrixcli listen=,\nto enable it you can run the following.\n\n#+begin_src shell\nsystemctl --user enable --now matrixcli\n#+end_src \n\n** tail \nreturns the last n messages of a room.\n\n#+begin_src shell\nmatrixcli tail -h\n#+end_src\n\n#+begin_example \nusage: matrixcli tail [-h] [-r ROOM_ID | -a ROOM_ALIAS] [-f] [-n [1-100]]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -r ROOM_ID, --room-id ROOM_ID\n                        specify the room id\n  -a ROOM_ALIAS, --room-alias ROOM_ALIAS\n                        specify the room by room alias\n  -f, --follow          wait for messages and print them as they come\n  -n [1-100], --messages [1-100]\n                        print the last specified messages\n#+end_example\n\nthe option -f prints the last messages but wait for new messages\nand print them as they come.\n\nyou can also send messages while in follow mode by typing the message you want to send\nand hit enter to send it. \n\n** send\n#+begin_src shell\nmatrixcli send --help \n#+end_src\n#+begin_example\nusage: matrixcli send [-h] [-r ROOM_ID | -a ROOM_ALIAS] [-t | -f] content\n\npositional arguments:\n  content\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -r ROOM_ID, --room-id ROOM_ID\n                        specify the room id\n  -a ROOM_ALIAS, --room-alias ROOM_ALIAS\n                        specify the room by room alias\n  -t, --text            force the program to treat the content as text message\n  -f, --file            force the program to treat the content as a file\n#+end_example\n\nthe send command takes the content you want to send as a positional arguments, the program first\nsees if the passed text represent a file that exists in the filesystem, if so it will try to \nguess its MIME type based on the extension to correctly preview the content on the receiver's end. \nif the passed text does not represent any file on the filesystem the program will treat it as a text message.\n\nto force the program to treat the content as a file or a text you can specify the optional arguments --file or --text.  \n\n** unread\n\n#+begin_src shell\nmatrixcli unread --help \n#+end_src\n\n#+begin_example\nusage: matrixcli unread [-h] [-f] [-r ROOM_ID | -a ROOM_ALIAS]\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -f, --follow          don't close connection and print the number of unread\n                        messages whenever updated\n  -r ROOM_ID, --room-id ROOM_ID\n                        specify the room id\n  -a ROOM_ALIAS, --room-alias ROOM_ALIAS\n                        specify the room by room alias\n#+end_example\n\noutputs unread messages for room_id or all rooms (except those in ignore_rooms)\nif no room_id or room_alias specified\n\n","funding_links":[],"categories":["Clients","\u003ca name=\"chat\"\u003e\u003c/a\u003eChat and instant messaging"],"sub_categories":["CLI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaadjsct%2Fmatrixcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaadjsct%2Fmatrixcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaadjsct%2Fmatrixcli/lists"}