{"id":13557310,"url":"https://github.com/JOJ0/synadm","last_synced_at":"2025-04-03T11:31:39.253Z","repository":{"id":37989764,"uuid":"306554592","full_name":"JOJ0/synadm","owner":"JOJ0","description":"Command line admin tool for Synapse (the Matrix reference homeserver)","archived":false,"fork":false,"pushed_at":"2024-10-24T19:55:06.000Z","size":669,"stargazers_count":185,"open_issues_count":17,"forks_count":25,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-10-25T00:02:51.176Z","etag":null,"topics":["api-client","matrix","python3","synapse"],"latest_commit_sha":null,"homepage":"https://synadm.readthedocs.io","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/JOJ0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"2020-10-23T07:00:14.000Z","updated_at":"2024-10-24T19:55:10.000Z","dependencies_parsed_at":"2023-10-02T12:08:49.827Z","dependency_job_id":"8e28578e-3a48-4d43-9f40-dd300b496552","html_url":"https://github.com/JOJ0/synadm","commit_stats":{"total_commits":541,"total_committers":24,"mean_commits":"22.541666666666668","dds":"0.23475046210720885","last_synced_commit":"bda3057d9b13c4829ee4f6257962dc98d978edaa"},"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JOJ0%2Fsynadm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JOJ0%2Fsynadm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JOJ0%2Fsynadm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JOJ0%2Fsynadm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JOJ0","download_url":"https://codeload.github.com/JOJ0/synadm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246353002,"owners_count":20763579,"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":["api-client","matrix","python3","synapse"],"created_at":"2024-08-01T12:04:16.291Z","updated_at":"2025-04-03T11:31:39.232Z","avatar_url":"https://github.com/JOJ0.png","language":"Python","funding_links":[],"categories":["Python","python3"],"sub_categories":[],"readme":"\u003c!-- omit in toc --\u003e\n# synadm - the Synapse Admin CLI\n\n- [About](#about)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [Getting an Admin Token](#getting-an-admin-token)\n  - [The configurator](#the-configurator)\n  - [matrix-docker-ansible-deploy](#matrix-docker-ansible-deploy)\n- [Usage](#usage)\n  - [Command Line Reference](#command-line-reference)\n  - [Advanced Usage](#advanced-usage)\n- [Update](#update)\n  - [Update PyPI Package](#update-pypi-package)\n  - [Update git Installation](#update-git-installation)\n- [Implementation Status / Commands List](#implementation-status--commands-list)\n- [Get in Touch](#get-in-touch)\n- [Contributing](#contributing)\n\n\n## About\n\nA CLI tool to help admins of [Matrix-Synapse homeservers](https://github.com/matrix-org/synapse) conveniently issue commands available via its [Admin API](https://element-hq.github.io/synapse/develop/usage/administration/admin_api/index.html#the-admin-api).\n\n\n## Prerequisites\n\n- Python 3.6+\n- a running Synapse instance\n- an admin-enabled user on the instance\n- the admin user's access token\n\n`synadm` is designed to run either directly on the host running the Synapse instance or on a remote machine able to access Synapse's API port. Synapse's default Admin API endpoint address usually is http://localhost:8008/_synapse/admin or https://localhost:8448/_synapse/admin.\n\n\n## Installation\n\nIf `pipx` is available on your operating system, it is the recommended method for installation:\n\n`pipx install synadm`\n\nAlternatively, regular `pip` can also be used:\n\n`pip3 install synadm`\n\nTo install the latest version from Git to a Python virtual environment [see the chapter in the contributing docs](https://synadm.readthedocs.io/en/latest/contributing.html#getting-the-source-and-installing).\n\n\n## Configuration\n\n`synadm` stores its configuration inside the executing user's home directory in `~/.config/synadm.yaml` and is handled by [the synadm configurator](#the-configurator). Usually it's not required to edit it manually.\n\n### Getting an Admin Token\n\nTo find out your admin user's token in Element-Web: _Login as this user - \"Click User Avatar\" - \"All Settings\" - \"Help \u0026 About\" - Scroll down - \"Advanced\" - \"Access Token\"_\n\nOr use synadm to fetch a token already. Use the fully qualified Matrix ID of the admin user:\n\n```\nsynadm matrix login @admin_username:yourdomain.org\nPassword:\n```\n\nIf you issue this command in a fresh `synadm` installation, [the configurator](#the-configurator) will launch anyway.\n\n- Answer the questions.\n- Set token to \"invalid\" at first, to convience `synadm` to launch the `matrix login` command (otherwise you'd get a \"Configuration incomplete\" error).\n- After successfully entering your admin password you will be presented a token which you can finally set by re-launching the configurator as described below.\n\n\n### The configurator\n\n`synadm` asks for necessary configuration items on first launch automatically. Also whenever new mandatory configuration items where added (eg after an update), the user will be prompted for missing items automatically.\n\nConfiguration can be changed any time by launching the configurator directly:\n\n```\nsynadm config\n```\n\nConfiguration will be saved in `~/.config/synadm.yaml`\n\n*Note: Be aware that once you configured `synadm`, your admin user's token is saved in the configuration file. On Posix compatible systems permissions are set to mode 0600, on other OS's it is your responsibilty to change permissions accordingly.*\n\n### matrix-docker-ansible-deploy\n\nTo use `synadm` with Synapse homeservers that were installed using [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy) you have two options.\n\nAccess the Synapse Admin API's \"via the public endpoint\" similar to a Matrix client.\n\n- In [vars.yaml](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md#configuring-the-ansible-playbook) set `matrix_nginx_proxy_proxy_matrix_client_api_forwarded_location_synapse_admin_api_enabled: true`.\n- The API's are accessible on the Client-Server API port, at `https://matrix.DOMAIN`.\n- Install `synadm` on your Docker host or on a separate machine.\n- Configure `synadm` to access at `https://matrix.DOMAIN:443/_synapse/admin`\n\nAlternatively, you can access the API's on the container network `matrix`.\n\n- Synapse is accessible via the hostname `matrix-synapse` resolved by the internal Docker DNS server.\n- The containers are connected internally via a network named `matrix` by default.\n- Start a container on that same network and install `synadm` into it.\n- Configure `synadm` to access at `http://matrix-synapse:8008/_synapse/admin` (http here, not https).\n\nFind some more details about the topic in [this issue post on the matrix-docker-ansible-deploy repo](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1846#issuecomment-1135516112).\n\n_Note that currently `synadm` is using a part of the Server-Server (Federation) API (`keys/v2/server`) to retrieve \"its own homeserver name\". This affects some of the `media` management commands. By default and also as the Matrix spec recommends, this API is not accessible via the Client-Server API port. We are working on a better solution to retrieve the own servername but as a workaround the `key` API's can be exposed by setting `matrix_synapse_http_listener_resource_names: [\"client\",\"keys\"]` in [vars.yaml](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md#configuring-the-ansible-playbook)._\n\nFind more details about the topic [here](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/1761#issuecomment-1101170229).\n\n\n## Usage\n\nUse the online help of the main command:\n\n```\nsynadm -h\n```\n\nand of the available subcommands:\n\n```\nsynadm version -h\nsynadm user -h\nsynadm room -h\n```\n\nYou even can spare the `-h` option, `synadm` will show some abbreviated help for the executed subcommand anyway. For example:\n\n```\nsynadm user\n```\nor\n```\nsynadm user details\n```\n\nwill show essential help for the particular subcommand right away.\n\n*Note: A list of currently available commands is found in chapter [implementation status / commands list](#implementation-status--commands-list)* as well as in the following chapter.\n\n### Command Line Reference\n\nA detailed [Command Line Reference](https://synadm.readthedocs.io/en/latest/index_cli_reference.html) can be found in `synadm's` readthedocs documentation.\n\n### Advanced Usage\n\nExamples of how `synadm` can be used in shell scripts and oneliners is\nprovided in the\n[Scripting Examples](https://synadm.readthedocs.io/en/latest/examples.html)\ndocs chapter.\n\n\n## Update\n\n### Update PyPI Package\n\n```\npip3 install synadm --upgrade\n```\n\n### Update git Installation\n\nTo update `synadm` to the latest development state, just update your git repo and reinstall:\n\n```\ncd synadm\ngit pull\npip install .\n```\n\n*Note: If you installed it to a Python venv, [activate it](CONTRIBUTING.md#3-set-up-a-python3-virtual-environment).*\n\n*Note: If you installed it in [editable mode](CONTRIBUTING.md#4-install-in-editable-mode) (or for development), you can spare the `pip install .` command - just `git pull` and you're done.*\n\n\n\n## Implementation Status / Commands List\n\nThe [API to CLI Mapping](https://synadm.readthedocs.io/en/latest/features.html) section of our documentation provides an overview of what `synadm` can do.\n\n\n## Get in Touch\n\nIf you need advice on using synadm, have a feature idea or would like to discuss anything else around `synadm`, get in touch via Matrix!\n\nWe are hanging around in the official support room for Synapse, [#synapse:matrix.org](https://matrix.to/#/#synapse:matrix.org). Usually you'll find `synadm` users there that might answer your questions already. If not, mentioning `synadm` will ping us with the help of Element's keyword notify feature and we'll try to get in touch.\n\nThe most direct way to reach synadm maintainers as well as seasoned users and Synapse admins is by joining [#synadm:peek-a-boo.at](https://matrix.to/#/#synadm:peek-a-boo.at).\n\nIf you are sure you've found a bug that was not already reported, certainly directly [opening an issue](https://codeberg.org/synadm/synadm/issues) is a valid option too. If unsure, ask in [#synadm:peek-a-boo.at](https://matrix.to/#/#synadm:peek-a-boo.at) first.\n\n\n\n## Contributing\n\nFirst of all, thanks for your interest in contributing to `synadm`! We appreciate any help, no matter if you are a programmer or a user. Both groups can do valuable things for the `synadm` project. We love providing a useful tool to fellow Synapse sysadmins but rely on contribution from the Synapse and Matrix community to keep `synadm` useful, current and stable.\n\nPlease review the [contributing docs](https://synadm.readthedocs.io/en/latest/contributing.html) for guidelines and help around the topic!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJOJ0%2Fsynadm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJOJ0%2Fsynadm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJOJ0%2Fsynadm/lists"}