{"id":16993616,"url":"https://github.com/unbekanntes-pferd/dccmd","last_synced_at":"2025-10-09T09:31:19.983Z","repository":{"id":39049742,"uuid":"477837196","full_name":"unbekanntes-pferd/dccmd","owner":"unbekanntes-pferd","description":"dccmd (DRACOON Commander) – a CLI client for DRACOON (https://dracoon.com)","archived":true,"fork":false,"pushed_at":"2025-02-05T09:42:02.000Z","size":144,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-22T05:26:32.813Z","etag":null,"topics":["cli","client","dracoon"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unbekanntes-pferd.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":"2022-04-04T19:04:52.000Z","updated_at":"2025-02-05T09:42:35.000Z","dependencies_parsed_at":"2024-01-28T15:47:19.057Z","dependency_job_id":"ec567912-2440-4c89-ac5f-425cc6542569","html_url":"https://github.com/unbekanntes-pferd/dccmd","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/unbekanntes-pferd/dccmd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unbekanntes-pferd","download_url":"https://codeload.github.com/unbekanntes-pferd/dccmd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unbekanntes-pferd%2Fdccmd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001135,"owners_count":26083022,"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","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","client","dracoon"],"created_at":"2024-10-14T03:43:36.499Z","updated_at":"2025-10-09T09:31:19.977Z","avatar_url":"https://github.com/unbekanntes-pferd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eDRACOON Commander\u003c/h1\u003e\n\n\u003cdiv style=\"background-color: #fff3cd; border-left: 4px solid #f1c40f; padding: 1em; border-radius: 4px; margin: 1em 0;\"\u003e\n  \u003cstrong\u003e⚠️ This project is archived\u003c/strong\u003e\n  \u003cp\u003eThis project does no longer receive any updates. If you are looking for a CLI tool for DRACOON with similar capabilities, use `dccmd-rs`.\u003c/p\u003e\n   Check out \u003ca href=\"https://github.com/unbekanntes-pferd/dccmd-rs\" target=\"_blank\" rel=\"noopener noreferrer\"\u003edccmd-rs\u003c/a\u003e.\n\u003c/div\u003e\n\n\n## Table of Contents\n\n* [About the Project](#about-the-project)\n  * [Built With](#built-with)\n* [Getting Started](#getting-started)\n  * [Prerequisites](#prerequisites)\n  * [Installation](#installation)\n* [Usage](#usage)\n* [Configuration](#configuration)\n* [License](#license)\n\n\n## About the project\n_Disclaimer: This is an unofficial client and is not supported by DRACOON._\u003cbr\u003e\nThis client is a CLI tool to perform basic commands in DRACOON and comes with the following functionalities:\n\n* Full support for S3 direct up- / download\n    * Chunked up- and downloads\n* Full support for DRACOON end-to-end encryption\n* Optimized for concurrent requests\n* Store credentials in OS-specific secure location\n    * Linux: Freedesktop Secret Service (secretstorage)\n    * macOS: Keychain\n    * Windows: Windows Credential Locker\n\n### Built With\n* [typer](https://typer.tiangolo.com)\n* [keyring](https://pypi.org/project/keyring)\n* [dracoon](https://github.com/unbekanntes-pferd/dracoon-python-api)\n    * [httpx](https://www.python-httpx.org/)\n* [poetry](https://python-poetry.org/)\n\nA full dependency list can be viewed in\n* [pyproject.toml](/pyproject.toml) - list of dependencies and project info\n* [poetry.lock](/poetry.lock)\n\nDRACOON Commander is built with typer as the CLI framework and uses keyring to store all credentials (OAuth2 tokens, client credentials and encryption password). \nThe tool is built on top of dracoon, an async API wrapper for DRACOON based on httpx.\nThe project is managed with poetry (dependencies, release build and publishing).\n\n## Getting Started\nIn order to get started, download the latest tarball from Github or install dccmd from pip:\n[Releases]()\n\n### Prerequisites\nYou need a working Python 3.10 installation – dccmd makes use of type annotations and uses 3.10 features.\nGet the latest Python version from: [python.org](https://python.org).\n\n```bash\npython3 --version\n```\n\nIn order to get going, you can install dccmd either in a virtual environment or globally.\n\n### Installation\n\nTo install a version, use `pip` and install the `dccmd` package.\n\n#### In a virtual environment\n```bash\nvirtualenv \u003cDIR\u003e\nsource \u003cDIR\u003e/bin/activate \npython3 -m pip install dccmd\n```\n#### Globally\n```bash\npython3 -m pip install dccmd\n```\n\n#### Set PATH\nIn order for the script to work, you might need to add the relevant script path to your PATH.\nWhen installing with pip, the output will already indicate if the path is present or not.\nIf you do not add the correct directory to PATH, you will *not* be able to use the `dccmd` command in your preferred shell.\n\n##### Windows\nIn Windows, just add the script path by editing the environment variables for your account:\nLook for an entry called 'Path' and install the script directory from the `pip install` output.\n\n##### Unix\nOn Linux or macOS you can add a path to PATH by using the following command:\u003cbr\u003e\n`export PATH=\"/your/directory/see/install/output:$PATH\"`\u003cbr\u003e\n\n\n## Usage\n\n### Display commands\n\nIn order to see all available commands, arguments and options, use the --help flag:\n```bash\ndccmd --help\n```\n\n```\nUsage: dccmd [OPTIONS] COMMAND [ARGS]...\n\nOptions:\n  --install-completion [bash|zsh|fish|powershell|pwsh]\n                                  Install completion for the specified shell.\n  --show-completion [bash|zsh|fish|powershell|pwsh]\n                                  Show completion for the specified shell, to\n                                  copy it or customize the installation.\n  --help                          Show this message and exit.\n\nCommands:\n  auth\n  client\n  crypto\n  download  Download a file from DRACOON by providing a source path and a...\n  ls        List all nodes in a DRACOON path\n  mkdir     Create a folder in a DRACOON parent path\n  mkroom    Create a room (inherit permissions) in a DRACOON parent path\n  rm        Delete a file / folder / room in DRACOON\n  upload    Upload a file into DRACOON by providing a source path and a...\n```\nAll commands display their own help message, e.g. \n`dccmd upload --help`.\n\n### Client registration and authentication\n\nBefore you can perform any command, you must authenticate and set up the client.\nIf you enter any command which requires authentication (e.g. `dccmd ls your.dracoon.domain.com/`), you will be prompted first for a client configuration:\n* client id\n* client secret\n\n#### Client \nBefore you can use `dccmd` you need to generate a client in your DRACOON instance (config manager role required).\n1. Create a client with a client id and client secret.\nPlease make sure you have the following settings active:\n* Authorization code \n* Redirect URI is set to `https://your.dracoon.domain.com/oauth/callback`\n* Optional: If you wish to use the CLI mode (enter password and username via CLI), you can activate password flow \n\n2. Copy client id and client secret and use any command (e.g. `dccmd ls your.dracoon.domain.com/`).\n\n3. Enter client id and client secret – the information will be securely stored in your OS-specific secret container.\n\n#### Authentication\nOnce the client is set up, you will receive a link to authenticate via OAuth2 authorization code flow – you will then receive a code which you need to enter into the terminal.\nWhen completed, you will be prompted to store credentials securely (OS-specific).\n\nAdditionally, you can skip the authorization code flow and provide credentials directly, e.g. for the `dccmd ls` command:\n\n```bash\ndccmd ls your-dracoon.domain.com/ --cli-mode username@mail.com topsecret123!\n```\n\n### Upload\n\n**Important: if you use Windows, you need to provide the path with '/' instead of '\\\\'!**\n\nYou can upload single files using the upload command:\n\n```bash\ndccmd upload /path/to/file.pdf your-dracoon.domain.com/\n```\nIn order to upload a directory, use the `--recursive` (`-r`) flag:\n\n```bash\ndccmd upload -r /path/to/folder your-dracoon.domain.com/\n```\n\n#### Conflict resolution\nIf you upload a file which already exists (based on file name), the upload will be rejected.\u003cbr\u003e \nIn order to force an overwrite, use the `--overwrite` flag:\n\n```bash\ndccmd upload /path/to/file.pdf your-dracoon.domain.com/ --overwrite\n```\n\nIf you wish to auto-rename the file if it already exists, use the `auto-rename`flag:\n\n```bash\ndccmd upload /path/to/file.pdf your-dracoon.domain.com/ --auto-rename\n```\n\n#### Advanced usage\nIf you upload folders recursively, you might encounter performance issues, specifically when uploading many small files. \nYou can therefore adjust concurrent file uploads via the `--velocity` (`-v`) flag:\n\n```bash\ndccmd upload -r /path/to/folder your-dracoon.domain.com/ -v 3\n```\nThe default value is 2 - it does not coincide with real request value.\u003cbr\u003e\nMaximum (although not recommended) value is 10. Entering higher numbers will result in max value use.\u003cbr\u003e\nMinimum value is 1 - this will not upload a folder per file but is the minimum concurrent request value. Entering lower numbers will result in min value use.\n\nIf you need to understand why uploads fail, you can also run the command using the `--debug` flag:\n\n```bash\ndccmd upload -r /path/to/folder your-dracoon.domain.com/ --debug\n```\n*Note: This will have impact on performance as the log will be streamed to terminal and the log level will be increased to DEBUG.*\n\n### Create folder\n\nIf you wish to create a folder, use the `mkdir` command:\n\n```bash\ndccmd mkdir your-dracoon.domain.com/parent/newfolder\n```\nJust enter the full new path to create a folder. \nYou will need *create* permission to do so.\n\n\n### Create room\n\nIf you wish to create a room, use the `mkroom` command:\n\n```bash\ndccmd mkroom your-dracoon.domain.com/parent/newroom\n```\nJust enter the full new path to create a room. \nThe room will be created as a room with inherited permissions from the parent.\nYou will need *manage* permission to do so.\n\nTo create a room on the root level ('/'), you need to provide an admin user using \nthe corresponding option (`-au` or `--admin-user`):\n\n```bash\ndccmd mkroom -au \"admin.username\" your-dracoon.domain.com/newroom\n```\n*Note: In order to use the username of an OIDC user, you need to escape the `\\`, meaning you need to enter multiple slashes like so: `OIDC\\\\\\user.name`*\n\nTo create a room on any level that does *not* inherit permissions, use the `-au` (`--admin-user`) flag and provide the room admin when creating the room as with root level rooms:\n\n```bash\ndccmd mkroom -au \"admin.username\" your-dracoon.domain.com/parent-room/newroom\n```\n\n### Delete node\n\nIf you wish to delete a node, use the `rm` command:\n\n```bash\ndccmd rm your-dracoon.domain.com/parent/somefile.pdf\n```\nIn order to delete a container (room, folder) you need to use the `--recursive` (`r`) flag:\n\n```bash\ndccmd rm your-dracoon.domain.com/parent/folder/to/delete\n```\n**Warning: Deleting rooms cannot be undone!**\n\n### List nodes\n\nIn order to list all nodes, use the `ls` command:\n\n```bash\ndccmd ls your-dracoon.domain.com/\n```\n*Note: In order to list the root node, you need to provide a trailing `/`*\nFor a specific container (room or folder), use the path:\n```bash\ndccmd ls your-dracoon.domain.com/your/room\n```\n\n#### Displaying additional information\nUsing the `ls` command by default only provides node names.\nIn order to display more information, use relevant flags:\n\n* Display all information (size, last updated, last update user): `--long` (`-l`)\n    * Display sizes in human readable format (B, KB..): `--human-readable` (`-h`)\n* Display node id: `--inode` (`-i`)\n\nExample displaying full information:\n\n```bash\ndccmd ls -h -i -l your-dracoon.domain.com/your/room\n```\n### Download\n\nTo download a file, use the `download` command:\n\n```bash\ndccmd download your-dracoon.domain.com/your/cool-file.mp4 /target/directory\n```\n\nTo download a room or a folder, use the `download` command with `--recursive` (`-r`) flag:\n\n```bash\ndccmd download -r your-dracoon.domain.com/your/cool-folder /target/directory\n```\n\n#### Advanced usage\nIf you download folders recursively, you might encounter performance issues, specifically when downloading many small files. \nYou can therefore adjust concurrent file uploads via the `--velocity` (`-v`) flag:\n\n```bash\ndccmd upload -r /path/to/folder your-dracoon.domain.com/ -v 3\n```\nThe default value is 2 - it does not coincide with real request value.\u003cbr\u003e\nMaximum (although not recommended) value is 10. Entering higher numbers will result in max value use.\u003cbr\u003e\nMinimum value is 1 - this will not download a folder per file but is the minimum concurrent request value. Entering lower numbers will result in min value use.\n\n### User operations\n\nYou can list, edit and import users with relevant `dccmd users` command:\n\n* csv-import  Add a list of users to DRACOON from a CSV file\n* ls          Get a list of users in DRACOON\n* rm          Delete a user\n\n#### Importing users\n\nYou can import users by using the `csv-import` command and providing a path to the csv file:\n\n```bash\ndccmd users csv-import /path/to/users.csv your-dracoon.domain.com/\n```\n\nThe csv file must contain a header and should include the following attributes:\n\n* first name\n* last name\n* email \n* login (optional)\n\nBy default, local users are created - if you want to import oidc users, you need pass the oidc config id:\n\n```bash\n#example with OIDC config 5\ndccmd users csv-import /path/to/users.csv your-dracoon.domain.com/ 5\n```\n\n#### Listing users\n\nYou can list all users using the `ls` command:\n\n```bash\ndccmd users ls your-dracoon.domain.com/\n```\n\nYou can get all users also as csv format by using the `--csv` flag:\n\n```bash\ndccmd users ls your-dracoon.domain.com/ --csv \u003e users.csv\n```\n\nTo find a user, you can pass a search string to search for either first name, last name or user name (search string applies to all):\n\n```bash\n# will return all users with either first name, last name or user name containing 'yourname'\ndccmd users ls your-dracoon.domain.com/ yourname\n```\n\n#### Deleting users\n\nYou can delete a user by providing the username:\n```bash\ndccmd users rm your-dracoon.domain.com/ user123\n```\n\n### Room permissions management\n\nFor an overview of the available commands use \n\n```bash\ndccmd rooms --help\n```\n\n#### List user / group permissions in a room\n\nTo list user permissions in a room, use the `list-users` command:\n\n```bash\ndccmd rooms list-users your-dracoon.domain.com/your-room\n```\nYou need minimum `read` permissions to list users.\n\nTo list group permissions in a room, use the `list-groups` command:\n\n```bash\ndccmd rooms list-groups your-dracoon.domain.com/your-room\n```\nYou need minimum `read` permissions to list groups.\n\nAs with other commands, you can use the `--csv` flag to get a csv export for the room\npermissions (users and groups).\n\n#### Add user / group to a room\n\nCurrently, the following templates are available:\n- read: read-only perrmissions for a room \n- edit: edit permissions for a room\n- admin: room admin permissions\n\nThe permissions coincide with the templates in use of the official DRACOON Web App.\n\nYou need `manage` permissions (room admin) to add users / groups.\n\nTo add a user, use the `add-user` command and provide the user and permission template (`-u` and `-p`):\n\n```bash\ndccmd rooms add-user -u \"user.name\" -p admin your-dracoon.domain.com/your-room\n```\n\nTo add a group, use the `add-group` command and provide the group and permission template (`-g` and `-p`):\n\n```bash\ndccmd rooms add-group -g \"group.name\" -p admin your-dracoon.domain.com/your-room\n```\n\n#### Remove user / group from a room\n\nYou need `manage` permissions (room admin) to remove users / groups.\n\nTo add a user, use the `remove-user` command and provide the user (`-u`):\n\n```bash\ndccmd rooms remove-user -u \"user.name\" your-dracoon.domain.com/your-room\n```\n\nTo add a group, use the `remove-group` command and provide the group (`-g`):\n\n```bash\ndccmd rooms remove-group -g \"group.name\" your-dracoon.domain.com/your-room\n```\n\n## Configuration / administration\n\nYou can view / manage the configuration for `dccmd` using the relevant commands:\n\n* `dccmd auth` - manage credentials\n    * `dccmd auth ls your.dracoon.domain.com` will display if a refresh token has been stored for the provided domain\n    * `dccmd auth rm your-dracoon.domain.com` will remove stored credentials for the provided domain\n* `dccmd client` - manage client\n    * `dccmd client register your.dracoon.domain.com` will start the registration process for a client and given domain\n    * `dccmd client ls your.dracoon.domain.com` will display client information for the provided domain\n    * `dccmd client rm your-dracoon.domain.com` will remove the stored client config for the provided domain\n* `dccmd crypto` - manage encryption\n    * `dccmd crypto ls your.dracoon.domain.com` will display if encryption password is stored for the provided domain\n    * `dccmd crypto rm your-dracoon.domain.com` will remove the encryption password for the provided domain\n    * `dccmd crypto distribute your-dracoon.domain.com/` will generate file keys available to distribute - if providing a specific path (`dccmd crypto distribute your-dracoon.domain.com/some/path`), only keys for provided parent room will be generated.\n\n### Logging \nWhen using a command, a log will be created in the current working directory.\nCurrently it is not possible to configure a default path for a log.\n\nYou can stream the log to stdout by using the `--debug` flag with any DRACOON-specific command (`upload`, `download`, `ls`, `rm`, `mkdir`, `mkroom`).\n\n\n## License\nDistributed under the Apache License. See [LICENSE](/LICENSE) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbekanntes-pferd%2Fdccmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funbekanntes-pferd%2Fdccmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funbekanntes-pferd%2Fdccmd/lists"}